<?xml version="1.0" encoding="UTF-8"?>
<!--
   Copyright 2005-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 - API notes - Engine</title>
  <author email="commons-dev@jakarta.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.
   Commons SCXML also allows listeners to be added to 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>TransitionTarget</code>s, as well as
   <code>onTransition</code> notificatins when transitions are followed.</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.setSuperStep(true);
            exec.go();
        } catch (ModelException me) {
            // Executor initialization failed, because the
            // state machine specified has inconsistencies
        }
     </pre>

     <p>Commons SCXML provides basic implementations of the
     <code>EventDispatcher</code>, <code>ErrorReporter</code>, and
     <code>SCXMLListener</code> interfaces, which simply log
     all the events received. Commons SCXML uses Commons Logging.</p>

     <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.</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-digester.html">SCXML digester</a>.<br/>
    The next note in this set describes
    <a href="core-events.html">triggering events</a>.</p>
   </subsection>

  </section>

 </body>

</document>