SCXML - Commons SCXML Usage - Five minute SCXML tutorial

What is SCXML?

State Chart XML (SCXML) is a general-purpose event-based state machine language that can be used in many ways.

The definitive guide to authoring SCXML documents is the W3C Working Draft of the SCXML specification.

This document contains the following sections:

Hello World
Transitions
Composite states
Parallel
Hello World with a custom action

Hello World

Here is the canonical hello world example for SCXML. The interesting bits are:

    <scxml xmlns="http://www.w3.org/2005/07/scxml"
              version="1.0"
              initial="hello">

     <final id="hello">
      <onentry>
       <log expr="'hello world'" />
      </onentry>
     </final>

    </scxml>

The document declares an initial state of "hello", which is the entry point into the state machine.
Once the state "hello" is entered the "executable content" contained in the <onentry> is immediately executed.
Similarly, there is also the symmetric <onexit>, which holds executable content to be executed when a state is being exited.
The final attribute on state "hello" indicates that the state machine has "run to completion".
Executable content is made of a series of "actions".
The "standard actions" defined by the SCXML specification are: <var>, <assign>, <log>, <send>, <cancel>, <if>, <elseif>, <else>.

Transitions

Transitions allow the state machine to change state. A transition is "followed" if its "trigger event" is received, and the "guard condition", if one is available is valid.

Here are some transition variants:

    <!--
      ... begin scxml, some states ...
    -->

     <state id="foo1">
      <!--
        ... some content ...
      -->
      <transition target="bar" />
     </state>

     <state id="foo2">
      <!--
        ... some content ...
      -->
      <transition event="foo.bar" target="bar" />
     </state>

     <state id="foo3">
      <!--
        ... some content ...
      -->
      <transition event="foo.bar" cond="some-boolean-expression"
                     target next="bar" />
     </state>

     <state id="bar">
      <!--
        ... some content ...
      -->
     </state>

    <!--
       ... remaining states, end scxml ...
    -->

The first transition in document order is an "immediate" transition. "foo1" is the source, and "bar" is the destination (transition target).
The second transition waits for the trigger event "foo.bar".
The third waits for "foo.bar" and the guard condition specified by its "cond" attribute to evaluate to true the instant the event is received.

Composite states

States can contain states, so we can think of an SCXML document as a recursive transition network. Here is a snippet (here is the entire version of this microwave example ):

    <!--
      ... begin snippet ...
    -->

     <state id="on">
      <initial>
       <transition target="idle"/>
      </initial>

      <state id="idle">
       <!-- content for state "idle" -->
      </state>

      <state id="cooking">
       <!-- content for state "cooking" -->
      </state>

      <!-- other content for state "on" -->

    <!--
      ... end snippet ...
    -->

The state "on" is an example of a composite state.
It contains two states, "idle" and "cooking". Since there are no other sibling states, this means that when the microwave is turned on, it must be in either idle or cooking state.
Since there are multiple states in the state "on", an <initial> element is required. This becomes the "active" child state when a transition is made to the composite state. (in this case, a transition to state "on", causes the "idle" state to be active).
States can be recursively nested to any depth.

Parallel

This is a wrapper element that encapsulates multiple <state>s -- or state machines, since in the section on composite states we took a look at the "recursion" or "nesting" for the <state> element, whereby each state can become a state machine in its own right -- that are "active" at the same time. Here is a relevant snippet (the entire version of this parallel microwave example ):

    <!--
      ... begin snippet ...
    -->

     <state id="microwave">
      <parallel id="parts">
       <state id="oven">

        <!-- state machine for "oven" (idle/cooking) -->

       </state>

       <state id="door">

        <!-- state machine for "door" (open/closed) -->

       </state>
      </parallel>
     </state>

    <!--
      ... end snippet ...
    -->

The state "microwave" is an example of a "orthogonal" state (one that owns a parallel).
It contains two state machines, "oven" and "door". These state machines are "active" at the same time. These are known as "regions".
Transition may occur within a region or from a region to outside the <parallel> (see below), but never from one region to another ("across" regions).
There is no need for an <initial> element within a <parallel>
The state machine must enter all regions at the same time, and an outbound transition out of the <parallel> from any region causes the state machine to exit all regions.
When all regions reach a "final" state, an "done.state.id" event is fired, where "id" is the id of the parent <parallel>

Hello World with a custom action

The Commons SCXML implementation allows you to register custom actions. Here is the Commons SCXML hello world example using a custom action. The interesting bits are:

    <scxml xmlns="http://www.w3.org/2005/07/scxml"
              xmlns:my="http://my.custom-actions.domain/CUSTOM"
              version="1.0"
              initial="custom">

     <final id="custom">
      <onentry>
       <my:hello name="world" />
      </onentry>
     </final>

    </scxml>