##### Commons SCXML Resources

- Overview
- User Guide
  - SCXML documents
  - Using Commons SCXML
  - Standalone Testing
  - SCXML Parser
  - 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

##### Releases

- Version 0.7
- Version 0.6
- Version 0.5

##### 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 - Firing events on the SCXML engine

Once the SCXML engine has been initialized, the state machine progresses based on the events that are fired on it. When an event is fired, if the current set of states have transitions waiting for that event, and the guard condition on one of those transitions is satisfied, the state machine is said to "follow" that transition, which may possibly yield a new set of current states. Most state machines will ultimately reach a "final" state, wherein the state machine has said to have executed to completion.

### Basic Usage

An event "foo.bar" may be fired on the engine as follows:

            //import org.apache.commons.scxml.SCXMLExecutor;
            //import org.apache.commons.scxml.TriggerEvent;
            //import org.apache.commons.scxml.model.ModelException;

            // where "exec" is the SCXMLExecutor instance
            TriggerEvent te = new TriggerEvent("foo.bar",
                                  TriggerEvent.SIGNAL_EVENT);
            try {
                exec.triggerEvent(te);
            } catch (ModelException me) {
                // The events left the engine in inconsistent state
            }

If the resulting events leave the state machine in an inconsistent state, a `ModelException` may be thrown.

### Event Payloads

Furthermore, events can carry within them a `payload` property that consists of some information that is useful for the guard conditions or executable content while the engine is processing the event. The payload can be any user-defined type.

            //import org.apache.commons.scxml.SCXMLExecutor;
            //import org.apache.commons.scxml.TriggerEvent;
            //import org.apache.commons.scxml.model.ModelException;

            // where "exec" is the SCXMLExecutor instance
            // and "foo" is an object (payload) with an accessible property "bar"
            TriggerEvent te = new TriggerEvent("event.with.payload",
                                  TriggerEvent.SIGNAL_EVENT, foo);
            try {
                exec.triggerEvent(te);
            } catch (ModelException me) {
                // The events left the engine in inconsistent state
            }

The payload in the above example can now be used in expressions, as the special variable "_eventdata". For example, assuming a JEXL expressions based document, transitions may look like (similarly "_eventdata" may be used in executable content in corresponding <onexit>, <transition> and <onentry> bodies).

             <transition event="event.with.payload"
                            cond="_eventdata.bar eq 'bar1'" next="state1" />
             <transition event="event.with.payload"
                            cond="_eventdata.bar eq 'bar2'" next="state2" />

### Multiple Events

More than one events may be triggered on the state machine at a time (using `triggerEvents()` method -- plural). After the engine processes a set of trigger events, it is customary to check whether the state machine has reached a <final> state. All events will operate over the same states ancestor closure.

### Running to completion

The following snippet illustrates how the `SCXMLExecutor` `Status` is queried for state machine run to completion.

            //import org.apache.commons.scxml.SCXMLExecutor;
            //import org.apache.commons.scxml.Status;

            // where "exec" is the SCXMLExecutor instance
            Status status = exec.getCurrentStatus();
            if (status.isFinal()) {
                // run to completion, release cached objects
            }

The `TriggerEvent` Javadoc is available here.
The `Status` Javadoc is available here

### API notes set

The previous note in this set describes the SCXML engine.