Using custom actions with Commons SCXML

Contains notes about Commons SCXML APIs for extending or altering document semantics.

+ + + Using custom actions with Commons SCXML + Commons Documentation Team + + + + +

+ +

Actions are SCXML elements that "do" something. Actions can be + used where "executable content" is permissible, for example, + within <onentry>, <onexit> and <transition> + elements.

+ +

The SCXML specification + (currently a Working Draft) defines a set of "standard actions". + These include <var>, <assign>, <log>, <send>, + <cancel>, <if>, <elseif> and <else>.

+ +

The specification also allows implementations to define "custom actions" + in addition to the standard actions. What such actions "do" is + upto the author of these actions, and these are therefore + called "custom" since they are tied to a specific implementation + of the SCXML specification.

+ +

Commons SCXML makes authoring custom actions fairly straightforward.

+ + + +

A custom action in the Commons SCXML implementation has access to: +

The current + Context + (and hence, the values of variables in the current Context). +
Any other Context within the document, provided the id of the + parent <state> is known. +
The expression + Evaluator + for this document, and hence the ability to evaluate a given + expression against the current or a identifiable Context. +
The list of other actions in this + Executable + .
The "root" Context, to examine any variable values in the + "document environment".
The + EventDispatcher, + to send or cancel events.
The + ErrorReporter, + to report any errors (that the ErrorReporter knows how to handle).
The histories, for any identifiable <history>.
The + NotificationRegistry, + to obtain the list of listeners attached to identifiable + "observers".
The engine log, to log any information it needs to.

+ + + +

+ +

Lets walk through the development of a simple, custom "hello world" + action.

+ + + +

We need a <hello> action in our (fictitious) namespace + "http://my.custom-actions.domain/CUSTOM". The action "tag" will + have one attribute "name". The action simply logs a hello to the + value of the name attribute when it executes.

+ + + + + +

A custom action must extend the Commons SCXML + Action + abstract base class.

+ +

Here is the Java source for our custom + Hello + action. The execute() method contains the logging statement.

+ + + + + +

With the custom action implemented, obtain a configured digester which + has the "default" ruleset required for reading (parsing) SCXML + documents, and then register the custom action like so:

+ +

+      // (1) Get Digester with "default" rules for parsing SCXML documents
+      Digester digester = SCXMLDigester.newInstance(null, null);
+
+      // (2) Register the "custom" action(s)
+      SCXMLDigester.addCustomAction(digester,
+          "http://my.custom-actions.domain/CUSTOM", "hello", Hello.class);
+

+ +

This static addCustomAction() method can only be used if the custom + rule has no body content (child "tags") or if the custom action + implements the + ExternalContent + interface, in which any body content gets read into a list + of DOM nodes. For any other requirements, the digester rules + can be added by directly using the + digester API + .

+ + + + + +

This involves parsing the document and making the resulting + SCXML object executor-ready (which allows us to detect any + "model inconsistencies" before feeding it to the + execution engine. That amounts to:

+ +

+      // (3) Parse the SCXML document containing the custom action(s)
+      SCXML scxml = null;
+      try {
+          scxml = (SCXML) digester.parse(<String>);
+          //String method as an example
+      } catch (Exception e) {
+          // bad document, take necessary action
+      }
+      // (4) Wire up the object model for the SCXMLExecutor
+      SCXMLDigester.updateSCXML(scxml);
+

+ +

Without custom actions, the utility methods of the + SCXMLDigester + should be used. That section is + here.

+ + + + + + +

Having obtained the SCXML object beyond step (4) above, + proceed as usual, see the section on the + Commons SCXML engine + for details.

+ + + +