Usage

The SCXMLExecutor is usually initialized as follows:

        //import org.apache.commons.scxml2.Context;
        //import org.apache.commons.scxml2.ErrorReporter;
        //import org.apache.commons.scxml2.Evaluator;
        //import org.apache.commons.scxml2.EventDispatcher;
        //import org.apache.commons.scxml2.SCXMLExecutor;
        //import org.apache.commons.scxml2.SCXMLListener;
        //import org.apache.commons.scxml2.model.SCXML;
        //import org.apache.commons.scxml2.model.ModelException;

        SCXMLExecutor exec = null;
        try {
            exec = new SCXMLExecutor(<Evaluator>,
                       <EventDispatcher>, <ErrorReporter>);
            exec.setStateMachine(<SCXML>);
            exec.addListener(<SCXML>, <SCXMLListener>);
            exec.setRootContext(<Context>);
            exec.go();
        } catch (ModelException me) {
            // Executor initialization failed, because the
            // state machine specified has inconsistencies
        }
     

Explanation

The SCXML specification allows implementations to support multiple expression languages so SCXML documents can be used in varying environments. The Context and Evaluator interfaces serve as adapters to the particular expression language APIs. Commons SCXML currently supports JEXL, Javascript, Groovy and XPath expressions. See the section on contexts and evaluators for further details about contexts, evaluators and root contexts.

Commons SCXML provides an EventDispatcher interface for wiring the behavior of SCXML <send> and <cancel> actions. This allows users to define custom target "types" as long as they handle the callbacks on the EventDispatcher implementation provided to the executor. The introductory section on using Commons SCXML has a brief discussion on interaction patterns, including <send> usage.

The ErrorReporter interface is used by Commons SCXML for reporting SCXML errors to the host environment, and contains the definition of commonly occuring errors while executing SCXML documents. It is primarily used for passive usages such as logging.

Commons SCXML also allows listeners (SCXMLListener) to be registered with the SCXMLExecutor, which are informed about the progress of the state machine via onEntry and onExit notifications for States, as well as onTransition notifications when transitions are followed.

Commons SCXML provides basic implementations of the EventDispatcher, ErrorReporter, and SCXMLListener interfaces in the env package, which simply log all the events received. Commons SCXML uses Commons Logging.

The executor is "set into motion" using the marker method SCXMLExecutor#go(). The SCXMLExecutor instances are not thread-safe, and need external synchronization if the usecase demands.

The SCXMLExecutor Javadoc is available here.

API notes set

The previous note in this set describes the SCXML Reader.
The next note in this set describes triggering events.