Actions

Actions allow you to expose functionality much more complex than simple reads and writes.

All actions subclass org.iot.dsa.node.action.DSAction. There are two methods to override:

 public abstract ActionResult invoke(DSInfo target, ActionInvocation request);

 public abstract void prepareParameter(DSInfo target, DSMap parameter);

Adding Actions

Actions can be added by overriding methods on DSNode.

DSNode.declareDefaults()

Actions on nodes can be declared defaults and they are the fastest to invoke. This mechanism uses more memory because an action will have a DSInfo in every instance of the node. If there will be many instances of a node, use virtual actions instead.

DSNode.getVirtualAction(s)

Virtual actions must be used to add actions to non-DSNode children, but they can also be used for DSNodes.

Virtual actions are not mounted in the node tree, therefore they use less memory. This can be very important on common nodes such as points. The one drawback is that the action has to be instantiated for every invocation.

There are two methods to override:

public DSInfo getVirtualAction(DSInfo target, String name);

public void getVirtualActions(DSInfo target, Collection<String> bucket);

The default implementations of those methods adds some actions for common edits such as delete and rename.

Action Groups

Action groups should be thought of as menus and you should group actions to make the user interface cleaner. There are some predefined groups that should be used for a consistent user experience.

DSAction.EDIT_GROUP

DSNode automatically adds actions such as Delete, Rename and Duplicate to this group.

If you want to create actions to edit values on your node, you should add them to this group:

actionInfo.getMetaData().setActionGroup(DSAction.EDIT_GROUP).  

Some recommended names for those kinds of edit actions are "Settings" or "Configuration".

DSAction.NEW_GROUP

Actions that add new children should be in the New group. If there is only a single new action there is no need for the group, but consider providing the ability to organize with folders.

Parameters

If an action requires parameters, use DSAction.addParameter to describe the parameters:

action.addParameter("Parameter Name", DSString.NULL, "This is documentation.")
      .setEditor(DSMetadata.STR_EDITOR_TEXT_AREA);

That method returns a DSMetadata instance for additional metadata about the parameter.

Result Types

Actions can have different types of results:

action.setResultType(ResultType.VALUES);

The types are:

• CLOSED_TABLE - A finite sized table whose stream is closed when the row cursor is complete.
• OPEN_TABLE - A finite sized table whose stream is left open once the row cursor is complete. Updates can be sent through the ActionInvocation instance passed to the invoke method.
• STREAM_TABLE - An infinite sized table (stream of rows). The client can decide how many rows to cache in memory.
• VOID - The default value, does not need to be specified.
• VALUES - A single row table whose stream will be closed after the row is sent.