commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ra...@apache.org
Subject svn commit: r382143 - in /jakarta/commons/sandbox/scxml/trunk/xdocs: guide.xml guide/scxml-documents.xml navigation.xml
Date Wed, 01 Mar 2006 20:22:04 GMT
Author: rahul
Date: Wed Mar  1 12:22:00 2006
New Revision: 382143

URL: http://svn.apache.org/viewcvs?rev=382143&view=rev
Log:
Add a "SCXML documents" section to the user guide.

Added:
    jakarta/commons/sandbox/scxml/trunk/xdocs/guide/scxml-documents.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=382143&r1=382142&r2=382143&view=diff
==============================================================================
--- jakarta/commons/sandbox/scxml/trunk/xdocs/guide.xml (original)
+++ jakarta/commons/sandbox/scxml/trunk/xdocs/guide.xml Wed Mar  1 12:22:00 2006
@@ -18,20 +18,37 @@
 <document>
 
  <properties>
-  <title>Commons SCXML API notes</title>
+  <title>Commons SCXML Guide</title>
   <author email="commons-dev@jakarta.apache.org">Commons Documentation Team</author>
  </properties>
 
  <body>
 
- <section name="Commons SCXML API notes">
+ <section name="Commons SCXML Guide">
 
-  <p>This is a collection of notes about the Commons SCXML API, a scratch pad of
+  <p>This is a collection of notes about all things Commons SCXML, a scratch pad of
   sorts, aimed at noting down usages for the frequently needed bits of Commons
-  SCXML and some interesting (to some of us) side-effects.
+  SCXML and some related and interesting (to some of us) tidbits.
   </p>
 
-  <subsection name="Core">
+  <subsection name="SCXML documents">
+   <p>State Chart XML (SCXML) is a general-purpose event-based state machine
+   language that can be used in many ways.</p>
+   <ul>
+    <li><a href="guide/scxml-documents.html">SCXML documents</a> - A five
+    minute introduction to SCXML documents.</li>
+   </ul>
+  </subsection>
+
+  <subsection name="Trying out Commons SCXML">
+   <p>Contains notes about trying Commons SCXML and testing SCXML documents.</p>
+   <ul>
+    <li><a href="guide/testing-standalone.html">Standalone</a> - Rev'ing
the
+    engine.</li>
+   </ul>
+  </subsection>
+
+  <subsection name="Core API">
    <p>Contains notes about the core Commons SCXML APIs.</p>
    <p>The first set of notes walks through the most common usage pattern,
    end-to-end.</p>
@@ -45,16 +62,17 @@
    </ul>
   </subsection>
 
-  <subsection name="Testing">
-   <p>Contains notes about trying Commons SCXML and testing SCXML documents.</p>
+  <subsection name="Advanced API">
+   <p>Contains notes about Commons SCXML APIs for extending or
+      altering document semantics.</p>
    <ul>
-    <li><a href="guide/testing-standalone.html">Standalone</a> - Rev'ing
the
-    engine.</li>
+    <li><!--a href="guide/custom-actions.html"-->Custom actions<!--/a-->
- Adding
+    custom actions to the Commons SCXML object model.</li>
    </ul>
   </subsection>
 
   <subsection name="Side-effects">
-   <p>Contains notes about interesting non-primary uses for Commons SCXML.</p>
+   <p>Contains notes about non-primary uses for Commons SCXML.</p>
    <ul>
     <li><a href="guide/side-effect-el.html">EL</a> - Trying Commons EL
outside
     a servlet container.</li>

