xdocs/guide/core-engine.xml - commons-scxml - Git at Google

 <?xml version="1.0" encoding="UTF-8"?>
 <!--
  * Licensed to the Apache Software Foundation (ASF) under one or more
  * contributor license agreements.  See the NOTICE file distributed with
  * this work for additional information regarding copyright ownership.
  * The ASF licenses this file to You 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 - API notes - Engine</title>
   <author email="dev@commons.apache.org">Commons Documentation Team</author>
  </properties>

  <body>

   <section name="Commons SCXML - Creating and configuring the SCXML engine">

    <p>The Commons SCXML executor is the engine that runs the state machine.</p>

    <subsection name="Usage">
      <p>The <code>SCXMLExecutor</code> is usually initialized as follows:</p>
      <pre>
         //import org.apache.commons.scxml.Context;
         //import org.apache.commons.scxml.ErrorReporter;
         //import org.apache.commons.scxml.Evaluator;
         //import org.apache.commons.scxml.EventDispatcher;
         //import org.apache.commons.scxml.SCXMLExecutor;
         //import org.apache.commons.scxml.SCXMLListener;
         //import org.apache.commons.scxml.model.SCXML;
         //import org.apache.commons.scxml.model.ModelException;

         SCXMLExecutor exec = null;
         try {
             exec = new SCXMLExecutor(&lt;Evaluator&gt;,
                        &lt;EventDispatcher&gt;, &lt;ErrorReporter&gt;);
             exec.setStateMachine(&lt;SCXML&gt;);
             exec.addListener(&lt;SCXML&gt;, &lt;SCXMLListener&gt;);
             exec.setRootContext(&lt;Context&gt;);
             exec.go();
         } catch (ModelException me) {
             // Executor initialization failed, because the
             // state machine specified has inconsistencies
         }
      </pre>
    </subsection>

    <subsection name="Explanation">
      <p>The SCXML specification allows implementations to support multiple
      expression languages so SCXML documents can be used in varying
      environments. The <code>Context</code> and <code>Evaluator</code>
      interfaces serve as adapters to the particular expression language
      APIs. Commons SCXML currently supports JEXL and JSP 2.0 EL
      expressions. See the section on
      <a href="contexts-evaluators.html">contexts and evaluators</a>
      for further details about contexts, evaluators and root contexts.</p>

      <p>Commons SCXML provides an
      <a href="../apidocs/org/apache/commons/scxml/EventDispatcher.html">EventDispatcher</a>
      interface for wiring the behavior of SCXML &lt;send&gt; and
      &lt;cancel&gt; actions. This allows users to define custom "targettypes"
      as long as they handle the callbacks on the <code>EventDispatcher</code>
      implementation provided to the executor. The introductory section on
      using Commons SCXML has a brief discussion on
      <a href="using-commons-scxml.html">interaction patterns</a>, including
      &lt;send&gt; usage.</p>

      <p>The
      <a href="../apidocs/org/apache/commons/scxml/ErrorReporter.html">ErrorReporter</a>
      interface is used by Commons SCXML for reporting SCXML errors to the host
      environment, and contains the definition of commonly occuring errors
      while executing SCXML documents. It is primarily used for passive usages
      such as logging.</p>

      <p>Commons SCXML also allows listeners
      (<a href="../apidocs/org/apache/commons/scxml/SCXMLListener.html">SCXMLListener</a>)
      to be registered with the <code>SCXMLExecutor</code>, which are informed
      about the progress of the state machine via <code>onEntry</code> and
      <code>onExit</code> notifications for <code>State</code>s, as
      well as <code>onTransition</code> notifications when transitions are
      followed.</p>

      <p>Commons SCXML provides basic implementations of the
      <code>EventDispatcher</code>, <code>ErrorReporter</code>, and
      <code>SCXMLListener</code> interfaces in the
      <a href="../apidocs/org/apache/commons/scxml/env/package-summary.html">env package</a>,
      which simply log all the events received. Commons SCXML uses
      Commons Logging.</p>

      <p>The executor is "set into motion" using the marker method
      <code>SCXMLExecutor#go()</code>. The <code>SCXMLExecutor</code> instances
      are <b>not</b> thread-safe, and need external synchronization if the
      usecase demands.</p>

      <p>The <code>SCXMLExecutor</code> Javadoc is available
      <a href="../apidocs/org/apache/commons/scxml/SCXMLExecutor.html">
      here</a>.
      </p>
    </subsection>

    <subsection name="API notes set">
     <p>The previous note in this set describes the
     <a href="core-parser.html">SCXML parser</a>.<br/>
     The next note in this set describes
     <a href="core-events.html">triggering events</a>.</p>
    </subsection>

   </section>

  </body>

 </document>
	<?xml version="1.0" encoding="UTF-8"?>
	<!--
	* Licensed to the Apache Software Foundation (ASF) under one or more
	* contributor license agreements. See the NOTICE file distributed with
	* this work for additional information regarding copyright ownership.
	* The ASF licenses this file to You 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 - API notes - Engine</title>
	<author email="dev@commons.apache.org">Commons Documentation Team</author>
	</properties>

	<body>

	<section name="Commons SCXML - Creating and configuring the SCXML engine">

	<p>The Commons SCXML executor is the engine that runs the state machine.</p>

	<subsection name="Usage">
	<p>The <code>SCXMLExecutor</code> is usually initialized as follows:</p>
	<pre>
	//import org.apache.commons.scxml.Context;
	//import org.apache.commons.scxml.ErrorReporter;
	//import org.apache.commons.scxml.Evaluator;
	//import org.apache.commons.scxml.EventDispatcher;
	//import org.apache.commons.scxml.SCXMLExecutor;
	//import org.apache.commons.scxml.SCXMLListener;
	//import org.apache.commons.scxml.model.SCXML;
	//import org.apache.commons.scxml.model.ModelException;

	SCXMLExecutor exec = null;
	try {
	exec = new SCXMLExecutor(<Evaluator>,
	<EventDispatcher>, <ErrorReporter>);
	exec.setStateMachine(<SCXML>);
	exec.addListener(<SCXML>, <SCXMLListener>);
	exec.setRootContext(<Context>);
	exec.go();
	} catch (ModelException me) {
	// Executor initialization failed, because the
	// state machine specified has inconsistencies
	}
	</pre>
	</subsection>

	<subsection name="Explanation">
	<p>The SCXML specification allows implementations to support multiple
	expression languages so SCXML documents can be used in varying
	environments. The <code>Context</code> and <code>Evaluator</code>
	interfaces serve as adapters to the particular expression language
	APIs. Commons SCXML currently supports JEXL and JSP 2.0 EL
	expressions. See the section on
	<a href="contexts-evaluators.html">contexts and evaluators</a>
	for further details about contexts, evaluators and root contexts.</p>

	<p>Commons SCXML provides an
	<a href="../apidocs/org/apache/commons/scxml/EventDispatcher.html">EventDispatcher</a>
	interface for wiring the behavior of SCXML <send> and
	<cancel> actions. This allows users to define custom "targettypes"
	as long as they handle the callbacks on the <code>EventDispatcher</code>
	implementation provided to the executor. The introductory section on
	using Commons SCXML has a brief discussion on
	<a href="using-commons-scxml.html">interaction patterns</a>, including
	<send> usage.</p>

	<p>The
	<a href="../apidocs/org/apache/commons/scxml/ErrorReporter.html">ErrorReporter</a>
	interface is used by Commons SCXML for reporting SCXML errors to the host
	environment, and contains the definition of commonly occuring errors
	while executing SCXML documents. It is primarily used for passive usages
	such as logging.</p>

	<p>Commons SCXML also allows listeners
	(<a href="../apidocs/org/apache/commons/scxml/SCXMLListener.html">SCXMLListener</a>)
	to be registered with the <code>SCXMLExecutor</code>, which are informed
	about the progress of the state machine via <code>onEntry</code> and
	<code>onExit</code> notifications for <code>State</code>s, as
	well as <code>onTransition</code> notifications when transitions are
	followed.</p>

	<p>Commons SCXML provides basic implementations of the
	<code>EventDispatcher</code>, <code>ErrorReporter</code>, and
	<code>SCXMLListener</code> interfaces in the
	<a href="../apidocs/org/apache/commons/scxml/env/package-summary.html">env package</a>,
	which simply log all the events received. Commons SCXML uses
	Commons Logging.</p>

	<p>The executor is "set into motion" using the marker method
	<code>SCXMLExecutor#go()</code>. The <code>SCXMLExecutor</code> instances
	are <b>not</b> thread-safe, and need external synchronization if the
	usecase demands.</p>

	<p>The <code>SCXMLExecutor</code> Javadoc is available
	<a href="../apidocs/org/apache/commons/scxml/SCXMLExecutor.html">
	here</a>.
	</p>
	</subsection>

	<subsection name="API notes set">
	<p>The previous note in this set describes the
	<a href="core-parser.html">SCXML parser</a>.<br/>
	The next note in this set describes
	<a href="core-events.html">triggering events</a>.</p>
	</subsection>

	</section>

	</body>

	</document>