commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ra...@apache.org
Subject svn commit: r382201 - in /jakarta/commons/sandbox/scxml/trunk/xdocs: guide.xml guide/custom-actions.xml navigation.xml
Date Wed, 01 Mar 2006 23:50:40 GMT
Author: rahul
Date: Wed Mar  1 15:50:38 2006
New Revision: 382201

URL: http://svn.apache.org/viewcvs?rev=382201&view=rev
Log:
Add guide to custom actions with Commons SCXML.

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

Modified: jakarta/commons/sandbox/scxml/trunk/xdocs/guide.xml
URL: http://svn.apache.org/viewcvs/jakarta/commons/sandbox/scxml/trunk/xdocs/guide.xml?rev=382201&r1=382200&r2=382201&view=diff
==============================================================================
--- jakarta/commons/sandbox/scxml/trunk/xdocs/guide.xml (original)
+++ jakarta/commons/sandbox/scxml/trunk/xdocs/guide.xml Wed Mar  1 15:50:38 2006
@@ -66,7 +66,7 @@
    <p>Contains notes about Commons SCXML APIs for extending or
       altering document semantics.</p>
    <ul>
-    <li><!--a href="guide/custom-actions.html"-->Custom actions<!--/a-->
- Adding
+    <li><a href="guide/custom-actions.html">Custom actions</a> - Adding
     custom actions to the Commons SCXML object model.</li>
    </ul>
   </subsection>

