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, see the javadoc for details:

 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 dynamic actions instead.

DSNode.getDynamicActions/getDynamicAction

Dynamic actions must be used to add actions to child values that are not DSNodes, but they can also be used for DSNodes.

Dynamic 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, see the javadoc for details:

public DSInfo getDynamicAction(DSInfo target, String name);

public void getDynamicActions(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("actionName", 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.
• 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.