SCXML - Commons SCXML Usage - API notes

Commons SCXML - Firing events on the SCXML engine

Once the SCXML engine has been initialized, the state machine progresses based on the events that are fired on it. When an event is fired, if the current set of states have transitions waiting for that event, and the guard condition on one of those transitions is satisfied, the state machine is said to "follow" that transition, which may possibly yield a new set of current states. Most state machines will ultimately reach a "final" state, wherein the state machine has said to have executed to completion.

Basic Usage

An event "foo.bar" may be fired on the engine as follows:

        //import org.apache.commons.scxml2.SCXMLExecutor;
        //import org.apache.commons.scxml2.TriggerEvent;
        //import org.apache.commons.scxml2.model.ModelException;

        // where "exec" is the SCXMLExecutor instance
        TriggerEvent te = new TriggerEvent("foo.bar",
                              TriggerEvent.SIGNAL_EVENT);
        try {
            exec.triggerEvent(te);
        } catch (ModelException me) {
            // The events left the engine in inconsistent state
        }

If the resulting events leave the state machine in an inconsistent state, a ModelException may be thrown.

Event Payloads

Furthermore, events can carry within them a payload property that consists of some information that is useful for the guard conditions or executable content while the engine is processing the event. The payload can be any user-defined type.

       //import org.apache.commons.scxml2.SCXMLExecutor;
       //import org.apache.commons.scxml2.TriggerEvent;
       //import org.apache.commons.scxml2.model.ModelException;

       // where "exec" is the SCXMLExecutor instance
       // and "foo" is an object (payload) with an accessible property "bar"
       TriggerEvent te = new TriggerEvent("event.with.payload",
       TriggerEvent.SIGNAL_EVENT, foo);
       try {
       exec.triggerEvent(te);
       } catch (ModelException me) {
       // The events left the engine in inconsistent state
       }

The payload in the above example can now be used in expressions, as the special variable "_eventdata". For example, assuming a JEXL expressions based document, transitions may look like (similarly "_eventdata" may be used in executable content in corresponding <onexit>, <transition> and <onentry> bodies).

         <transition event="event.with.payload"
                        cond="_eventdata.bar eq 'bar1'" next="state1" />
         <transition event="event.with.payload"
                        cond="_eventdata.bar eq 'bar2'" next="state2" />

Multiple Events

More than one events may be triggered on the state machine at a time (using triggerEvents() method -- plural). After the engine processes a set of trigger events, it is customary to check whether the state machine has reached a <final> state. All events will operate over the same states ancestor closure.

Running to completion

The following snippet illustrates how the SCXMLExecutor Status is queried for state machine run to completion.

        //import org.apache.commons.scxml2.SCXMLExecutor;
        //import org.apache.commons.scxml2.Status;

        // where "exec" is the SCXMLExecutor instance
        Status status = exec.getCurrentStatus();
        if (status.isFinal()) {
            // run to completion, release cached objects
        }

The TriggerEvent Javadoc is available here.
The Status Javadoc is available here

API notes set

The previous note in this set describes the SCXML engine.