##### 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

## SCXML Semantics

This section is for advanced users only, and will probably not be needed by most users of the Commons SCXML library.

### Pluggable semantics

The Commons SCXML state machine engine is really a tuple, the SCXMLExecutor (an API that new users can code to, and is almost always sufficient) accompanied by a SCXMLSemantics implementation (an API that advanced users can code to, to change the engine behavior to suit their needs).

The basic modus operandi for an engine is simple - when an event is triggered, figure out which (if any) transition(s) to follow, and transit to the new set of states executing any specified actions along the way. The default semantics available in the Commons SCXML distribution can be replaced with custom semantics provided by the user using the `SCXMLExecutor` constructor that takes the `SCXMLSemantics` parameter i.e. the engine semantics are "pluggable".

### Example scenario

Consider dispute resolution for example -- when more than one outbound transitions from a single state hold true. The default `SCXMLSemantics` implementation available in the distribution does none, it will follow all filtered transitions, possibly leading to a `ModelException` immediately or down the road. However, a user may want:

- The transition defined closest to the document root to be followed
- The transition defined farthest from the document root to be followed
- The transition whose origin and target have the lowest common ancestor to be followed
- The transition whose origin and target have the highest common ancestor to be followed

Even after one of above dispute resolution algorithms is applied, if there are more than one candidate transitions, the user may want:

- A `ModelException` to be thrown
- The transition that appears first in document order to be followed
- The transition that appears last in document order to be followed

To implement any of the above choices, the user may extend the default `SCXMLSemantics` implementation, override the `filterTransitionsSet()` method (or write a new implementation from scratch), and plug in the new semantics while instantiating the `SCXMLExecutor`. The pluggability allows differing semantics to be developed for the Commons SCXML engine, independent of the Commons SCXML codebase.