FSM-Engine

Easily define Finite State Machines in your Java applications, using Spring.

#Introduction

FSM Engine makes it easy to define and execute simple finite state machines, and thus workflows, in your Java applications. It really helps in cases where the behaviour of an object needs to be changed automatically, at runtime, depending on its state.

This library was originally inspired by Harel Statecharts and the State Design Pattern and is implemented by the National Documentation Centre of Greece. Also, it is successfully incorporated in a few production applications, including the National Archive of PhD Theses and the National Interloaning System of Scientific and Technological Libraries.

#Features

• Basic FSM elements: States, Events, Transitions.
• Advanced FSM blocks: Actions, Guard conditions, Branches.
• Define your Finite State Machine in a plain Spring context XML.
• Use standard Spring annotations for working with the workflow engine.

#Quick Start

The recommended way to get started using FSM Engine in your project is with a dependency management system. Specifically, FSM Engine uses Apache Maven for project management.

Clone this git repository, and add the artifact to your local maven repository:

git clone https://github.com/EKT/FSM-Engine.git
cd FSM-Engine
mvn clean install

Finally, include the dependency in pom.xml of your project:

<dependency>
  <groupId>gr.ekt</groupId>
  <artifactId>fsm-engine</artifactId>
  <version>0.9.0</version>
</dependency>

Examine the tests, under src/test/java, for a lot of practical examples.

As always, our Wiki provides complimentary information on using the library.

#3 minute demo

Suppose a simple Switch that can be either OFF or ON.

At first, our domain object should implement the interface gr.ekt.fsmengine.api.StateContext.

public class Switch implements StateContext {
	// actual implementation
}

Then, we should declare the basic elements in our Spring context.

    <!-- Event -->
    <bean id="eventPress" class="gr.ekt.fsmengine.api.DefaultEvent">
        <property name="name" value="EVENT_PRESS"/>
    </bean>

    <!-- States -->
    <bean id="stateOff" class="gr.ekt.fsmengine.api.DefaultState">
        <property name="stateName" value="STATE_OFF"/>
        <property name="eventTransitionsMap">
            <map>
                <entry key-ref="eventPress" value-ref="transition"/>
            </map>
        </property>
    </bean>
    
    <bean id="stateOn" class="gr.ekt.fsmengine.api.DefaultState">
        <property name="stateName" value="STATE_ON"/>
    </bean>

    <!-- Transition -->
    <bean id="transition" class="gr.ekt.fsmengine.api.DefaultTransition">
        <property name="fromState" ref="stateOff" />
        <property name="toState" ref="stateOn" />
    </bean>

So, we have one event, two states and one transition. In fact, the "press" event moves the switch from OFF to ON.

Back to our Java code, we just need a reference to the engine and the event.

@Autowired
private SpringFsm engine;

@Autowired
private Event press;

Let's fire the event!

void foo(Switch input) {
	format("Status: %s\n", input.getStateName()); // OFF
	engine.processEvent(press, input);
	format("Status: %s\n", input.getStateName()); // ON
}