Using dashboard functions

You can use dashboard functions in order to perform calculations, filtering, formatting and other operations on correlator data. Scalar functions can be used when operating on a single variable of a single instance. Tabular functions can be used when operating on a table of correlator data. Where all correlator data is stored in dashboards or dashboard servers as tables, they are compatible with all tabular functions.

Using built-in functions

Following is an example of using a built-in function.

To use a built-in function

Open the file tutorial-function-sum.rtv by selecting Data Functions on the tutorial main page.

Here the value in the label at the bottom of the dashboard is the sum of the Position variables of each instance. To recreate this sample follow the following steps.
Open the file tutorial-summary-table.rtv by selecting Summary Table on the tutorial main page.
From the Tools menu, select the Functions item to display the Functions panel.
Click the Add button to display the Edit Function dialog.
Set the Function Name field to PositionTotal and the Function Type field to Add All Rows Or Columns.

For information on all built-in functions, see Dashboard function reference.
Right-click the Table field in the Edit Function dialog and attach it to Apama by specifying the information shown in the dialog shown below.

Here the attachment specifies that the Position column for the tutorial DataView is to be used. The Sum function will produce the sum of the values in all the cells of a given column; in this case the sum of the cells in the Position column for all instances.
Click OK in the Edit Functiondialog and close the Functions dialog.

The function PositionTotal has now been defined and object properties can be attached to it.
From the Labels tab in the Object Palette, select the second label object and add it to the dashboard canvas.
Select the label object and in the Object Property panel right click the valueString property and select Attach to Data | Function to display the Attach to Function Data dialog.
From the Function Name drop down list, select the PositionTotal function as follows:

The label object is now attached to the PositionTotal function and will display the sum of the Position variable for all instances.

For more information on the Functions panel and the Edit Function dialog, see Introduction to Dashboard Functions.

Dashboard Builder provides many functions for operating on data. These can be used to operate on an instance data to produce scalar results such as a sum. They can also be used to produce tabular results which can be displayed as tables or charts. It is also possible to chain functions where one function takes as its input value the output of another function. For more information, see the Dashboard Function Reference in Developing Apama Applications.

Apama also gives you the ability to define custom dashboard functions, as described in the next section.

Creating custom functions

To provide a library of functions

Develop an implementation of com.apama.dashboard.function.IFunctionLibrary. See Developing a custom-function library.
Install your implementation. See Installing a custom-function library.

Developing a custom-function library

Your implementation of IFunctionLibrary must implement the following methods:
getFunctionDescriptors: Creates a function descriptor for each function that the library supports; returns a list of com.apama.dashboard.function.IFunctionDescriptors. This method is called once at data server or display server startup. See Implementing getFunctionDescriptors.
evaluateFunction: Returns the result of executing a specified function with specified arguments. See Implementing evaluateFunction.

When you compile your implementation, ensure that ap-dashboard-client.jar is on your class path. This jar file is in the lib directory of your Apama installation.

Implementing getFunctionDescriptors

To create a function descriptor, use the factory class com.apama.dashboard.function.FunctionDescriptorFactory. Call createFunctionDescriptor, passing arguments that specify the following:

The function name that will be used by the Dashboard Builder and by the implementation of evaluateFunction
The argument names that will be used by the Dashboard Builder
The argument names that will be used by the implementation of evaluateFunction
The return type of the function (String, Double, Integer, or com.apama.dashboard.data.ITabularData)
The names of the returned columns, for functions that return table data
A text description of the function

Info

When you create a dashboard custom function you must specify prefixes for parameters according to the parameter type. A prefix must be s_arg for a String parameter, t_arg for a Table parameter or i_arg for an Integer parameter, for example, s_arg1,s_arg2.

Implementing evaluateFunction

Implement this method to evaluate a specified function with specified actual arguments. The function is specified with the function name. The arguments are specified with an instance of com.apama.dashboard.data.IVariableData.

For functions that return table data, use the factory class com.apama.dashboard.data.TabularDataFactory to create an instance of ITabularData.

When you compile your implementation, ensure that ap-dashboard-client.jar is on your class path. This jar file is in the lib directory of your Apama installation.

Your implementation of evaluateFunction can set or retrieve substitution values, if necessary, by using the following methods of DashboardManager and IDashboardContext:

DashoardManager.getFunctionDashboardContext: This static method takes as argument an instance of IVariableData and returns an instance of IDashboardContext. Pass the instance of IVariableData that is passed into evaluateFunction.
IDashboardContext.getSubstitutionValue: Gets the value of a substitution with a given name.
IDashboardContext.setSubstitution: Sets the value of a substitution with a given name.
IDashboardContext.setSubstitutions: Sets the values of substitutions, where the substitutions and values are specified with String vectors.

Each set method has a boolean argument, triggerUpdate, which controls whether objects attached to the substitution are updated. If it is false, they are not. If the substitutions are only used as command parameters or in drilldowns, you can improve performance by specifying false.

Here is an example:

IDashboardContext ctxt =
DashboardManager.getFunctionDashboardContext(v);
String val1 = ctxt.getSubstitutionValue("$subst1");
...
ctxt.setSubstitution("$subst2", "val2", false);

Installing a custom-function library

To install your function library for a given data server or display server, do both of the following:

Include a line in the data server or display server’s EXTENSIONS.ini file that specifies the fully qualified name of your IFunctionLibrary implementation. The line must have the following form:
```
function fully-qualified-classname
```
Create a jar file that contains your IFunctionLibrary implementation, and add it to APAMA_DASHBOARD_CLASSPATH (changes to this environment variable are picked up by dashboard processes only at process startup). You can also use the --dashboardExtraJars command line argument to specify this jar file.

A data server or display server’s EXTENSIONS.INI is, by default, located in the lib directory of its Apama installation. You can specify a data server or display server’s EXTENSIONS.ini file at startup by using the -X or --extensionFile option.

The EXTENSIONS.ini specifies the function library to use. This file identifies all the user supplied extension classes (including command libraries and scenario authorities). Here is a sample EXTENSIONS.ini:

function com.apama.dashboard.sample.SampleFunctionLibrary
command com.apama.dashboard.sample.SampleCommandLibrary
scenarioAuthority com.apama.dashboard.sample.SampleScenarioAuthority

This file installs a function library, a command library, and a scenario authority.