You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by ra...@apache.org on 2006/03/02 00:50:40 UTC
svn commit: r382201 - in /jakarta/commons/sandbox/scxml/trunk/xdocs:
guide.xml guide/custom-actions.xml navigation.xml
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 <onentry>, <onexit> and <transition>
+ 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 <var>, <assign>, <log>, <send>,
+ <cancel>, <if>, <elseif> and <else>.</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 <state> 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 <history>.</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 <hello> 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(<String>);
+ //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