commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ra...@apache.org
Subject svn commit: r399857 - in /jakarta/commons/proper/scxml/trunk/xdocs: guide.xml guide/custom-semantics.xml navigation.xml
Date Thu, 04 May 2006 20:42:44 GMT
Author: rahul
Date: Thu May  4 13:42:41 2006
New Revision: 399857

URL: http://svn.apache.org/viewcvs?rev=399857&view=rev
Log:
Throw in another section on custom semantics into the user guide, since this has become documentation
day already.

Added:
    jakarta/commons/proper/scxml/trunk/xdocs/guide/custom-semantics.xml   (with props)
Modified:
    jakarta/commons/proper/scxml/trunk/xdocs/guide.xml
    jakarta/commons/proper/scxml/trunk/xdocs/navigation.xml

Modified: jakarta/commons/proper/scxml/trunk/xdocs/guide.xml
URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/scxml/trunk/xdocs/guide.xml?rev=399857&r1=399856&r2=399857&view=diff
==============================================================================
--- jakarta/commons/proper/scxml/trunk/xdocs/guide.xml (original)
+++ jakarta/commons/proper/scxml/trunk/xdocs/guide.xml Thu May  4 13:42:41 2006
@@ -74,6 +74,9 @@
    <ul>
     <li><a href="guide/custom-actions.html">Custom actions</a> - Adding
     custom actions to the Commons SCXML object model.</li>
+    <li><a href="guide/custom-semantics.html">Custom semantics</a> - Changing
+    the default semantics of the Commons SCXML engine for specialized
+    uses.</li>
    </ul>
   </subsection>
 

Added: jakarta/commons/proper/scxml/trunk/xdocs/guide/custom-semantics.xml
URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/scxml/trunk/xdocs/guide/custom-semantics.xml?rev=399857&view=auto
==============================================================================
--- jakarta/commons/proper/scxml/trunk/xdocs/guide/custom-semantics.xml (added)
+++ jakarta/commons/proper/scxml/trunk/xdocs/guide/custom-semantics.xml Thu May  4 13:42:41
2006
@@ -0,0 +1,97 @@
+<?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 custom semantics for the Commons SCXML engine</title>
+  <author email="commons-dev@jakarta.apache.org">Commons Documentation Team</author>
+ </properties>
+
+ <body>
+
+  <section name="SCXML Semantics">
+
+   <p><b>This section is for advanced users only, and will probably not
+   be needed by most users of the Commons SCXML library.</b></p>
+
+   <subsection name="Pluggable semantics">
+
+    <p>The Commons SCXML state machine engine is really a tuple, the
+    <a href="../apidocs/org/apache/commons/scxml/SCXMLExecutor.html">SCXMLExecutor</a>
+    (an API that new users can code to, and is almost always sufficient)
+    accompanied by a
+    <a href="../apidocs/org/apache/commons/scxml/SCXMLSemantics.html">SCXMLSemantics</a>
+    implementation (an API that advanced users can code to, to change the
+    engine behavior to suit their needs).</p>
+    
+    <p>The basic modus operandi for an engine is simple - when an event is
+    triggered, figure out which (if any) transition(s) to follow, and
+    transit to the new set of states executing any specified actions along
+    the way. The default semantics available in the Commons SCXML distribution
+    can be replaced with custom semantics provided by the user using the
+    <code>SCXMLExecutor</code> constructor that takes the
+    <code>SCXMLSemantics</code> parameter i.e. the engine semantics are
+    "pluggable".</p>
+
+   </subsection>
+
+   <subsection name="Example scenario">
+
+    <p>Consider dispute resolution for example -- when more than one
+    outbound transitions from a single state hold true. The default
+    <code>SCXMLSemantics</code> implementation available in the distribution
+    is puristic, it will throw a <code>ModelException</code>. However, a user
+    may want:</p>
+
+    <ul>
+     <li>The transition defined closest to the document root to be
+     followed</li>
+     <li>The transition defined farthest from the document root to be
+     followed</li>
+     <li>The transition whose origin and target have the lowest common
+     ancestor to be followed</li>
+     <li>The transition whose origin and target have the highest common
+     ancestor to be followed</li>
+    </ul>
+
+    <p>Even after one of above dispute resolution algorithms is applied, if
+    there are more than one candidate transitions, the user may want:</p>
+
+    <ul>
+     <li>A <code>ModelException</code> to be thrown</li>
+     <li>The transition that appears first in document order to be
+     followed</li>
+     <li>The transition that appears last in document order to be
+     followed</li>
+    </ul>
+
+    <p>To implement any of the above choices, the user may extend the
+    default <code>SCXMLSemantics</code> implementation, override the
+    <code>filterTransitionsSet()</code> method (or write a new implementation
+    from scratch), and plug in the new semantics while instantiating the
+    <code>SCXMLExecutor</code>. The pluggability allows differing semantics
+    to be developed for the Commons SCXML engine, independent of the Commons
+    SCXML codebase.</p>
+
+   </subsection>
+
+  </section>
+
+ </body>
+
+</document>

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

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

Modified: jakarta/commons/proper/scxml/trunk/xdocs/navigation.xml
URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/scxml/trunk/xdocs/navigation.xml?rev=399857&r1=399856&r2=399857&view=diff
==============================================================================
--- jakarta/commons/proper/scxml/trunk/xdocs/navigation.xml (original)
+++ jakarta/commons/proper/scxml/trunk/xdocs/navigation.xml Thu May  4 13:42:41 2006
@@ -66,6 +66,9 @@
         <item     name="Custom Actions"
                   href="/guide/custom-actions.html" />
 
+        <item     name="Custom Semantics"
+                  href="/guide/custom-semantics.html" />
+
         <item     name="Side Effect - EL"  
                   href="/guide/side-effect-el.html" />
 



---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org


Mime
View raw message