##### Commons SCXML Resources

- Overview
- User Guide
  - SCXML documents
  - Using Commons SCXML
  - Standalone Testing
  - SCXML Digester
  - SCXML datamodel
  - Contexts and Evaluators
  - SCXML Engine
  - Triggering Events
  - Custom Actions
  - Custom Semantics
  - Side Effect - EL
- Javadoc
- FAQ
- Usecases
- Building
- Dependencies
- Mailing lists
- Team
- SVN repository
- Nightly snapshots

##### Project Documentation

- About
- Project Info
- Project Reports
- Development Process

##### Commons

- Home
- Components
- Sandbox
- Dormant
- Volunteering
- Contributing Patches
- Building Components
- Releasing Components
- Wiki

##### Legend

- External Link
- Opens in a new window

## Commons SCXML - Creating and configuring the SCXML engine

The Commons SCXML executor is the engine that runs the state machine.

### Usage

The `SCXMLExecutor` is usually initialized as follows:

            //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
            }

### Explanation

The SCXML specification allows implementations to support multiple expression languages so SCXML documents can be used in varying environments. The `Context` and `Evaluator` 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 contexts and evaluators for further details about contexts, evaluators and root contexts.

Commons SCXML provides an EventDispatcher 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 `EventDispatcher` implementation provided to the executor. The introductory section on using Commons SCXML has a brief discussion on interaction patterns, including <send> usage.

The ErrorReporter 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.

Commons SCXML also allows listeners (SCXMLListener) to be registered with the `SCXMLExecutor`, which are informed about the progress of the state machine via `onEntry` and `onExit` notifications for `State`s, as well as `onTransition` notifications when transitions are followed.

Commons SCXML provides basic implementations of the `EventDispatcher`, `ErrorReporter`, and `SCXMLListener` interfaces in the env package, which simply log all the events received. Commons SCXML uses Commons Logging.

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

The `SCXMLExecutor` Javadoc is available here.

### API notes set

The previous note in this set describes the SCXML digester.
The next note in this set describes triggering events.