Apache Commons logo Commons SCXML

Using Commons SCXML

Commons SCXML provides a generic event-driven state machine based execution environment, borrowing the semantics defined by SCXML. Most things that can be represented as a UML state chart -- business process flows, view navigation bits, interaction or dialog management, and too many more to list here -- can leverage the Commons SCXML library. The library can also be used by frameworks needing a process control language. This document is a bird's eye view about using Commons SCXML for individual (or framework) needs.


This document is divided into the following sections:

The interacting pieces

As with most library code, we have a fairly generic (and thereby reusable) asset, a specific domain and the "glue":

  1. The engine - Commons SCXML, a generic event-driven state machine based execution environment.
  2. The domain - The realization in software of the domain whose behavior we've defined via SCXML document(s).
  3. The bridge - The two way communication link, events flying from domain to state machine engine and activities being triggered in domain based on current states for the state machine.

The layer that is therefore needed is the bridge or glue to tie a specific usecase to the Commons SCXML engine. While the API aspects are dealt with in the core and advanced API sections of this user guide, the subsequent section provides a brief narrative introduction.

The interaction patterns

Here are some of the commons usage patterns for bridging (not a comprehensive list, plus none of these are mutually exclusive in any combination):

Mapping states to activities

This approach consists of maintaining some sort of lookup table that records what is to be done (i.e. the activity to be performed) when a particular state is reached. Event are fired on the engine, the executor is actively queried for current states, and those activities indicated by the lookup yield the next set of events (by causing some user interaction, or a change in application data model etc.) moving us forward.

This pattern is often useful when the activities are homogeneous (always activate a component of a specific type, always render a page and wait for submission etc.)

Listening to state machine progress

Commons SCXML allows processes to register listeners for notifications for state machine execution events (entry, exit, transition). Listeners implement the SCXMLListener interface. This approach is useful for:

  • Activities that have high likelihood of succeeding - such as UI updates
  • Managing side-effects, which are generally "passive" in nature with respect to the state machine execution

Using the send action and EventDispatcher

SCXML includes the <send> action to "dispatch" an event of choice (including whatever payload) to a specified target (of a specified type). The payload is delivered in the form of a namelist, which can be considered as params for the event target.

The callbacks are received on the EventDispatcher associated with the SCXMLExecutor. The EventDispatcher implementation activates the necessary target, which then performs the activity needed to make progress.

Using custom actions

Commons SCXML allows users to register custom actions with the Commons SCXML engine. Using custom actions in conjunction with derived events can lead to quite elegant authoring. The downsides are that this makes the solution non-portable (that is, it will not work on other SCXML engines -- if that is any cause for concern) and that the custom actions need to be authored by the user.

From a state machine theory point of view, actions are supposed to take negligible amount of time, so if lengthy activities need to be performed, using the <invoke> is more appropriate.

Using invoke to kickstart external processes

The <invoke> element is defined by the latest version of the W3C SCXML Working Draft. It allows the engine to invoke processes from simple states (those that don't have <parallel> or <state> children). The process may return a payload with the "done" event, that becomes available for decision making in the state machine context. Some related details are currently TBD in the Working Draft and therefore, susceptible to change.


The Commons SCXML usecases provide some examples.

  • The StopWatch usecases registers a SCXMLListener at the document root to manage the UI updates.