<< Waffle Theorem | Home | How Brontosaurs kill Raptors >>

Persistent State Machine with Apache SCXML

The source code for this blog article can be downloaded here.

I'm bored of reinventing the wheel. Everytime I need a state machine to ensure my states traverse only valid transitions, I find myself either not bothering, because I trust my coding (and write all the necessary unit tests of course), or writing very similar code over again.

So I started wondering if there was a configurable state machine out there somewhere, and in no time at all Google gave me a link to SCXML from Apache. Apache SCXML is an implementation of a configurable state machine based on the SCXML working draft from W3C.

I started by taking a look at what it does and how it works, always keeping in mind my requirements based on previous projects. The main question was how I could use a state machine in a persistent entity so that when an attempt is made to change the state, the state machine validated the attempt, ensuring only valid transitions are carried out. That meant two things:
  • The state machine had to be able to have its current state set to any state. If I load an object with state out of the database, I need to be able to set that state in the state machine so that it checks any attempts to change state, based on this starting state.
  • The state machine had to fit into a JPA entity class so that I could persist and load the state.

Apache SCXML doesn't come with great documentation but if you look around, it has some "use cases" which are examples of how you can use it. It comes with the class org.apache.commons.scxml.env.AbstractStateMachine which uses reflection to trigger transitions. I went for a slightly different approach and created the uk.co.maxant.demo.scxml.util.AbstractStateMachine, which wraps an instance of the SCXMLExecutor (the "engine", or state machine itself). By wrapping the state machine, I am able to provide two extra benefits:
  • I can construct the state machine using the starting state out of a persisted entity, rather than being forced to use the state charts initial state. The implementation details of this construction are a little complicated so my abstract wrapper can hide the details from the caller who is more interested in writing some business code, rather than boiler plate code.
  • I can enforce only valid state transitions, in that before performing a transition, I can use the state machine to check if its a valid transition from the current state. Apache SCXMLs default handling means that if you try to set the state to an illegal state, the state machine simply does nothing. I prefer to be a little harsher and throw an IllegalStateException!

The implementation of the AbstractStateMachine contains trigger methods for changing state via transition events. Each event makes a simple call to the AbstractStateMachine.trigger(String) method which first of all checks that the current state allows the transition, and second of all delegates the transition to the wrapped state machine instance. If the requested state transition is illegal, then an IllegalStateException with details of the problem is thrown. I too, could have also used reflection like the Apache example, but prefer to write more readable code for this Blog.

Apache SCXML is built up by creating an SCXML instance which is based upon the configuration which is an XML representation of the state chart and can be generated from UML. As such, this configuration has an initial state, as defined in your state chart. You then create an instance of the engine (state machine, SCXMLExecutor) which is responsible for running with the configuration. For performance reasons, the configuration should only be created once, as it parses the XML document. In my demo, I instantiated it at class load time in the subclass of AbstractStateMachine.

So what do you do, if you are loading an object from a persistent store like a database and you want to instantiate your state machine (SCXMLExecutor) with a state other than the initial state? Well, it's quite easy, you simply use the API to modify the current state of the state machine (SCXMLExecutor) instance and set the initial state to be that, which your persisted entity currently has. The method isn't setCurrentState(), rather you use the current state object, and remove its states and set the relevant state which you retrieved from the configuration (SCXML). Have a look at AbstractStateMachine.setInitialState(SCXMLExecutor, String) to see how. Thanks to the SCXML team for showing me how to do this!

So having done all that, I was now in a position to use the state machine to manage the state in a persistent entity. I created a database table with a varchar column for holding my state, and primary key. In the real world, the state would be part of a much larger entity with other fields. I then setup my Eclipse project to contain the JPA facet and by right clicking on the project was able to generate my JPA entity classes from the table, such as shown in the SomethingPersistentWithState class. The only special thing I did, was to select "property based access" as the way in which JPA accesses the attributes. Normally, and by default, JPA uses field based access, i.e. it uses reflection at runtime to get and set the class attributes. By selecting "property based access", Eclipse generates an additional Annotation on my entity class: @Access(AccessType.PROPERTY). I then had only three things to do:
  • Change the "state" class attribute from a String into an instance of StateMachineDemo, which is the implementation of AbstractStateMachine. I can do this, because the above Annotation means that JPA doesn't care how I implement the attribute, is will always use bean conform accessors to set/get the state of my entity, namely the String getState() and void setState(String) methods.
  • Change the generated void setState(String) method visibility to become private, so that no one could explicitly set the state of my entity. The method needs to exist, so that JPA can access the attribute to persist it, but JPA can happily live with the method being private.
  • Add methods for each transition, which simply delegate the call to the state machine. Users of the persistent entity use these trigger methods to change the state, rather than calling void setState(String) on the entity.

These changes are all shown/documented in the StateMachineDemo class.

To demonstrate the state machine working, as well as it being used in a persistent environment, have a look at the JUnit test case StateMachineDemoTest. This class contains tests for setting any state during construction, tests for state transitions proving that only valid ones are allowed, as well as reading/writing an entity containing state to the database and updating the state along the way.

Download the source here.

© 2010, Ant Kutschera
Social Bookmarks :  Add this post to Slashdot    Add this post to Digg    Add this post to Reddit    Add this post to Delicious    Add this post to Stumble it    Add this post to Google    Add this post to Technorati    Add this post to Bloglines    Add this post to Facebook    Add this post to Furl    Add this post to Windows Live    Add this post to Yahoo!

Re: Persistent State Machine with Apache SCXML

Hallo Ant! I am also looking for a solution to the persistence of SCXML state. I checked your method, and it looks very nice. Thank you for your work!

Re: Persistent State Machine with Apache SCXML

Hi, While your version works with the current release, I think it is unfortunate that you have to manipulate the state collection after having started a process in order to set the new State. This breaks as soon as "exec.getCurrentStatus().getStates()" makes the returned Set immutable... Alas, I have not found a better solution myself yet.

Re: Persistent State Machine with Apache SCXML

Hi Flo, perhaps you could fire off the question to the Apache SCM team - they were helpful when I asked them. Maybe they could create a way of setting the initial state from persistence?

Re: Persistent State Machine with Apache SCXML

Yeah, I might do that. Thanks for your effort btw :).

Re: Persistent State Machine with Apache SCXML

Which JPA version did you use? I find this solution very interesting. It opens the door to use SCXML for managing life cycles in business entities. There, persistence is really necessary! Thanks!

Re: Persistent State Machine with Apache SCXML

Hi Ant, Are you still actively working with SCXML? I am just getting started and my hope is to create a generic SCXML workbench UI to display state and expose events to allow the user to trigger events for transitions. Would you be interested in collaborating on this?

Re: Persistent State Machine with Apache SCXML

Hi Mike, I'm too tied up with other stuff these days, so thanks for the offer, but I'm afraid I'm not interested. Cheers, Ant

Add a comment Send a TrackBack