simple-fsm
is, as the name suggests, a simple finite state machine library that helps with state management.
How to?
Consider the classic turnstile FSM:
The following code represents this turnstile:
class Turnstile {
private TurnstileState currentState;
public Turnstile() {
this.currentState = TurnstileState.LOCKED;
}
public void coin() {
if (currentState == TurnstileState.LOCKED) {
currentState = TurnstileState.UNLOCKED;
}
}
public void push() {
if (currentState == TurnstileState.UNLOCKED) {
currentState = TurnstileState.LOCKED;
}
}
}
enum TurnstileEvent {
PUSH, COIN
}
enum TurnstileState {
LOCKED, UNLOCKED
}One of the following two methods can be used for state management:
Composition
The turnstile class is composed of a the SimpleStateMachine and takes care of its entire lifecycle.
All the state related changes and validations are managed by the state machine alone.
class Turnstile {
private SimpleStateMachine<TurnstileEvent, TurnstileState, Turnstile> stateMachine;
public Turnstile() {
stateMachine = SimpleStateMachine.<TurnstileEvent, TurnstileState, Turnstile>builder()
.initialState(TurnstileState.LOCKED)
.addTransition(new Transition<>(TurnstileEvent.PUSH, TurnstileState.LOCKED, TurnstileState.LOCKED))
.addTransition(new Transition<>(TurnstileEvent.COIN, TurnstileState.LOCKED, TurnstileState.UNLOCKED))
.addTransition(new Transition<>(TurnstileEvent.PUSH, TurnstileState.UNLOCKED, TurnstileState.LOCK))
.addTransition(new Transition<>(TurnstileEvent.COIN, TurnstileState.UNLOCKED, TurnstileState.UNLOCKED))
.build();
}
public void coin() {
stateMachine.consume(TurnstileEvent.COIN, this);
}
public void push() {
stateMachine.consume(TurnstileEvent.PUSH, this);
}
}Inheritance
Turnstile inherits the SimpleStateMachine and routes the state change calls to state machines APIs.
class Turnstile extends SimpleStateMachine<TurnstileEvent, TurnstileState, Turnstile> {
public Turnstile() {
super(TurnstileState.LOCKED, buildTurnstileTransitions());
}
private static List<Transition<TurnstileEvent, TurnstileState, Turnstile>> buildTurnstileTransitions() {
List<Transition<TurnstileEvent, TurnstileState, Turnstile>> transitions;
transitions.add(new Transition<>(TurnstileEvent.PUSH, TurnstileState.LOCKED, TurnstileState.LOCKED));
transitions.add(new Transition<>(TurnstileEvent.COIN, TurnstileState.LOCKED, TurnstileState.UNLOCKED));
transitions.add(new Transition<>(TurnstileEvent.PUSH, TurnstileState.UNLOCKED, TurnstileState.LOCK));
transitions.add(new Transition<>(TurnstileEvent.COIN, TurnstileState.UNLOCKED, TurnstileState.UNLOCKED));
return transitions;
}
public void coin() {
consume(TurnstileEvent.COIN, this);
}
public void push() {
consume(TurnstileEvent.PUSH, this);
}
}Actions
SimpleStateMachine supports "actions" to be invoked before and after the state transition takes place. Add custom
actions to be invoked by adding a list of implementations of the Action interface.
Consider the following implementation of Action which helps us calculate the amount collected by the turnstile.
class AmountCounter implements Action<TurnstileEvent, TurnstileState, Turnstile> {
@Override
public void before(ActionContext<TurnstileEvent, TurnstileState, Turnstile> actionContext) {}
@Override
public void after(ActionContext<TurnstileEvent, TurnstileState, Turnstile> actionContext) {
Turnstile turnstile = actionContext.getData();
turnstile.incrementAmount();
}
}The buildTurnstileTransitions method in the inheritance example will look something like the following:
private static List<Transition<TurnstileEvent, TurnstileState, Turnstile>> buildTurnstileTransitions() {
List<Action<TurnstileEvent, TurnstileState, Turnstile>> actions = Collections.singletonList(new AmountCounter());
List<Transition<TurnstileEvent, TurnstileState, Turnstile>> transitions;
transitions.add(new Transition<>(TurnstileEvent.PUSH, TurnstileState.LOCKED, TurnstileState.LOCKED));
transitions.add(new Transition<>(TurnstileEvent.COIN, TurnstileState.LOCKED, TurnstileState.UNLOCKED, actions));
transitions.add(new Transition<>(TurnstileEvent.PUSH, TurnstileState.UNLOCKED, TurnstileState.LOCK));
transitions.add(new Transition<>(TurnstileEvent.COIN, TurnstileState.UNLOCKED, TurnstileState.UNLOCKED, actions));
return transitions;
}
