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