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