The simple, stupid state machine for Java
Switch branches/tags
Clone or download

README.md


Easy States
The simple, stupid state machine for Java™

MIT license Coverage Build Status Maven Central Javadoc Gitter


Latest news

  • 03/07/2017: Version 1.0.1 is released with a small change in the artifactId. See details in the release notes.
  • 08/06/2017: Version 1.0.0 is out. See release notes here.

What is Easy States?

Easy States is an event-driven Deterministic Finite Automaton implementation in Java.

It is inspired by Erlang design principles which describe a Finite State Machine as a set of relations of the form:

State(S) x Event(E) -> Actions(A), State(S')

These relations are interpreted like follows:

If we are in state S and the event E occurs, we should perform action(s) A and make a transition to the state S'.

How does it work?

Easy States provides APIs for key concepts of state machines:

  • State: a particular state the machine can be on at given point in time
  • Event: represents an event that may trigger an action and change the state of the machine
  • Transition: represents a transition between two states of the machine when an event occurs
  • FiniteStateMachine: core abstraction of a finite state machine

Using Easy States, you can define FSM transitions with an intuitive fluent API:

Transition t = new TransitionBuilder()
        .sourceState(s0) //if we are in state s0
        .eventType(Event.class) // and the event E occurs
        .eventHandler(myActionA) // we should perform the actions A
        .targetState(s1) // and make a transition to the state s1
        .build();

How to use it?

Easy States has no dependencies. You can download and add the easy-states-1.0.1.jar file to your application's classpath and you're done. If you use maven, add the following dependency to your pom.xml:

<dependency>
    <groupId>org.jeasy</groupId>
    <artifactId>easy-states</artifactId>
    <version>1.0.1</version>
</dependency>

Two minutes tutorial

This tutorial is an implementation of the turnstile example described in wikipedia:

A turnstile has two states: Locked and Unlocked. There are two inputs that affect its state: putting a coin in the slot (coin) and pushing the arm (push). In the locked state, pushing on the arm has no effect; no matter how many times the input push is given it stays in the locked state. Putting a coin in, that is giving the machine a coin input, shifts the state from Locked to Unlocked. In the unlocked state, putting additional coins in has no effect; that is, giving additional coin inputs does not change the state.

turnsitle

For this example, we define:

  • two states: Locked and Unlocked
  • two events: PushEvent and CoinEvent
  • two actions: Lock and Unlock
  • and four transitions: pushLocked, unlock, coinUnlocked and lock

1. First, let's define states

State locked = new State("locked");
State unlocked = new State("unlocked");

Set<State> states = new HashSet<State>();
states.add(locked);
states.add(unlocked);

2. Then, define events

class PushEvent extends Event { }
class CoinEvent extends Event { }

3. Then transitions

Transition unlock = new TransitionBuilder()
        .name("unlock")
        .sourceState(locked)
        .eventType(CoinEvent.class)
        .eventHandler(new Unlock())
        .targetState(unlocked)
        .build();

Transition pushLocked = new TransitionBuilder()
        .name("pushLocked")
        .sourceState(locked)
        .eventType(PushEvent.class)
        .targetState(locked)
        .build();

Transition lock = new TransitionBuilder()
        .name("lock")
        .sourceState(unlocked)
        .eventType(PushEvent.class)
        .eventHandler(new Lock())
        .targetState(locked)
        .build();

Transition coinUnlocked = new TransitionBuilder()
        .name("coinUnlocked")
        .sourceState(unlocked)
        .eventType(CoinEvent.class)
        .targetState(unlocked)
        .build();

4. And finally the finite state machine

FiniteStateMachine turnstileStateMachine = new FiniteStateMachineBuilder(states, locked)
        .registerTransition(lock)
        .registerTransition(pushLocked)
        .registerTransition(unlock)
        .registerTransition(coinUnlocked)
        .build();

The complete code of this tutorial can be found here.

To run the tutorial, please follow these instructions:

$>git clone https://github.com/j-easy/easy-states.git
$>cd easy-states
$>mvn install
$>mvn exec:java -P runTurnstileTutorial

You will be able to fire events interactively from the console and check the evolution of the machine's state.

License

Easy States is released under the terms of the MIT License:

The MIT License

   Copyright (c) 2017, Mahmoud Ben Hassine (mahmoud.benhassine@icloud.com)

   Permission is hereby granted, free of charge, to any person obtaining a copy
   of this software and associated documentation files (the "Software"), to deal
   in the Software without restriction, including without limitation the rights
   to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
   copies of the Software, and to permit persons to whom the Software is
   furnished to do so, subject to the following conditions:

   The above copyright notice and this permission notice shall be included in
   all copies or substantial portions of the Software.

   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
   FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
   AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
   LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
   OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
   THE SOFTWARE.