Added: jakarta/commons/sandbox/scxml/trunk/xdocs/guide/custom-actions.xml
URL: http://svn.apache.org/viewcvs/jakarta/commons/sandbox/scxml/trunk/xdocs/guide/custom-actions.xml?rev=382201&view=auto
==============================================================================
--- jakarta/commons/sandbox/scxml/trunk/xdocs/guide/custom-actions.xml (added)
+++ jakarta/commons/sandbox/scxml/trunk/xdocs/guide/custom-actions.xml Wed Mar  1 15:50:38
2006
@@ -0,0 +1,185 @@
+<?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 actions with Commons SCXML</title>
+  <author email="commons-dev@jakarta.apache.org">Commons Documentation Team</author>
+ </properties>
+
+ <body>
+
+  <section name="What is a 'custom action'?">
+
+   <p>Actions are SCXML elements that "do" something. Actions can be
+      used where "executable content" is permissible, for example,
+      within &lt;onentry&gt;, &lt;onexit&gt; and &lt;transition&gt;
+      elements.</p>
+
+   <p>The <a href="http://www.w3.org/TR/scxml/">SCXML specification</a>
+      (currently a Working Draft) defines a set of "standard actions".
+      These include &lt;var&gt;, &lt;assign&gt;, &lt;log&gt;, &lt;send&gt;,
+      &lt;cancel&gt;, &lt;if&gt;, &lt;elseif&gt; and &lt;else&gt;.</p>
+
+   <p>The specification also allows implementations to define "custom actions"
+      in addition to the standard actions. What such actions "do" is
+      upto the author of these actions, and these are therefore
+      called "custom" since they are tied to a specific implementation
+      of the SCXML specification.</p>
+
+  </section>
+
+  <section name="Custom actions with Commons SCXML">
+
+   <p>Commons SCXML makes authoring custom actions fairly straightforward.</p>
+
+   <subsection name="What can be done via a custom action">
+
+    <p>A custom action in the Commons SCXML implementation has access to:
+     <ul>
+      <li>The current
+          <a href="../apidocs/org/apache/commons/scxml/Context.html">Context</a>
+          (and hence, the values of variables in the current Context).
+      </li>
+      <li>Any other Context within the document, provided the id of the
+          parent &lt;state&gt; is known.
+      </li>
+      <li>The expression
+          <a href="../apidocs/org/apache/commons/scxml/Evaluator.html">Evaluator</a>
+          for this document, and hence the ability to evaluate a given
+          expression against the current or a identifiable Context.
+      </li>
+      <li>The list of other actions in this
+          <a href="../apidocs/org/apache/commons/scxml/model/Executable.html">Executable</a>
+          .</li>
+      <li>The "root" Context, to examine any variable values in the
+          "document environment".</li>
+      <li>The
+          <a href="../apidocs/org/apache/commons/scxml/EventDispatcher.html">EventDispatcher</a>,
+          to send or cancel events.</li>
+      <li>The
+          <a href="../apidocs/org/apache/commons/scxml/ErrorReporter.html">ErrorReporter</a>,
+          to report any errors (that the ErrorReporter knows how to handle).</li>
+      <li>The histories, for any identifiable &lt;history&gt;.</li>
+      <li>The
+          <a href="../apidocs/org/apache/commons/scxml/NotificationRegistry.html">NotificationRegistry</a>,
+          to obtain the list of listeners attached to identifiable
+          "observers".</li>
+      <li>The engine log, to log any information it needs to.</li>
+     </ul>
+    </p>
+
+   </subsection>
+
+  </section>
+
+  <section name="Walkthrough - Adding a 'hello world' custom action">
+
+   <p>Lets walk through the development of a simple, custom "hello world"
+      action.</p>
+
+   <subsection name="Idea">
+
+    <p>We need a &lt;hello&gt; action in our (fictitious) namespace
+      "http://my.custom-actions.domain/CUSTOM". The action "tag" will
+      have one attribute "name". The action simply logs a hello to the
+      value of the name attribute when it executes.</p>
+
+   </subsection>
+
+   <subsection name="Custom action implementation">
+
+    <p>A custom action must extend the Commons SCXML
+       <a href="../apidocs/org/apache/commons/scxml/model/Action.html">Action</a>
+       abstract base class.</p>
+
+    <p>Here is the Java source for our custom
+       <a href="../xref-test/org/apache/commons/scxml/model/Hello.html">Hello</a>
+       action. The execute() method contains the logging statement.</p>
+
+   </subsection>
+
+   <subsection name="Registering the action with the digester">
+
+    <p>With the custom action implemented, obtain a configured digester which
+       has the "default" ruleset required for reading (parsing) SCXML
+       documents, and then register the custom action like so:</p>
+
+    <pre>
+      // (1) Get Digester with "default" rules for parsing SCXML documents
+      Digester digester = SCXMLDigester.newInstance(null, null);
+
+      // (2) Register the "custom" action(s)
+      SCXMLDigester.addCustomAction(digester,
+          "http://my.custom-actions.domain/CUSTOM", "hello", Hello.class);
+    </pre>
+
+    <p>This static addCustomAction() method can only be used if the custom
+       rule has no body content (child "tags") or if the custom action
+       implements the
+       <a href="../apidocs/org/apache/commons/scxml/model/ExternalContent.html">ExternalContent</a>
+       interface, in which any body content gets read into a list
+       of DOM nodes. For any other requirements, the digester rules
+       can be added by directly using the
+       <a href="http://jakarta.apache.org/commons/digester/commons-digester-1.7/docs/api/">digester
API</a>
+       .</p>
+
+   </subsection>
+
+   <subsection name="Read in the 'custom' SCXML document">
+
+    <p>This involves parsing the document and making the resulting
+       SCXML object executor-ready (which allows us to detect any
+       "model inconsistencies" before feeding it to the
+       execution engine. That amounts to:</p>
+
+    <pre>
+      // (3) Parse the SCXML document containing the custom action(s)
+      SCXML scxml = null;
+      try {
+          scxml = (SCXML) digester.parse(&lt;String&gt;);
+          //String method as an example
+      } catch (Exception e) {
+          // bad document, take necessary action
+      }
+      // (4) Wire up the object model for the SCXMLExecutor
+      SCXMLDigester.updateSCXML(scxml);
+    </pre>
+
+    <p>Without custom actions, the utility methods of the
+       <a href="../apidocs/org/apache/commons/scxml/io/SCXMLDigester.html">SCXMLDigester</a>
+       should be used. That section is
+       <a href="core-digester.html">here</a>.</p>
+
+   </subsection>
+
+
+   <subsection name="Launching the engine">
+
+    <p>Having obtained the SCXML object beyond step (4) above,
+       proceed as usual, see the section on the
+       <a href="core-engine.html">Commons SCXML engine</a>
+       for details.</p>
+
+   </subsection>
+
+  </section>
+
+ </body>
+
+</document>

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

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

Modified: jakarta/commons/sandbox/scxml/trunk/xdocs/navigation.xml
URL: http://svn.apache.org/viewcvs/jakarta/commons/sandbox/scxml/trunk/xdocs/navigation.xml?rev=382201&r1=382200&r2=382201&view=diff
==============================================================================
--- jakarta/commons/sandbox/scxml/trunk/xdocs/navigation.xml (original)
+++ jakarta/commons/sandbox/scxml/trunk/xdocs/navigation.xml Wed Mar  1 15:50:38 2006
@@ -42,8 +42,8 @@
         <item     name="Triggering Events"  
                   href="/guide/core-events.html" />
 
-        <!--item     name="Custom Actions"  
-                  href="/guide/core-events.html" /-->
+        <item     name="Custom Actions"
+                  href="/guide/custom-actions.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