Apache Commons logo Commons SCXML

SCXML Semantics

This section is for advanced users only, and will probably not be needed by most users of the Commons SCXML library.

Pluggable semantics

The Commons SCXML state machine engine is really a tuple, the SCXMLExecutor (an API that new users can code to, and is almost always sufficient) accompanied by a SCXMLSemantics implementation (an API that advanced users can code to, to change the engine behavior to suit their needs).

The basic modus operandi for an engine is simple - when an event is triggered, figure out which (if any) transition(s) to follow, and transit to the new set of states executing any specified actions along the way. The default semantics available in the Commons SCXML distribution, which is based upon the SCXML specification rules for the Algorithm for SCXML processing, can be replaced with custom semantics provided by the user using the SCXMLExecutor constructor that takes the SCXMLSemantics parameter i.e. the engine semantics are "pluggable".

Example scenario

Consider dispute resolution for example -- when more than one outbound transitions from a single state hold true. The default SCXMLSemantics implementation available in the distribution does none, it will follow all filtered transitions, possibly leading to a ModelException immediately or down the road. However, a user may want:

  • The transition defined closest to the document root to be followed
  • The transition defined farthest from the document root to be followed
  • The transition whose origin and target have the lowest common ancestor to be followed
  • The transition whose origin and target have the highest common ancestor to be followed

Even after one of above dispute resolution algorithms is applied, if there are more than one candidate transitions, the user may want:

  • A ModelException to be thrown
  • The transition that appears first in document order to be followed
  • The transition that appears last in document order to be followed

To implement any of the above choices, the user may extend the default SCXMLSemantics implementation, override one or more of the existing implemention methods, or even write a new implementation from scratch, and plug in the new semantics while instantiating the SCXMLExecutor. The pluggability allows differing semantics to be developed for the Commons SCXML engine, independent of the Commons SCXML codebase.