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: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]