Tuesday, June 26, 2012

Easy Finite State Machine Implementation with Apache Commons SCXML

This article mentions about Finite State Machines (FSM), SCXML (State Chart extensible Markup Language)  and Apache Common's SCXML library. A basic ATM finite state machine sample code is also provided with the article.

Finite State Machines:

You probably remember Finite State Machines from your Computer Science courses. FSMs are used to design computer programs or digital circuits.

A sample Finite State Machine [2]

A FSM is simply an abstract machine that can be in one of a finite number of states.The machine is in only one state at a time; the state it is in at any given time is called the current state. It can change from one state to another when initiated by a triggering event or condition, this is called a transition. A particular FSM is defined by a list of the possible transition states from each current state, and the triggering condition for each transition. [1]

SCXML Language:

A working draft called SCXML (State Machine Notation for Control Abstraction, published by W3C) can be used to describe complex state machines. SCXML is a general-purpose xml-based state machine language. It is still a draft and latest version is 16 February 2012. Click here to get five minute introduction to SCXML documents.

Apache Commons SCXML Library:

Apache has an implementation aimed at creating and maintaining a Java SCXML engine capable of executing a state machine defined using a SCXML document, while abstracting out the environment interfaces. The latest stable version is 0.9.
Library Website: http://commons.apache.org/scxml/index.html
Eclipse Plugin: http://commons.apache.org/sandbox/gsoc/2010/scxml-eclipse/ (still under development)
UseCases: http://commons.apache.org/scxml/usecases.html
SCXML Editors:

Apache's Eclipse Plugin aims to provide a visual editor to edit SCXML files but it is still under development. There is also scxml gui ( http://code.google.com/p/scxmlgui/ ) which is very successful. You can also check State Forge's visual State Machine Diagram :  http://www.stateforge.com/StateMachineDiagram/StateMachineDiagram.html

Code Sample :

In this part of the article, we will implement a basic ATM Status state-machine. As a brief information, we assume an ATM can have following statuses. :

  • idle: When ATM has no activity, simply it is closed
  • loading: when an idle atm tries to connect to ATM Server, configs and info is started loading
  • Out-of-service: If ATM loading fails or ATM is shutdown
  • In-service: If ATM laoding is successful or ATM is started up
  • Disconnected: If ATM is not connected to network

Sorry for the missing or incorrect information about ATM statuses. This is just an example :)

Let's first draw our state machine using scxmlgui program. One can write his own scxml file but scxmlgui does that ugly task for you. Here is the state chart diagram which describes the status change of an ATM :

And the output SCXML file describing the transitions in the diagram above:

Our FSM implemantation is in AtmStatusFSM class.
  • AtmStatusFSM class extends org.apache.commons.scxml.env.AbstractStateMachine
  • FSM is configured by giving the scxml file (atm_status.xml) path to super constructor. 
  • ATM state changes are controlled by events. When fireEvent method is called with related event name [e.g. fireEvent("atm.connected")], FSM state is updated automatically. You can get current state whenever you want.
  • You can also write public methods having the state names of our FSM. These methods are called when the corresponding state is activated.

We have the following enum file to describe our events. You don't have to code such a class, but it might help to define the events. You can also get those events dynamically using getEngine().getCurrentStatus().getEvents()code fragment.

You can see the basic GUI code below. The GUI first shows the possible events that can be fired. When an event is selected and submitted, current ATM status is displayed and event list is updated.

The output of our simple program :

The project files (with required libraries) as shown in Eclipse are given in the following image:

For full source code visit https://github.com/ozkansari/atmstatemachine

[2] Managing the MIDlet Life-Cycle with a Finite State Machine  : http://developers.sun.com/mobility/midp/articles/fsm/

This article is also introduced in DZone.


  1. Great example. Can you please post another one, showcasing use of invokers and listeners.

  2. thankyou for such a good explanation