xdocs/guide/using-commons-scxml.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>Using Commons SCXML - How it fits</title>
   <author email="dev@commons.apache.org">Commons Documentation Team</author>
  </properties>

  <body>

   <section name="Using Commons SCXML">

    <p>Commons SCXML provides a generic event-driven state machine based
    execution environment, borrowing the semantics defined by
    <a href="http://www.w3.org/TR/scxml">SCXML</a>. Most things that can be
    represented as a UML state chart -- business process flows, view
    navigation bits, interaction or dialog management, and too many more
    to list here -- can leverage the Commons SCXML library. The library can
    also be used by frameworks needing a process control language. This
    document is a bird's eye view about using Commons SCXML for individual
    (or framework) needs.</p>

   </section>

   <section name="Contents">

    <p>This document is divided into the following sections:
     <ul>
      <li><a href="#pieces">The interacting pieces</a></li>
      <li><a href="#patterns">The interaction patterns</a></li>
      <li><a href="#usecases">Usecases</a></li>
     </ul>
    </p>

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

   <section name="The interacting pieces">
    <p>As with most library code, we have a fairly generic (and thereby
    reusable) asset, a specific domain and the "glue":</p>

    <ol>
     <li>The <i><b>engine</b></i> - Commons SCXML, a generic event-driven state
     machine based execution environment.</li>
     <li>The <i><b>domain</b></i> - The realization in software of the domain
     whose behavior we've defined via SCXML document(s).</li>
     <li>The <i><b>bridge</b></i> - The two way communication link, events
     flying from domain to state machine engine and activities being triggered
     in domain based on current states for the state machine.</li>
    </ol>

    <p>The layer that is therefore needed is the bridge or glue to tie a
    specific usecase to the Commons SCXML engine. While the API aspects are
    dealt with in the core and advanced API sections of this user guide, the
    subsequent section provides a brief narrative introduction.</p>

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

   <section name="The interaction patterns">
    <p>Here are some of the commons usage patterns for bridging (not a
    comprehensive list, plus none of these are mutually exclusive in any
    combination):</p>

    <subsection name="Mapping states to activities">

     <p>This approach consists of maintaining some sort of lookup table that
     records what is to be done (i.e. the activity to be performed) when
     a particular state is reached. Event are fired on the engine, the
     executor is actively queried for current states, and those activities
     indicated by the lookup yield the next set of events (by causing some
     user interaction, or a change in application data model etc.) moving us
     forward.</p>

     <p>This pattern is often useful when the activities are homogeneous
     (always activate a component of a specific type, always render a page
     and wait for submission etc.)</p>

    </subsection>

    <subsection name="Listening to state machine progress">

     <p>Commons SCXML allows processes to register listeners for
     notifications for state machine execution events (entry, exit,
     transition). Listeners implement the
     <a href="../apidocs/org/apache/commons/scxml/SCXMLListener.html">SCXMLListener</a>
     interface. This approach is useful for:</p>

     <ul>
      <li>Activities that have high likelihood of succeeding -
      such as UI updates</li>
      <li>Managing side-effects, which are generally "passive"
      in nature with respect to the state machine execution</li>
     </ul>

    </subsection>

    <subsection name="Using the send action and EventDispatcher">

     <p>SCXML includes the &lt;send&gt; action to "dispatch" an event of choice
     (including whatever payload) to a specified target (of a specified
     targettype). The payload is delivered in the form of a namelist,
     which can be considered as params for the event target.</p>

     <p>The callbacks are received on the
     <a href="../apidocs/org/apache/commons/scxml/EventDispatcher.html">EventDispatcher</a>
     associated with the SCXMLExecutor. The EventDispatcher implementation
     activates the necessary target, which then performs the activity needed to
     make progress.</p>

    </subsection>

    <subsection name="Using custom actions">

     <p>Commons SCXML allows users to register
     <a href="custom-actions.html">custom actions</a> with the Commons
     SCXML engine. Using custom actions in conjunction with derived events
     can lead to quite elegant authoring. The downsides are that this makes
     the solution non-portable (that is, it will not work on other SCXML
     engines -- if that is any cause for concern) and that the custom actions
     need to be authored by the user.</p>

     <p>From a state machine theory point of view, actions are supposed to
     take negligible amount of time, so if lengthy activities need to be
     performed, using the &lt;invoke&gt; is more appropriate.</p>

    </subsection>

    <subsection name="Using invoke to kickstart external processes">

     <p>The &lt;invoke&gt; element is defined by the latest version of
     the W3C SCXML Working Draft. It allows the engine to invoke processes from
     simple states (those that don't have &lt;parallel&gt; or &lt;state&gt;
     children). The process may return a payload with the "done" event,
     that becomes available for decision making in the state machine
     context. Some related details are currently <b>TBD</b> in the Working
     Draft and thefore, susceptible to change.</p>

    </subsection>

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

   <section name="Usecases">

    <p>The Commons SCXML <a href="../usecases.html">usecases</a> provide some
    examples.</p>

    <ul>
     <li>The StopWatch usecases registers a SCXMLListener at the
     document root to manage the UI updates.</li>
     <li>The RDC usecase (dialog management in speech apps) implicitly
     maps state IDs to IDs of speech components that get activated.</li>
     <li>The Shale usecase (cross-page navigation for JSF apps) has an
     explicit lookup table mapping state IDs to JSF view IDs.</li>
    </ul>

   </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>Using Commons SCXML - How it fits</title>
	<author email="dev@commons.apache.org">Commons Documentation Team</author>
	</properties>

	<body>

	<section name="Using Commons SCXML">

	<p>Commons SCXML provides a generic event-driven state machine based
	execution environment, borrowing the semantics defined by
	<a href="http://www.w3.org/TR/scxml">SCXML</a>. Most things that can be
	represented as a UML state chart -- business process flows, view
	navigation bits, interaction or dialog management, and too many more
	to list here -- can leverage the Commons SCXML library. The library can
	also be used by frameworks needing a process control language. This
	document is a bird's eye view about using Commons SCXML for individual
	(or framework) needs.</p>

	</section>

	<section name="Contents">

	<p>This document is divided into the following sections:
	<ul>
	<li><a href="#pieces">The interacting pieces</a></li>
	<li><a href="#patterns">The interaction patterns</a></li>
	<li><a href="#usecases">Usecases</a></li>
	</ul>
	</p>

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

	<section name="The interacting pieces">
	<p>As with most library code, we have a fairly generic (and thereby
	reusable) asset, a specific domain and the "glue":</p>

	<ol>
	<li>The <i><b>engine</b></i> - Commons SCXML, a generic event-driven state
	machine based execution environment.</li>
	<li>The <i><b>domain</b></i> - The realization in software of the domain
	whose behavior we've defined via SCXML document(s).</li>
	<li>The <i><b>bridge</b></i> - The two way communication link, events
	flying from domain to state machine engine and activities being triggered
	in domain based on current states for the state machine.</li>
	</ol>

	<p>The layer that is therefore needed is the bridge or glue to tie a
	specific usecase to the Commons SCXML engine. While the API aspects are
	dealt with in the core and advanced API sections of this user guide, the
	subsequent section provides a brief narrative introduction.</p>

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

	<section name="The interaction patterns">
	<p>Here are some of the commons usage patterns for bridging (not a
	comprehensive list, plus none of these are mutually exclusive in any
	combination):</p>

	<subsection name="Mapping states to activities">

	<p>This approach consists of maintaining some sort of lookup table that
	records what is to be done (i.e. the activity to be performed) when
	a particular state is reached. Event are fired on the engine, the
	executor is actively queried for current states, and those activities
	indicated by the lookup yield the next set of events (by causing some
	user interaction, or a change in application data model etc.) moving us
	forward.</p>

	<p>This pattern is often useful when the activities are homogeneous
	(always activate a component of a specific type, always render a page
	and wait for submission etc.)</p>

	</subsection>

	<subsection name="Listening to state machine progress">

	<p>Commons SCXML allows processes to register listeners for
	notifications for state machine execution events (entry, exit,
	transition). Listeners implement the
	<a href="../apidocs/org/apache/commons/scxml/SCXMLListener.html">SCXMLListener</a>
	interface. This approach is useful for:</p>

	<ul>
	<li>Activities that have high likelihood of succeeding -
	such as UI updates</li>
	<li>Managing side-effects, which are generally "passive"
	in nature with respect to the state machine execution</li>
	</ul>

	</subsection>

	<subsection name="Using the send action and EventDispatcher">

	<p>SCXML includes the <send> action to "dispatch" an event of choice
	(including whatever payload) to a specified target (of a specified
	targettype). The payload is delivered in the form of a namelist,
	which can be considered as params for the event target.</p>

	<p>The callbacks are received on the
	<a href="../apidocs/org/apache/commons/scxml/EventDispatcher.html">EventDispatcher</a>
	associated with the SCXMLExecutor. The EventDispatcher implementation
	activates the necessary target, which then performs the activity needed to
	make progress.</p>

	</subsection>

	<subsection name="Using custom actions">

	<p>Commons SCXML allows users to register
	<a href="custom-actions.html">custom actions</a> with the Commons
	SCXML engine. Using custom actions in conjunction with derived events
	can lead to quite elegant authoring. The downsides are that this makes
	the solution non-portable (that is, it will not work on other SCXML
	engines -- if that is any cause for concern) and that the custom actions
	need to be authored by the user.</p>

	<p>From a state machine theory point of view, actions are supposed to
	take negligible amount of time, so if lengthy activities need to be
	performed, using the <invoke> is more appropriate.</p>

	</subsection>

	<subsection name="Using invoke to kickstart external processes">

	<p>The <invoke> element is defined by the latest version of
	the W3C SCXML Working Draft. It allows the engine to invoke processes from
	simple states (those that don't have <parallel> or <state>
	children). The process may return a payload with the "done" event,
	that becomes available for decision making in the state machine
	context. Some related details are currently <b>TBD</b> in the Working
	Draft and thefore, susceptible to change.</p>

	</subsection>

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

	<section name="Usecases">

	<p>The Commons SCXML <a href="../usecases.html">usecases</a> provide some
	examples.</p>

	<ul>
	<li>The StopWatch usecases registers a SCXMLListener at the
	document root to manage the UI updates.</li>
	<li>The RDC usecase (dialog management in speech apps) implicitly
	maps state IDs to IDs of speech components that get activated.</li>
	<li>The Shale usecase (cross-page navigation for JSF apps) has an
	explicit lookup table mapping state IDs to JSF view IDs.</li>
	</ul>

	</section>

	</body>

	</document>