Manipulating Variables

This section explains how to programmatically manipulate context variables.

There are several ways to get a list of variables from a Context:

• getVariableDefinitions() - this method will return the list of all variables in a context
• getVariableDefinitions(CallerController caller) - this method will return the list of variables accessible by the caller (either for reading or for writing)
• getVariableDefinitions(String group) - this method will return the list of variables belonging to the certain group or its subgroups
• getVariableDefinitions(CallerController caller, String group) - this method will return the list of variables belonging to the certain group and accessible by the caller

List<VariableDefinition> variables = context.getVariableDefinitions(ContextUtils.GROUP_REMOTE); // Finding all variables in group "remote"

To retrieve a single variable definition by its name call getVariableDefinition(String name) method. The method getVariableDefinition(String name, CallerController caller) will return a definition or null if variable is not accessible by caller.

The Context interface has two primary methods for manipulating variable values:

• getVariable()
• setVariable()

These methods allow to read and write context variable values respectively.

The getVariable() method reads variable value and returns a DataTable representing this value. It accepts one or two arguments: name of variable to read and optional instance of CallerController that incorporates permissions of calling side (see Dealing with Access Permissions for details).

Once the variable value table is obtained, you can access its data. See Manipulating Data Tables for details.

Here is an example of how to read variable value:

DataTable variableValue = context.getVariable("tabularVariable");

There are two primary ways to set a variable:

• By supplying a pre-built DataTable object. This object can be programmatically created from scratch or obtained via getVariable() call and modified.
• By supplying individual cell values.

Example 1 - setting variable value using a pre-built data table:

DataTable variableValue = new SimpleDataTable(context.getVariableDefinition("tabularVariable").getFormat()); // Creating empty value

variableValue.addRecord().addString("str1").addInt(111); // Adding a record
variableValue.addRecord().addString("str2").addInt(222); // Adding another one

context.setVariable("tabularVariable", variableValue); // Setting variable value

Example 2 - modifying previous variable value:

DataTable variableValue = context.getVariable("tabularVariable");

variableValue.addRecord().addString("str1").addInt(111); // Adding a record
variableValue.addRecord().addString("str2").addInt(222); // Adding another one

context.setVariable("tabularVariable", variableValue); // Setting variable value

Example 3 - setting variable value using a list of cell values:

context.setVariable("tabularVariable", "str1", 111); // Supplying cell values for the first record of new variable value

If you want to change just a single cell or record of variable value, it's not enough to read its value and modify the obtained DataTable. It's necessary to write modified value back to the source context by calling setVariable(). Simply speaking, any modification of variable requires setVariable() call.

There are two ways to access database-stored historical values of a variable:

• By calling variableHistory function from Utilities context. This method will work both locally (inside server drivers/plugins) and remotely (via server API).
• By calling ServerContextUtils.getVariableHistory() static Java method. This way is slightly faster than previous one, but it will work inside server JVM only (e.g. in drivers/plugins).

Full signature of ServerContextUtils.getVariableHistory() method:

public static Iterator<Pair<Date, DataTable>> getVariableHistory(ServerContextManager cm, CallerController caller, String context, String variable, Date fromDate, Date toDate, Integer maxResults, boolean sortAscending) throws DaoException

The variableHistory function of Utilities context returns a Data Table each row of that contains timestamp and historical value of the variable. See its description here.

DataTable history = utilsContext.callFunction(UtilitiesContextConstants.F_VARIABLE_HISTORY, getCallerController(), con.getPath(), vd.getName()); // Other parameters omitted

for (DataRecord rec : history)
{
// Process historical values
}

Static method of ServerContextUtils class that returns historical values of a variable has the following signature:

public static Map<Date, DataTable> getVariableHistory(CallerController caller, String context, String variable, Date fromDate, Date toDate, Integer maxResults, boolean sortAscending) throws DaoException, ContextException, DataTableException

It returns the map of timestamps indicating time when values were saved and the values themselves.

Interfaces located in com.tibbo.aggregate.common.server package provide string constants matching names of most server context variables and their fields.

Using those constants is always preferred to using string constants defined in your own code. This will ensure error-proof code if some variables or fields will get renamed or relocated in the future versions of Iotellect Server.

Was this page helpful?

Tell us more

Send

Thank you!