Frequently Asked Questions

What threading guarantees are provide in t he API?

Connections can be created and shared across threads.

Data callbacks are fired on a seperate thread and are consistent per stream. A callback for a given stream will not fire until the previous callback on that stream has returned.

How can I process Open Access data using multiple threads?

To process data from Open Access on multiple threads, push the data on to a queue from the callback and then read from the queue in worker threads that you create yourself.

The key is to block the Open Access callback for as little time as possible.

No commands are being returned from the API. How can I debug this?

The commands available through the API depend on gateway level authorisation. The Open Access cluster connects to the gateway using the username specified in Connecting to a Gateway.

On the gateway side, it is possible to configure each user with fine grained permissions on commands. This includes restricting visibility of that command completely as well as disabling execution. If the user cannot see or execute the command, the Open Access cluster cannot either.

Currently the way to verify which commands are available for a gateway user is to log in as that user using the ActiveConsole.

Why are there two ways of getting arguments - getArguments and getOrderedArguments?

When commands are published from the gateway, their arguments are provided to the Open Access Cluster as a list. We decided for Open Access 1.0 to adapt this to a map of argument name to argument definition.

This works for most commands in the system, however some have arguments with no name. Their functionality is inferred by their position in the list. For example, ‘Snooze for a specified time period’ has duration as the third parameter. The fourth parameter specifies whether the duration is hours, minutes or days.

Names for such arguments are automatically generated, however using these alone it was difficult to construct user interfaces that would make sense.

To fix the problem, an alternative accessor was added that returns the arguments in the order that they are sent from the gateway. Both ultimately return the same data, just in different arrangements.

You can pass arguments to CommandExecuteQuery using their index from the ordered arguments list:

CommandExecuteQuery query = CommandExecuteQuery.create("<path to item>", "<command id>");
query.putArgument(0, "<arg 1>");
query.putArgument(1, "<arg 2>");

However, most API consumers should use the named arguments map instead.

How can I get the column name of a cell that has been updated?

// Using DataViewTracker
DataView dataView = tracker.update(change);

if(change.getType() == DataViewChange.Type.CELL_UPDATE) {
    int colIx = change.getColumn();
    return dataView.getColumnHeaders().get(colIx);
}

How can I get a particular cell by row name or column name?

If you know you are interested in particular cells, consider using a DataSetQuery with an XPath matching those cells instead of a DataViewQuery matching the whole view. The solution using only a DataView is to perform a manual search.

String rowName = "testRow";
String colName = "testCol";
DataViewCell cell = null;
// Using DataViewTracker
DataView view = tracker.update(change);

int colIx = view.getColumnHeaders().indexOf(colName);
if(colIx == -1) {
    throw new IllegalArgumentException("Could not find column " + colName);
}

for(DataViewRow row : view.getRows()) {
    if(rowName.equals(row.getName())) {
        cell = row.getCells().get(colIx);
        break;
    }
}

if(cell == null) {
    throw new IllegalArgumentException("Could not find row");
}

How do I enable debug logging on an Open Access cluster node?

Modify config/logback.xml and set the root logging level to DEBUG:

...

<root level="DEBUG">
    <appender-ref ref="FILE" />
    <appender-ref ref="STDOUT" />
</root>

...

Modify config/application.conf to enable lower level Akka framework debugging:

akka.loglevel = DEBUG