You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by ra...@apache.org on 2006/05/04 18:06:02 UTC
svn commit: r399746 -
/jakarta/commons/proper/scxml/trunk/xdocs/guide/using-commons-scxml.xml
Author: rahul
Date: Thu May 4 09:05:59 2006
New Revision: 399746
URL: http://svn.apache.org/viewcvs?rev=399746&view=rev
Log:
Add a section to the user guide on common interaction patterns using the Commons SCXML library (the "glue" or "bridge" code).
Added:
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
URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/scxml/trunk/xdocs/guide/using-commons-scxml.xml?rev=399746&view=auto
==============================================================================
--- 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 2006
@@ -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
+
+ 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="commons-dev@jakarta.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><i>Not yet implemented in Commons SCXML.</i></p>
+
+ <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. Many related details are currently <b>TBD</b> in the Working
+ Draft and thefore, the Commons SCXML engine does not implement
+ <invoke> yet.</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>
+
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: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org