<?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/scxml2/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
    type). 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/scxml2/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 therefore, 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>
   </ul>

  </section>

 </body>

</document>

