Apache Commons logo Commons SCXML

Using SCXML documents to define behavior

SCXML documents (more generically, UML state chart diagrams) can be used to define stateful behavior of objects, and Commons SCXML enables developers to take this model directly into the corresponding code artifacts. The resulting artifacts tend to be much simpler, embody a useful separation of concerns and are easier to understand and maintain.


  • Demonstrate a "standalone" usecase of Commons SCXML
  • Demonstrate the useful separation of concerns, the simplicity of the resulting artifacts, and the direct association between the model and the code when using Commons SCXML to incorporate behavior.

Sample walkthrough - From model to working code

Here is a short exercise in modeling and implementing an object with stateful behavior. A stopwatch -- for anyone who may need an introduction -- is used to measure duration, with one button for starting and stopping the watch and another one for pausing the display (also known as "split", where the watch continues to keep time while the display is frozen, to measure, for example, "lap times" in races). Once the watch has been stopped, the start/stop button may be used to reset the display.

The Model - UML Diagram

Here is the state chart diagram that describes the behavior of this particular stopwatch:
stopwatch state chart diagram
(Zoom out)

The SCXML document

The SCXML document is then, a simple serialization of the "model" above: stopwatch.xml.

The Stopwatch class

Here is the class that implements the stopwatch behavior, StopWatch.java. The class extends AbstractStateMachine.java, which provides one approach for providing the base functionality needed by classes representing stateful entities. Points to note in the StopWatch class are:

  • The "lifecycle" is defined by the SCXML document, which is an artifact easily derived from the modeling layer.
  • The code is much simpler, since the lifecycle management task has been assigned to Commons SCXML.

The Stopwatch UI

Here is the UI for our demonstration, StopWatchDisplay.java. Points to note here are:

  • The UI is "backed" by a StopWatch instance.
  • It merely relays the user initiated events (in this case, button clicks) to the Commons SCXML driven StopWatch instance by serving as an intermediary / proxy.
  • The UI and application behavior separation is thus, and usefully, pronounced.

The result

(Figure 1: Begin in state "reset")

(Figure 2: Start puts the stopwatch in "running" state)

(Figure 3: Split causes the stopwatch to be "paused")

(Figure 4: Unsplit puts the stopwatch back in "running")

(Figure 5: "stopped")

(Figure 6: Rinse and repeat - "reset")