You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@shale.apache.org by ra...@apache.org on 2006/10/29 04:17:36 UTC
svn commit: r468828 - in /shale/framework/trunk/shale-dialog-scxml/src/site:
resources/ resources/images/ resources/images/log-on-dialog.jpg
xdoc/index.xml
Author: rahul
Date: Sat Oct 28 20:17:35 2006
New Revision: 468828
URL: http://svn.apache.org/viewvc?view=rev&rev=468828
Log:
New documentation sections: benefits, instruction by example for describing dialogs as SCXML documents, bootstrapping the SCXML dialog manager.
SHALE-263
Added:
shale/framework/trunk/shale-dialog-scxml/src/site/resources/
shale/framework/trunk/shale-dialog-scxml/src/site/resources/images/
shale/framework/trunk/shale-dialog-scxml/src/site/resources/images/log-on-dialog.jpg (with props)
Modified:
shale/framework/trunk/shale-dialog-scxml/src/site/xdoc/index.xml
Added: shale/framework/trunk/shale-dialog-scxml/src/site/resources/images/log-on-dialog.jpg
URL: http://svn.apache.org/viewvc/shale/framework/trunk/shale-dialog-scxml/src/site/resources/images/log-on-dialog.jpg?view=auto&rev=468828
==============================================================================
Binary file - no diff available.
Propchange: shale/framework/trunk/shale-dialog-scxml/src/site/resources/images/log-on-dialog.jpg
------------------------------------------------------------------------------
svn:mime-type = image/jpeg
Modified: shale/framework/trunk/shale-dialog-scxml/src/site/xdoc/index.xml
URL: http://svn.apache.org/viewvc/shale/framework/trunk/shale-dialog-scxml/src/site/xdoc/index.xml?view=diff&rev=468828&r1=468827&r2=468828
==============================================================================
--- shale/framework/trunk/shale-dialog-scxml/src/site/xdoc/index.xml (original)
+++ shale/framework/trunk/shale-dialog-scxml/src/site/xdoc/index.xml Sat Oct 28 20:17:35 2006
@@ -42,6 +42,211 @@
</subsection>
+
+ <a name="dialog-scxml-why"/>
+ <subsection name="Benefits">
+
+ <ul>
+
+ <li>SCXML is a <a href="http://www.w3.org/TR/scxml">W3C Working Draft</a>
+ which may translate to better support in tooling, number of
+ implementations and various runtime environments. It is the candidate
+ controller notation coming out of the W3C.</li>
+
+ <li>SCXML is more closely aligned to state chart theory and UML2, which
+ helps those using model driven development methodologies.</li>
+
+ <li>SCXML semantics provides for much more than the basic Shale dialogs
+ implementation, such as histories, per state contexts, arbitrary
+ expression evaluation, parallelism and the possibility
+ (<i>currently not available in the shale-dialog-scxml module</i>) to add
+ domain-specific XML vocabularies via action namespaces. See the
+ <a href="http://jakarta.apache.org/commons/scxml/">Commons SCXML site</a>
+ for details.</li>
+
+ <li>Those developing multi-channel applications, or using frameworks
+ that use SCXML for the controller bits in other contexts (e.g.
+ <a href="http://jakarta.apache.org/taglibs/doc/rdc-doc/intro.html">RDC framework</a>),
+ may be inclined towards SCXML-based authoring for Shale dialogs.</li>
+
+ </ul>
+
+ </subsection>
+
+
+ <a name="dialog-scxml-how"/>
+ <subsection name="Describing Shale dialogs via SCXML documents">
+
+ <p>A Shale dialog is modeled as a state machine. The various
+ "state types" that commonly constitute the dialog state machine
+ are described in the Shale dialogs
+ <a href="../shale-dialog-basic/index.html#dialog-state-types">basic
+ implementation documentation</a>.</p>
+
+ <p> This section maps these types to the corresponding SCXML
+ snippets appropriate for the Shale dialogs SCXML implementation.
+ The example dialog from the Shale usecases sample application
+ is captured here as a <a href="images/log-on-dialog.jpg">UML state
+ machine diagram</a> and forms the basis of the snippets below.</p>
+
+ <ul>
+
+ <li>Action state instances may be mapped to executable content
+ in UML <code><onentry></code> (and may be chained similarly).
+<source>
+<!-- An "action" state -->
+<state id="checkCookie">
+
+ <!-- Execute the method binding expression in the onentry block,
+ method must take no arguments and return a String. These
+ method binding expressions must use the #{...} syntax -->
+
+ <onentry>
+ <var name="cookieOutcome" expr="#{profile$logon.check}" />
+ </onentry>
+
+ <!-- Check the return value, and conditionally transition
+ to the appropriate state. Arbitrary EL expressions must use
+ the ${...} syntax. Since transitions are not guarded by
+ events, the transitions are "immediate" -->
+
+ <transition cond="${cookieOutcome eq 'authenticated'}"
+ target="exit"/>
+ <transition cond="${cookieOutcome eq 'unauthenticated'}"
+ target="logon"/>
+
+</state>
+</source>
+ </li>
+
+ <li>View state instances use event guards to wait for postback.
+<source>
+<!-- A "view" state, the default convention maps this state to
+ to the JSF view identifier "/logon" -->
+<state id="logon">
+
+ <!-- Wait for postback event, which is named "faces.outcome"
+ The reserved variable "outcome" contains the logical
+ outcome, which is used to conditionally transition
+ to the next state -->
+
+ <transition event="faces.outcome"
+ cond="${outcome eq 'authenticated'}"
+ target="exit"/>
+ <transition event="faces.outcome"
+ cond="${outcome eq 'create'}"
+ target="createProfile"/>
+
+</state>
+</source>
+ </li>
+
+ <li>Subdialog state instances may be mapped to external SCXML
+ documents (describing the subdialog) via the "src" attribute
+ of the SCXML <state> element.
+ </li>
+<source>
+<!-- A "subdialog" state, the "src" attribute points to the SCXML
+ document describing the subdialog. -->
+<state id="createProfile" src="edit-profile.xml">
+
+ <!-- Wait for <state_id>.done event, which lets us know
+ the subdialog has run to completion. This subdialog uses the
+ the "outcome" variable to convey its logical outcome to the
+ parent dialog (the SCXML <assign> element can be used
+ to assign values to existing variables) -->
+
+ <transition event="createProfile.done"
+ cond="${outcome eq 'success' or outcome eq 'cancel'}"
+ target="exit"/>
+ <transition event="createProfile.done"
+ cond="${outcome eq 'failure'}"
+ target="fail"/>
+
+</state>
+</source>
+ <li>End state instances may be mapped to SCXML final states.
+<source>
+<!-- An "end" state, signifies that the dialog has run to
+ completion, the default convention maps this state to
+ to the JSF view identifier "/exit". -->
+<state id="exit" final="true"/>
+</source>
+ Once the dialog reaches an end state, the dialog manager
+ cleans up the current instance of the executing dialog.
+ </li>
+
+ </ul>
+
+ </subsection>
+
+
+ <a name="dialog-scxml-using"/>
+ <subsection name="Using Dialog Manager (SCXML implementation)">
+
+ <p>To use the SCXML Dialog Manager facilities in Shale, take the following
+ steps:</p>
+
+ <ul>
+ <li>Model your dialog as a series of <em>State</em>s with transitions
+ between them labelled with the logical outcome that selects
+ that particular transition. A UML State Diagram is a very useful
+ mechanism for visualizing such a model. Then create a SCXML
+ document for each of the dialogs (dialog state machine diagrams can
+ be easily mapped to SCXML documents, see above section).</li>
+ <li>Build the views (and corresponding <code>ViewController</code> beans,
+ if you are also using the <a href="../shale-view/index.html">
+ Shale View Controller Support</a> functionality)
+ that comprise your dialog, using standard JavaServer Faces and
+ (optional) Shale <code>ViewController</code> facilities.</li>
+ <li>Declare your dialogs via an XML document, conventionally named
+ <code>/WEB-INF/dialog-config.xml</code>:
+<source>
+<dialogs>
+
+ <dialog name="FirstDialogName"
+ scxmlconfig="firstdialog.xml"
+ dataclassname="org.apache.shale.examples.FirstDialogData"
+ />
+
+ <dialog name="SecondDialogName"
+ scxmlconfig="seconddialog.xml"
+ dataclassname="org.apache.shale.examples.SecondDialogData"
+ />
+
+ ...
+
+</dialogs>
+</source></li>
+ <li>If you have more than one dialog configuration file, or you have
+ defined your only dialog configuration file as a web application
+ resource with a name different than the one described above, use
+ a context initiaization parameter to define a comma-delimited list
+ of context-relative paths to configuration resources to be loaded:
+<source>
+<context-param>
+ <param-name>org.apache.shale.dialog.scxml.CONFIGURATION</param-name>
+ <param-value>/WEB-INF/foo.xml,/WEB-INF/bar.xml</param-value>
+</context-param>
+</source></li>
+ <li>In addition to the dialog configuration resources defined by this
+ context initialization parameter, a resource named
+ <code>/WEB-INF/dialog-config.xml</code> will be automatically
+ processed, if it exists, and has not already been loaded.</li>
+ <li>Alternatively, or in addition to the above, any JAR file in
+ <code>/WEB-INF/lib</code> will be scanned for configuration
+ documents at <code>META-INF/dialog-config.xml</code>. Such
+ resources will be automatically processed, making it easy to
+ define JAR files with dialog configurations and corresponding
+ Java classes and resources, which are recognized simply by
+ including this JAR file in the application.</li>
+ <li>To initiate a dialog named "xxxxx", use one of the techniques
+ defined by the <a href="../shale-dialog/index.html#dialog-using">
+ Shale Dialog Manager</a>.</li>
+ </ul>
+
+ </subsection>
+
</section>
</body>