Added: jakarta/commons/sandbox/scxml/trunk/xdocs/guide/scxml-documents.xml
URL: http://svn.apache.org/viewcvs/jakarta/commons/sandbox/scxml/trunk/xdocs/guide/scxml-documents.xml?rev=382143&view=auto
==============================================================================
--- jakarta/commons/sandbox/scxml/trunk/xdocs/guide/scxml-documents.xml (added)
+++ jakarta/commons/sandbox/scxml/trunk/xdocs/guide/scxml-documents.xml Wed Mar  1 12:22:00
2006
@@ -0,0 +1,190 @@
+<?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>Commons SCXML Usage - Five minute SCXML tutorial</title>
+  <author email="commons-dev@jakarta.apache.org">Commons Documentation Team</author>
+ </properties>
+
+ <body>
+
+  <section name="What is SCXML?">
+
+   <p>State Chart XML (SCXML) is a general-purpose event-based state
+      machine language that can be used in many ways.</p>
+
+   <p>The definitive guide to authoring SCXML documents is the
+      <a href="http://www.w3.org/TR/scxml/">W3C Working Draft
+      of the SCXML specification</a>.</p>
+
+  </section> 
+
+  <section name="Hello World">
+
+   <p>Here is the canonical
+      <a href="http://svn.apache.org/repos/asf/jakarta/commons/sandbox/scxml/trunk/src/test/java/org/apache/commons/scxml/hello-world.xml">hello
world example</a>
+      for SCXML. The interesting bits are:</p>
+
+   <pre>
+    &lt;scxml xmlns="http://www.w3.org/2005/07/SCXML"
+              version="1.0"
+              initialstate="hello"&gt;
+
+     &lt;state id="hello" final="true"&gt;
+      &lt;onentry&gt;
+       &lt;log expr="'hello world'" /&gt;
+      &lt;/onentry&gt;
+     &lt;/state&gt;
+
+    &lt;/scxml&gt;
+   </pre>
+
+   <p>
+    <ul>
+     <li>The document declares an initial state of "hello", which is the entry
+         point into the state machine.
+     </li>
+     <li>Once the state "hello" is entered the "executable content" contained
+         in the &lt;onentry&gt; is immediately executed.
+     </li>
+     <li>Similarly, there is also the symmetric &lt;onexit&gt;, which holds
+         executable content to be executed when a state is being exited.</li>
+     <li>The final attribute on state "hello" indicates that the state
+         machine has "run to completion".</li>
+     <li>Executable content is made of a series of "actions".</li>
+     <li>The "standard actions" defined by the SCXML specification are:
+         &lt;var&gt;, &lt;assign&gt;, &lt;log&gt;, &lt;send&gt;,
+         &lt;cancel&gt;, &lt;if&gt;, &lt;elseif&gt;, &lt;else&gt;.</li>
+    </ul>
+   </p>
+
+  </section>
+
+  <section name="Transitions">
+
+   <p>Transitions allow the state machine to change state. A transition is
+      "followed" if its "trigger event" is received, and the
+      "guard condition", if one is available is valid.
+   </p>
+
+   <p>Here are some transition variants:</p>
+
+   <pre>
+    &lt;!--
+      ... begin scxml, some states ...
+    --&gt;
+
+     &lt;state id="foo1"&gt;
+      &lt;!--
+        ... some content ...
+      --&gt;
+      &lt;transition&gt;
+       &lt;target next="bar" /&gt;
+      &lt;/transition&gt;
+     &lt;/state&gt;
+
+     &lt;state id="foo2"&gt;
+      &lt;!--
+        ... some content ...
+      --&gt;
+      &lt;transition event="foo.bar"&gt;
+       &lt;target next="bar" /&gt;
+      &lt;/transition&gt;
+     &lt;/state&gt;
+
+     &lt;state id="foo3"&gt;
+      &lt;!--
+        ... some content ...
+      --&gt;
+      &lt;transition event="foo.bar" cond="some-boolean-expression"&gt;
+       &lt;target next="bar" /&gt;
+      &lt;/transition&gt;
+     &lt;/state&gt;
+
+     &lt;state id="bar"&gt;
+      &lt;!--
+        ... some content ...
+      --&gt;
+     &lt;/state&gt;
+
+    &lt;!--
+       ... remaining states, end scxml ...
+    --&gt;
+   </pre>
+
+   <p>
+    <ul>
+     <li>The first transition in document order is an "immediate"
+         transition. "foo1" is the source, and "bar" is the
+         destination (transition target).
+     </li>
+     <li>The second transition waits for the trigger event "foo.bar".
+     </li>
+     <li>The third waits for "foo.bar" and the guard condition
+         specified by its "cond" attribute to evaluate to true
+         the instant the event is received.
+     </li>
+    </ul>
+   </p>
+
+  </section>
+
+  <section name="Hello World with a custom action">
+
+   <p>The Commons SCXML implementation allows you to register custom actions.
+      Here is the Commons SCXML
+      <a href="http://svn.apache.org/repos/asf/jakarta/commons/sandbox/scxml/trunk/src/test/java/org/apache/commons/scxml/custom-hello-world.xml">hello
world example using a custom action</a>.
+      The interesting bits are:</p>
+
+   <pre>
+    &lt;scxml xmlns="http://www.w3.org/2005/07/SCXML"
+              xmlns:my="http://my.custom-actions.domain/CUSTOM"
+              version="1.0"
+              initialstate="custom"&gt;
+
+     &lt;state id="custom" final="true"&gt;
+      &lt;onentry&gt;
+       &lt;my:hello name="world" /&gt;
+      &lt;/onentry&gt;
+     &lt;/state&gt;
+
+    &lt;/scxml&gt;
+   </pre>
+
+   <p>
+    <ul>
+     <li>&lt;my:hello&gt; is an example of a custom action whose local
+         name is "hello" and is bound to the fictitious namespace
+         "http://my.custom-actions.domain/CUSTOM"
+     </li>
+     <li>The custom action hello merely logs a hello to the value of
+         the name attribute, and thus the above example produces results
+         identical to the initial hello world example above.
+     </li>
+     <li>For details, see the section on
+         <!--a href="custom-actions.html"-->custom actions<!--/a--> in this guide.
+     </li>
+    </ul>
+   </p>
+
+  </section>
+
+ </body>
+
+</document>

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

Propchange: jakarta/commons/sandbox/scxml/trunk/xdocs/guide/scxml-documents.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=382143&r1=382142&r2=382143&view=diff
==============================================================================
--- jakarta/commons/sandbox/scxml/trunk/xdocs/navigation.xml (original)
+++ jakarta/commons/sandbox/scxml/trunk/xdocs/navigation.xml Wed Mar  1 12:22:00 2006
@@ -27,6 +27,12 @@
                   href="/guide.html"
                   collapse="true">
 
+        <item     name="SCXML documents"  
+                  href="/guide/scxml-documents.html" />
+
+        <item     name="Standalone Testing"  
+                  href="/guide/testing-standalone.html" />
+
         <item     name="SCXML Digester"  
                   href="/guide/core-digester.html" />
 
@@ -36,8 +42,8 @@
         <item     name="Triggering Events"  
                   href="/guide/core-events.html" />
 
-        <item     name="Standalone Testing"  
-                  href="/guide/testing-standalone.html" />
+        <!--item     name="Custom Actions"  
+                  href="/guide/core-events.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