commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject svn commit: r399746 - /jakarta/commons/proper/scxml/trunk/xdocs/guide/using-commons-scxml.xml
Date Thu, 04 May 2006 16:06:02 GMT
Author: rahul
Date: Thu May  4 09:05:59 2006
New Revision: 399746

Add a section to the user guide on common interaction patterns using the Commons SCXML library
(the "glue" or "bridge" code).

    jakarta/commons/proper/scxml/trunk/xdocs/guide/using-commons-scxml.xml   (with props)

Added: jakarta/commons/proper/scxml/trunk/xdocs/guide/using-commons-scxml.xml
--- jakarta/commons/proper/scxml/trunk/xdocs/guide/using-commons-scxml.xml (added)
+++ jakarta/commons/proper/scxml/trunk/xdocs/guide/using-commons-scxml.xml Thu May  4 09:05:59
@@ -0,0 +1,182 @@
+<?xml version="1.0" encoding="UTF-8"?>
+   Copyright 2006 The Apache Software Foundation
+   Licensed 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
+   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.
+ <properties>
+  <title>Using Commons SCXML - How it fits</title>
+  <author email="">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="">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><i>Not yet implemented in Commons SCXML.</i></p>
+    <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. Many related details are currently <b>TBD</b> in the Working
+    Draft and thefore, the Commons SCXML engine does not implement
+    &lt;invoke&gt; yet.</p>
+   </subsection>
+   <a name="usecases"/>
+  </section>
+  <section name="Usecases">
+   <p>The Commons SCXML <a href="../usecases.html">usecases</a> provide
+   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>

Propchange: jakarta/commons/proper/scxml/trunk/xdocs/guide/using-commons-scxml.xml
    svn:eol-style = native

Propchange: jakarta/commons/proper/scxml/trunk/xdocs/guide/using-commons-scxml.xml
    svn:keywords = Date Author Id Revision HeadURL

To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message