xdocs/guide/scxml-documents.xml - commons-scxml - Git at Google

 <?xml version="1.0" encoding="UTF-8"?>
 <!--
  * Licensed to the Apache Software Foundation (ASF) under one or more
  * contributor license agreements.  See the NOTICE file distributed with
  * this work for additional information regarding copyright ownership.
  * The ASF licenses this file to You under the Apache License, Version 2.0
  * (the "License"); you may not use this file except in compliance with
  * the License.  You may obtain a copy of the License at
  *
  *     http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
 -->

 <document>

  <properties>
   <title>Commons SCXML Usage - Five minute SCXML tutorial</title>
   <author email="dev@commons.apache.org">Commons Documentation Team</author>
  </properties>

  <body>

   <section name="What is SCXML?">

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

    <p>The definitive guide to authoring SCXML documents is the
       <a href="http://www.w3.org/TR/scxml/">W3C Working Draft
       of the SCXML specification</a>.</p>

   </section>

   <section name="Contents">

    <p>This document contains the following sections:
     <ul>
      <li><a href="#hello">Hello World</a></li>
      <li><a href="#transitions">Transitions</a></li>
      <li><a href="#composite">Composite states</a></li>
      <li><a href="#parallel">Parallel</a></li>
      <li><a href="#custom">Hello World with a custom action</a></li>
     </ul>
    </p>

    <a name="hello"/>
   </section>

   <section name="Hello World">

    <p>Here is the canonical
       <a href="http://svn.apache.org/repos/asf/jakarta/commons/proper/scxml/trunk/src/test/java/org/apache/commons/scxml/hello-world.xml">hello world example</a>
       for SCXML. The interesting bits are:</p>

    <pre>
     &lt;scxml xmlns="http://www.w3.org/2005/07/scxml"
               version="1.0"
               initialstate="hello"&gt;

      &lt;state id="hello" final="true"&gt;
       &lt;onentry&gt;
        &lt;log expr="'hello world'" /&gt;
       &lt;/onentry&gt;
      &lt;/state&gt;

     &lt;/scxml&gt;
    </pre>

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

    <a name="transitions"/>
   </section>

   <section name="Transitions">

    <p>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.
    </p>

    <p>Here are some transition variants:</p>

    <pre>
     &lt;!--
       ... begin scxml, some states ...
     --&gt;

      &lt;state id="foo1"&gt;
       &lt;!--
         ... some content ...
       --&gt;
       &lt;transition target="bar" /&gt;
      &lt;/state&gt;

      &lt;state id="foo2"&gt;
       &lt;!--
         ... some content ...
       --&gt;
       &lt;transition event="foo.bar" target="bar" /&gt;
      &lt;/state&gt;

      &lt;state id="foo3"&gt;
       &lt;!--
         ... some content ...
       --&gt;
       &lt;transition event="foo.bar" cond="some-boolean-expression"
                      target next="bar" /&gt;
      &lt;/state&gt;

      &lt;state id="bar"&gt;
       &lt;!--
         ... some content ...
       --&gt;
      &lt;/state&gt;

     &lt;!--
        ... remaining states, end scxml ...
     --&gt;
    </pre>

    <p>
     <ul>
      <li>The first transition in document order is an "immediate"
          transition. "foo1" is the source, and "bar" is the
          destination (transition target).
      </li>
      <li>The second transition waits for the trigger event "foo.bar".
      </li>
      <li>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.
      </li>
     </ul>
    </p>

    <a name="composite"/>
   </section>

   <section name="Composite states">

    <p>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
       <a href="http://svn.apache.org/repos/asf/jakarta/commons/proper/scxml/trunk/src/test/java/org/apache/commons/scxml/env/jexl/microwave-01.xml">microwave example</a>
       ):</p>

    <pre>
     &lt;!--
       ... begin snippet ...
     --&gt;

      &lt;state id="on"&gt;
       &lt;initial&gt;
        &lt;transition target="idle"/&gt;
       &lt;/initial&gt;

       &lt;state id="idle"&gt;
        &lt;!-- content for state "idle" --&gt;
       &lt;/state&gt;

       &lt;state id="cooking"&gt;
        &lt;!-- content for state "cooking" --&gt;
       &lt;/state&gt;

       &lt;!-- other content for state "on" --&gt;

     &lt;!--
       ... end snippet ...
     --&gt;
    </pre>

    <p>
     <ul>
      <li>The state "on" is an example of a composite state.</li>
      <li>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.
      </li>
      <li>Since there are multiple states in the state "on", an
          &lt;initial&gt; 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).
      </li>
      <li>States can be recursively nested to any depth.</li>
     </ul>
    </p>

    <a name="parallel"/>
   </section>

   <section name="Parallel">

    <p>This is a wrapper element that encapsulates multiple
       &lt;state&gt;s -- or state machines, since in the section on
       composite states we took a look at the "recursion" or
       "nesting" for the &lt;state&gt; 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
       <a href="http://svn.apache.org/repos/asf/jakarta/commons/proper/scxml/trunk/src/test/java/org/apache/commons/scxml/env/jexl/microwave-02.xml">parallel microwave example</a>
       ):</p>

    <pre>
     &lt;!--
       ... begin snippet ...
     --&gt;

      &lt;state id="microwave"&gt;
       &lt;parallel id="parts"&gt;
        &lt;state id="oven"&gt;

         &lt;!-- state machine for "oven" (idle/cooking) --&gt;

        &lt;/state&gt;

        &lt;state id="door"&gt;

         &lt;!-- state machine for "door" (open/closed) --&gt;

        &lt;/state&gt;
       &lt;/parallel&gt;
      &lt;/state&gt;

     &lt;!--
       ... end snippet ...
     --&gt;
    </pre>

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

    <a name="custom"/>
   </section>

   <section name="Hello World with a custom action">

    <p>The Commons SCXML implementation allows you to register custom actions.
       Here is the Commons SCXML
       <a href="http://svn.apache.org/repos/asf/jakarta/commons/proper/scxml/trunk/src/test/java/org/apache/commons/scxml/custom-hello-world-02.xml">hello world example using a custom action</a>.
       The interesting bits are:</p>

    <pre>
     &lt;scxml xmlns="http://www.w3.org/2005/07/scxml"
               xmlns:my="http://my.custom-actions.domain/CUSTOM"
               version="1.0"
               initialstate="custom"&gt;

      &lt;state id="custom" final="true"&gt;
       &lt;onentry&gt;
        &lt;my:hello name="world" /&gt;
       &lt;/onentry&gt;
      &lt;/state&gt;

     &lt;/scxml&gt;
    </pre>

    <p>
     <ul>
      <li>&lt;my:hello&gt; is an example of a custom action whose local
          name is "hello" and is bound to the fictitious namespace
          "http://my.custom-actions.domain/CUSTOM"
      </li>
      <li>The custom action hello merely logs a hello to the value of
          the name attribute, and thus the above example produces results
          identical to the initial hello world example above.
      </li>
      <li>For details, see the section on
          <a href="custom-actions.html">custom actions</a> in this guide.
      </li>
     </ul>
    </p>

   </section>

  </body>

 </document>
	<?xml version="1.0" encoding="UTF-8"?>
	<!--
	* Licensed to the Apache Software Foundation (ASF) under one or more
	* contributor license agreements. See the NOTICE file distributed with
	* this work for additional information regarding copyright ownership.
	* The ASF licenses this file to You under the Apache License, Version 2.0
	* (the "License"); you may not use this file except in compliance with
	* the License. You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing, software
	* distributed under the License is distributed on an "AS IS" BASIS,
	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	* See the License for the specific language governing permissions and
	* limitations under the License.
	-->

	<document>

	<properties>
	<title>Commons SCXML Usage - Five minute SCXML tutorial</title>
	<author email="dev@commons.apache.org">Commons Documentation Team</author>
	</properties>

	<body>

	<section name="What is SCXML?">

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

	<p>The definitive guide to authoring SCXML documents is the
	<a href="http://www.w3.org/TR/scxml/">W3C Working Draft
	of the SCXML specification</a>.</p>

	</section>

	<section name="Contents">

	<p>This document contains the following sections:
	<ul>
	<li><a href="#hello">Hello World</a></li>
	<li><a href="#transitions">Transitions</a></li>
	<li><a href="#composite">Composite states</a></li>
	<li><a href="#parallel">Parallel</a></li>
	<li><a href="#custom">Hello World with a custom action</a></li>
	</ul>
	</p>

	<a name="hello"/>
	</section>

	<section name="Hello World">

	<p>Here is the canonical
	<a href="http://svn.apache.org/repos/asf/jakarta/commons/proper/scxml/trunk/src/test/java/org/apache/commons/scxml/hello-world.xml">hello world example</a>
	for SCXML. The interesting bits are:</p>

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

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

	</scxml>
	</pre>

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

	<a name="transitions"/>
	</section>

	<section name="Transitions">

	<p>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.
	</p>

	<p>Here are some transition variants:</p>

	<pre>
	<!--
	... 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 ...
	-->
	</pre>

	<p>
	<ul>
	<li>The first transition in document order is an "immediate"
	transition. "foo1" is the source, and "bar" is the
	destination (transition target).
	</li>
	<li>The second transition waits for the trigger event "foo.bar".
	</li>
	<li>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.
	</li>
	</ul>
	</p>

	<a name="composite"/>
	</section>

	<section name="Composite states">

	<p>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
	<a href="http://svn.apache.org/repos/asf/jakarta/commons/proper/scxml/trunk/src/test/java/org/apache/commons/scxml/env/jexl/microwave-01.xml">microwave example</a>
	):</p>

	<pre>
	<!--
	... 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 ...
	-->
	</pre>

	<p>
	<ul>
	<li>The state "on" is an example of a composite state.</li>
	<li>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.
	</li>
	<li>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).
	</li>
	<li>States can be recursively nested to any depth.</li>
	</ul>
	</p>

	<a name="parallel"/>
	</section>

	<section name="Parallel">

	<p>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
	<a href="http://svn.apache.org/repos/asf/jakarta/commons/proper/scxml/trunk/src/test/java/org/apache/commons/scxml/env/jexl/microwave-02.xml">parallel microwave example</a>
	):</p>

	<pre>
	<!--
	... 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 ...
	-->
	</pre>

	<p>
	<ul>
	<li>The state "microwave" is an example of a "orthogonal"
	state (one that owns a parallel).</li>
	<li>It contains two state machines, "oven" and "door". These
	state machines are "active" at the same time. These are
	known as "regions".
	</li>
	<li>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).
	</li>
	<li>There is no need for an <initial> element within
	a <parallel></li>
	<li>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.</li>
	<li>When all regions reach a "final" state, an "id.done" event
	is fired, where "id" is the id of the parent <parallel>
	</li>
	</ul>
	</p>

	<a name="custom"/>
	</section>

	<section name="Hello World with a custom action">

	<p>The Commons SCXML implementation allows you to register custom actions.
	Here is the Commons SCXML
	<a href="http://svn.apache.org/repos/asf/jakarta/commons/proper/scxml/trunk/src/test/java/org/apache/commons/scxml/custom-hello-world-02.xml">hello world example using a custom action</a>.
	The interesting bits are:</p>

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

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

	</scxml>
	</pre>

	<p>
	<ul>
	<li><my:hello> is an example of a custom action whose local
	name is "hello" and is bound to the fictitious namespace
	"http://my.custom-actions.domain/CUSTOM"
	</li>
	<li>The custom action hello merely logs a hello to the value of
	the name attribute, and thus the above example produces results
	identical to the initial hello world example above.
	</li>
	<li>For details, see the section on
	<a href="custom-actions.html">custom actions</a> in this guide.
	</li>
	</ul>
	</p>

	</section>

	</body>

	</document>