1.0.0.M1
Copyright © 2015 Pivotal Software, Inc.
Table of Contents
Concept of a state machine is most likely older that any of a reader of this reference documentation and definitely older than a Java language itself. Description of finite automate dates back to 1943 when gentlements Warren McCulloch and Walter Pitts wrote a paper about it. Later George H. Mealy presented a state machine concept in 1955 which is known as a Mealy Machine. A year later in 1956 Edward F. Moore presented another paper which is known as a Moore Machine. If you’re ever read anything about state machines, names Mealy and Moore should have popped up at some point.
This reference documentations contains following parts.
Part I, “Introduction” introduction to this reference documentation
Part II, “Spring and Statemachine” describes the usage of Spring State Machine(SSM)
Part III, “State Machine Examples” more detailed state machine samples
Part IV, “FAQ” frequently ask questions
Part V, “Appendices” generic info about used material and state machines
Spring Statemachine(SSM) is a framework for application developers to use traditional state machine concepts with Spring applications. SSM aims to provide following features:
- Easy to use flat one level state machine for simple use cases.
- Hierarchical state machine structure to ease complex state configuration.
- State machine regions to provide even more complex state configurations.
- Usage of triggers, transitions, guards and actions.
- Type safe configuration adapter.
- State machine event listeners.
- Spring IOC integration to associate beans with a state machine.
Before you continue it’s worth to go through appendices Section B.2, “Glossary” and Section B.3, “A State Machines Crash Course” to get a generic idea of what state machines are mostly because rest of a documentation expects reader to be fairly familiar with state machine concepts.
Spring Statemachine 1.0.0.M1 is built and tested with JDK 7 and Spring Framework 4.1.6.RELEASE and doesn’t require any other dependencies outside of Spring Framework. Samples require spring-shell and spring-boot which pulls other dependencies beyond framework itself.
State machines are powerful because behaviour is always guaranteed to be consistent and relatively easily debugged due to ways how operational rules are written in stone when machine is started. Idea is that your application is and may exist in a finite number of states and then something happens which takes your application from one state to the next. What will drive a state machine are triggers which are either based on events or timers.
It is much easier to design high level logic outside of your application and then interact with a state machine with a various different ways. You can simply interact with a state machine by sending event, listening what a state machine does or simply request a current state.
Traditionally state machines are added to a existing project when developer realizes that code base is starting to look like a plate full of spaghetti. Spaghetti code looks like never ending hierarchical structure of IFs, ELSEs and BREAK clauses and probably compiler should ask developer to go home when things are starting to look too complex.
Project is a good candiate to use state machine if:
- Application or part of its structure can be represented as states.
- You want to split complex logic into smaller manageable tasks.
- Application is already suffering concurrency issues with i.e. something happening asynchronously.
You are already trying to implement a state machine if:
- Use of boolean flags or enums to model situations.
- Having variables which only have meaning for some part of your application lifecycle.
- Looping throught if/else structure and checking if particular flag or enum is set and then making further exceptions what to do when certain combination of your flags and enums exists or doesn’t exist together.
This part of the reference documentation explains the core functionality that Spring Statemachine provides to any Spring based application.
Chapter 5, Statemachine Configuration describes the generic configuration support.
Chapter 6, State Machine Factories describes the generic state machine factory support.
Chapter 7, Triggering Transitions describes the use of triggers.
Chapter 8, Listening State Machine Events describes the use of state machine listeners.
Chapter 9, Context Integration describes the generic Spring application context support.
One of the common tasks when using a Statemachine is to design its runtime configuration. This chapter will focus on how Spring Statemachine is configured and how it leverages Spring’s lightweight IoC containers to simplify the application internals to make it more manageable.
We’ll get into more complex configuration examples a bit later but
lets first start with a something simple. For most simple state
machine you just use EnumStateMachineConfigurerAdapter and define
possible states, choose initial and optional end state.
@Configuration @EnableStateMachine public static class Config1 extends EnumStateMachineConfigurerAdapter<States, Events> { @Override public void configure(StateMachineStateConfigurer<States, Events> states) throws Exception { states .withStates() .initial(States.S1) .end(States.SF) .states(EnumSet.allOf(States.class)); } }
Hierarchical states can be defined by using multiple withStates()
calls where parent() can be used to indicate that these
particular states are sub-states of some other state.
@Configuration @EnableStateMachine public static class Config2 extends EnumStateMachineConfigurerAdapter<States, Events> { @Override public void configure(StateMachineStateConfigurer<States, Events> states) throws Exception { states .withStates() .initial(States.S1) .state(States.S1) .and() .withStates() .parent(States.S1) .initial(States.S2) .state(States.S2); } }
We support three different types of transitions, external,
internal and local. Transitions are either triggered by a signal
which is an event sent into a state machine or a timer.
@Configuration @EnableStateMachine public static class Config3 extends EnumStateMachineConfigurerAdapter<States, Events> { @Override public void configure(StateMachineStateConfigurer<States, Events> states) throws Exception { states .withStates() .initial(States.S1) .states(EnumSet.allOf(States.class)); } @Override public void configure(StateMachineTransitionConfigurer<States, Events> transitions) throws Exception { transitions .withExternal() .source(States.S1).target(States.S2) .event(Events.E1) .and() .withInternal() .source(States.S2) .event(Events.E2) .and() .withLocal() .source(States.S2).target(States.S3) .event(Events.E3); } }
Guards are used to protect state transitions. Interface Guard is used to do an evaluation where method has access to a StateContext.
@Configuration @EnableStateMachine public static class Config4 extends EnumStateMachineConfigurerAdapter<States, Events> { @Override public void configure(StateMachineTransitionConfigurer<States, Events> transitions) throws Exception { transitions .withExternal() .source(States.S1).target(States.S2) .event(Events.E1) .guard(guard()) .and() .withExternal() .source(States.S2).target(States.S3) .event(Events.E2) .guardExpression("true"); } @Bean public Guard<States, Events> guard() { return new Guard<States, Events>() { @Override public boolean evaluate(StateContext<States, Events> context) { return true; } }; } }
In above two different types of guard configurations are used. Firstly a
simple Guard is created as a bean and attached to transition between
states S1 and S2.
Secondly a simple spel expression can be used as a guard where
expression must return a Boolean value. Behind a scenes this spel
based guard is a SpelExpressionGuard. This was attached to
transition between states S2 and S3. Both guard in above sample
always evaluate to true.
Actions can be defined with various steps within a state transitions.
@Configuration @EnableStateMachine public static class Config5 extends EnumStateMachineConfigurerAdapter<States, Events> { @Override public void configure(StateMachineTransitionConfigurer<States, Events> transitions) throws Exception { transitions .withExternal() .source(States.S1) .target(States.S2) .event(Events.E1) .action(action()); } @Bean public Action<States, Events> action() { return new Action<States, Events>() { @Override public void execute(StateContext<States, Events> context) { // do something } }; } }
There are use cases when state machine needs to be created dynamically instead of defining static configuration at compile time. For example if there are custom components which are using its own state machines and these components are created dynamically it is impossible to have a static state machined build during the application start. Internally state machines are always build via a factory interfaces and this then gives user an option to use this feature programmatically. Configuration for state machine factory is exactly same as you’ve seen in various examples in this document where state machine configuration is hard coded.
Actually creating a state machine using @EnableStateMachine will work via factory so @EnableStateMachineFactory is merely exposing that factory via its interface.
@Configuration @EnableStateMachineFactory public static class Config6 extends EnumStateMachineConfigurerAdapter<States, Events> { @Override public void configure(StateMachineStateConfigurer<States, Events> states) throws Exception { states .withStates() .initial(States.S1) .end(States.SF) .states(EnumSet.allOf(States.class)); } }
Now that you’ve used @EnableStateMachineFactory to create a factory instead of a state machine bean, it can be injected and used as is to request new state machines.
static class Bean3 { @Autowired StateMachineFactory<States, Events> factory; void method() { StateMachine<States,Events> stateMachine = factory.getStateMachine(); stateMachine.start(); } }
Current limitation of factory is that all actions and guard it is associating with created state machine will share a same instances. This means that from your actions and guard you will need to specifially handle a case that same bean will be called by a different state machines. This limitation is something which will be resolved in future releases.
Driving a statemachine is done via transitions which are triggerred by triggers. Currently supported triggers are EventTrigger and TimerTrigger.
EventTrigger is the most useful trigger because it allows user to directly interact with a state machine by sending events to it. These events are also called signals. Trigger is added to a transition simply by associating a state to it during a configuration.
@Autowired StateMachine<States, Events> stateMachine; void signalMachine() { stateMachine.sendEvent(Events.E1); Message<Events> message = MessageBuilder .withPayload(Events.E2) .setHeader("foo", "bar") .build(); stateMachine.sendEvent(message); }
In above example we send an event using two different ways. Firstly we
simply sent a type safe event using state machine api method
sendEvent(E event). Secondly we send event wrapped in a Spring
messaging Message using api method sendEvent(Message<E> message)
with a custom event headers. This allows user to add arbitrary extra
information with an event which is then visible to StateContext when
for example user is implementing actions.
There are use cases where you just want to know what is happening with a state machine, react to something or simply get logging for debugging purposes. SSM provides interfaces for adding listeners which then gives an option to get callback when various state changes, actions, etc are happening.
You basically have two options, either to listen Spring application context events or directly attach listener to a state machine. Both of these basically will provide same information where one is producing events as event classes and other producing callbacks via a listener interface. Both of these have pros and cons which will be discussed later.
Application context events classes are OnTransitionStartEvent, OnTransitionEvent, OnTransitionEndEvent, OnStateExitEvent, OnStateEntryEvent, OnStateChangedEvent, OnStateMachineStart and OnStateMachineStop. These can be used as is with spring typed ApplicationListener class but they also share a common class StateMachineEvent which can be used to get statemachine related events.
static class StateMachineApplicationEventListener implements ApplicationListener<StateMachineEvent> { @Override public void onApplicationEvent(StateMachineEvent event) { } }
Using StateMachineListener you can either extend it and implement all callback methods or use StateMachineListenerAdapter class which contains stub method implementations and choose which ones to override.
static class StateMachineEventListener extends StateMachineListenerAdapter<States, Events> { @Override public void stateChanged(State<States, Events> from, State<States, Events> to) { } @Override public void stateEntered(State<States, Events> state) { } @Override public void stateExited(State<States, Events> state) { } @Override public void transition(Transition<States, Events> transition) { } @Override public void transitionStarted(Transition<States, Events> transition) { } @Override public void transitionEnded(Transition<States, Events> transition) { } @Override public void stateMachineStarted(StateMachine<States, Events> stateMachine) { } @Override public void stateMachineStopped(StateMachine<States, Events> stateMachine) { } }
In above example we simply created our own listener class StateMachineEventListener which extends StateMachineListenerAdapter.
Once you have your own listener defined, it can be registered into a state machine via its interface as shown below. It’s just a matter of flavour if it’s hooked up within a spring configuration or done manually at any time of application life-cycle.
static class Config7 { @Autowired StateMachine<States, Events> stateMachine; @Bean public StateMachineEventListener stateMachineEventListener() { StateMachineEventListener listener = new StateMachineEventListener(); stateMachine.addStateListener(listener); return listener; } }
Spring application context is not a fastest event bus out there so it
is advised to give some thought what is a rate of events state machine
is sending. For better performance it may be better to use
StateMachineListener interface. For this specific reason it is
possible to use contextEvents flag with @EnableStateMachine and
@EnableStateMachineFactory to disable Spring application context
events as shown above.
@Configuration @EnableStateMachine(contextEvents = false) public static class Config8 extends EnumStateMachineConfigurerAdapter<States, Events> { } @Configuration @EnableStateMachineFactory(contextEvents = false) public static class Config9 extends EnumStateMachineConfigurerAdapter<States, Events> { }
It is a little limited to do interaction with a state machine by either listening its events or using actions with states and transitions. Time to time this approach would be too limited and verbose to create interaction with the application a state machine is working with. For this specific use case we have made a spring style context intergration which easily attach state machine functionality into your beans.
@WithStateMachine annotation can be used to associate a state machine with a existing bean. Withing this annotation a propertys source and target can be used to qualify a transition
@WithStateMachine static class Bean1 { @OnTransition(source = "S1", target = "S2") public void fromS1ToS2() { } }
Default @OnTransition annotation can’t be used with a state and event enums user have created due to java language limitations, thus string representation have to be used.
However if you want to have a type safe annotation it is possible to create a new annotation and use @OnTransition as meta annotation. This user level annotation can make a reference to actual states and events enums and framework will try to match these in a same way.
@Target(ElementType.METHOD) @Retention(RetentionPolicy.RUNTIME) @OnTransition static @interface StatesOnTransition { States[] source() default {}; States[] target() default {}; }
Above we created a @StatesOnTransition annotation which defines
source and target as a type safe manner.
@WithStateMachine static class Bean2 { @StatesOnTransition(source = States.S1, target = States.S2) public void fromS1ToS2() { } }
In your own bean you can then use this @StatesOnTransition as is and
use type safe source and target.
This part of the reference documentation explains the use of state machines together with a sample code and a uml state charts. We do few shortcuts when representing relationship between a state chart, SSM configuration and what an application does with a state machine. For complete examples go and study the samples repository.
Samples are build directly from a main source distribution during a normal build cycle.
./gradlew clean build -x test
Every sample is located in its own directory under
spring-statemachine-samples. Samples are based on spring-boot and
spring-shell and you will find usual boot fat jars under every sample
projects build/libs directory.
Turnstile is a simple device which gives you an access if payment is
made and is a very simple to model using a state machine. In its
simples form there are only two states, LOCKED and UNLOCKED. Two
events, COIN and PUSH can happen if you try to go through it or
you make a payment.
States.
public static enum States { LOCKED, UNLOCKED }
Events.
public static enum Events { COIN, PUSH }
Configuration.
@Configuration @EnableStateMachine static class StateMachineConfig extends EnumStateMachineConfigurerAdapter<States, Events> { @Override public void configure(StateMachineStateConfigurer<States, Events> states) throws Exception { states .withStates() .initial(States.LOCKED) .states(EnumSet.allOf(States.class)); } @Override public void configure(StateMachineTransitionConfigurer<States, Events> transitions) throws Exception { transitions .withExternal() .source(States.LOCKED) .target(States.UNLOCKED) .event(Events.COIN) .and() .withExternal() .source(States.UNLOCKED) .target(States.LOCKED) .event(Events.PUSH); } }
You can see how this sample state machine interacts with event by
running turnstile sample.
$ java -jar spring-statemachine-samples-turnstile-1.0.0.BUILD-SNAPSHOT.jar sm>sm print +----------------------------------------------------------------+ | SM | +----------------------------------------------------------------+ | | | +----------------+ +----------------+ | | *-->| LOCKED | | UNLOCKED | | | +----------------+ +----------------+ | | +---| entry/ | | entry/ |---+ | | | | exit/ | | exit/ | | | | | | | | | | | | PUSH| | |---COIN-->| | |COIN | | | | | | | | | | | | | | | | | | | | |<--PUSH---| | | | | +-->| | | |<--+ | | | | | | | | +----------------+ +----------------+ | | | +----------------------------------------------------------------+ sm>sm start State changed to LOCKED State machine started sm>sm event COIN State changed to UNLOCKED Event COIN send sm>sm event PUSH State changed to LOCKED Event PUSH send
Showcase is a complex state machine showing all possible transition topologies up to four levels of state nesting.
States.
public static enum States { S0, S1, S11, S12, S2, S21, S211, S212 }
Events.
public static enum Events { A, B, C, D, E, F, G, H, I }
Configuration - states.
@Override public void configure(StateMachineStateConfigurer<States, Events> states) throws Exception { states .withStates() .initial(States.S0, fooAction()) .state(States.S0) .and() .withStates() .parent(States.S0) .initial(States.S1) .state(States.S1) .and() .withStates() .parent(States.S1) .initial(States.S11) .state(States.S11) .state(States.S12) .and() .withStates() .parent(States.S0) .state(States.S2) .and() .withStates() .parent(States.S2) .initial(States.S21) .state(States.S21) .and() .withStates() .parent(States.S21) .initial(States.S211) .state(States.S211) .state(States.S212); }
Configuration - transitions.
@Override public void configure(StateMachineTransitionConfigurer<States, Events> transitions) throws Exception { transitions .withExternal() .source(States.S1).target(States.S1).event(Events.A) .guard(foo1Guard()) .and() .withExternal() .source(States.S1).target(States.S11).event(Events.B) .and() .withExternal() .source(States.S21).target(States.S211).event(Events.B) .and() .withExternal() .source(States.S1).target(States.S2).event(Events.C) .and() .withExternal() .source(States.S2).target(States.S1).event(Events.C) .and() .withExternal() .source(States.S1).target(States.S0).event(Events.D) .and() .withExternal() .source(States.S211).target(States.S21).event(Events.D) .and() .withExternal() .source(States.S0).target(States.S211).event(Events.E) .and() .withExternal() .source(States.S1).target(States.S211).event(Events.F) .and() .withExternal() .source(States.S2).target(States.S11).event(Events.F) .and() .withExternal() .source(States.S11).target(States.S211).event(Events.G) .and() .withExternal() .source(States.S211).target(States.S0).event(Events.G) .and() .withInternal() .source(States.S0).event(Events.H) .guard(foo0Guard()) .action(fooAction()) .and() .withInternal() .source(States.S2).event(Events.H) .guard(foo1Guard()) .action(fooAction()) .and() .withInternal() .source(States.S1).event(Events.H) .and() .withExternal() .source(States.S11).target(States.S12).event(Events.I) .and() .withExternal() .source(States.S211).target(States.S212).event(Events.I) .and() .withExternal() .source(States.S12).target(States.S212).event(Events.I); }
Configuration - actions and guard.
@Bean public FooGuard foo0Guard() { return new FooGuard(0); } @Bean public FooGuard foo1Guard() { return new FooGuard(1); } @Bean public FooAction fooAction() { return new FooAction(); }
Action.
private static class FooAction implements Action<States, Events> { @Override public void execute(StateContext<States, Events> context) { Map<Object, Object> variables = context.getExtendedState().getVariables(); Integer foo = context.getExtendedState().get("foo", Integer.class); if (foo == null) { log.info("Init foo to 0"); variables.put("foo", 0); } else if (foo == 0) { log.info("Switch foo to 1"); variables.put("foo", 1); } else if (foo == 1) { log.info("Switch foo to 0"); variables.put("foo", 0); } } }
Guard.
private static class FooGuard implements Guard<States, Events> { private final int match; public FooGuard(int match) { this.match = match; } @Override public boolean evaluate(StateContext<States, Events> context) { Object foo = context.getExtendedState().getVariables().get("foo"); return !(foo == null || !foo.equals(match)); } }
Lets go throught what this state machine do when it’s executed and we send various event to it.
sm>sm start Entry state S0 Entry state S1 Entry state S11 Init foo to 0 State machine started sm>sm event A Event A send sm>sm event C Exit state S11 Exit state S1 Entry state S2 Entry state S21 Entry state S211 Event C send sm>sm event H Switch foo to 1 Event H send sm>sm event C Exit state S211 Exit state S21 Exit state S2 Entry state S1 Entry state S11 Event C send sm>sm event A Exit state S11 Exit state S1 Entry state S1 Entry state S11 Event A send
What happens in above sample:
-
State machine is started which takes it to its initial state S11
via superstates S1 and S0. Also extended state variable
foois init to0. -
We try to execute self transition in state S1 with event A but
nothing happens because transition is guarded by variable
footo be1. -
We send event C which takes us to other state machine where
initial state S211 and its superstates are entered. In there we
can use event H which does a simple internal transition to flip
variable
foo. Then we simply go back using event C. - Event A is sent again and now S1 does a self transition because guard evaluates true.
-
It’s also worth to pay attention to how event H is handled in
different states S0, S1 and S2. This is a good example of how
hierarchical states and their event handling works. If state S2 is
unable to handle event H due to guard condition, its parent is
checked next. This guarantees that while on state S2,
fooflag is always flipped around. However in state S1 event H always match to its dummy transtion without guard or action, not never happens.
CD Player is a sample which resembles better use case of most of use have used in a real world. CD Player itself is a really simple entity where user can open a deck, inser or change a disk, then drive player functionality by pressing various buttons like eject, play, stop, pause, rewind and backward.
How many of use have really given a thought of what it will take to make a code for a CD Player which interacts with a hardware. Yes, concept of a player is overly simple but if you look behind a scenes things actually get a bit convoluted.
You’ve probably noticed that if your deck is open and you press play, deck will close and a song will start to play if CD was inserted in a first place. In a sense when deck is open you first need to close it and then try to start playing if cd is actually instered. Hopefully you have now realised that a simple CD Player is not anymore so simple. Sure you can wrap all this with a simple class with few boolean variables and probably few nested if/else clauses, that will do the job, but what about if you need to make all this behaviour much more complex, do you really want to keep adding more flags and if/else clauses.
Lets go throught how this sample and its state machine is designed and how those two interacts with each other. Below three config sections are used withing a EnumStateMachineConfigurerAdapter.
@Override public void configure(StateMachineStateConfigurer<States, Events> states) throws Exception { states .withStates() .initial(States.IDLE) .state(States.IDLE) .and() .withStates() .parent(States.IDLE) .initial(States.CLOSED) .state(States.CLOSED, closedEntryAction(), null) .state(States.OPEN) .and() .withStates() .state(States.BUSY) .and() .withStates() .parent(States.BUSY) .initial(States.PLAYING) .state(States.PLAYING) .state(States.PAUSED); }
@Override public void configure(StateMachineTransitionConfigurer<States, Events> transitions) throws Exception { transitions .withExternal() .source(States.CLOSED).target(States.OPEN).event(Events.EJECT) .and() .withExternal() .source(States.OPEN).target(States.CLOSED).event(Events.EJECT) .and() .withExternal() .source(States.OPEN).target(States.CLOSED).event(Events.PLAY) .and() .withExternal() .source(States.PLAYING).target(States.PAUSED).event(Events.PAUSE) .and() .withInternal() .source(States.PLAYING) .action(playingAction()) .timer(1000) .and() .withInternal() .source(States.PLAYING).event(Events.BACK) .action(trackAction()) .and() .withInternal() .source(States.PLAYING).event(Events.FORWARD) .action(trackAction()) .and() .withExternal() .source(States.PAUSED).target(States.PLAYING).event(Events.PAUSE) .and() .withExternal() .source(States.BUSY).target(States.IDLE).event(Events.STOP) .and() .withExternal() .source(States.IDLE).target(States.BUSY).event(Events.PLAY) .action(playAction()) .guard(playGuard()) .and() .withInternal() .source(States.OPEN).event(Events.LOAD).action(loadAction()); }
@Bean public ClosedEntryAction closedEntryAction() { return new ClosedEntryAction(); } @Bean public LoadAction loadAction() { return new LoadAction(); } @Bean public TrackAction trackAction() { return new TrackAction(); } @Bean public PlayAction playAction() { return new PlayAction(); } @Bean public PlayingAction playingAction() { return new PlayingAction(); } @Bean public PlayGuard playGuard() { return new PlayGuard(); }
What we did in above configuration:
- We used EnumStateMachineConfigurerAdapter to configure states and transitions.
- States CLOSED and OPEN are defined as substates of IDLE, states PLAYING and PAUSED are defined as substates of BUSY.
- With state CLOSED we added entry action as bean closedEntryAction.
-
With transition we mostly mapped events to expected state transitions like EJECT closing and opening a deck, PLAY, STOP and PAUSE doing their natural transitions. Few words to mention what we did for other transitions.
- With source state PLAYING we added a timer trigger which is needed to automatically track elapsed time within a playing track and to have facility to make a decision when to switch to next track.
- With event PLAY if source state is IDLE and target state is BUSY we defined action playAction and guard playGuard.
- With event LOAD and state OPEN we defined internal transition with action loadAction which will insert cd disc into extended state variables.
- PLAYING state defined three internal transitions where one is triggered by a timer executing a playingAction which updates extended state variables. Other two transitions are with trackAction with different events, BACK and FORWARD respectively which handles when user wants to go back or forward in tracks.
This machine only have six states which are introduced as an enum.
public static enum States { // super state of PLAYING and PAUSED BUSY, PLAYING, PAUSED, // super state of CLOSED and OPEN IDLE, CLOSED, OPEN }
Events represent, in a sense in this example, what buttons user would press and if user loads a cd disc into a deck.
public static enum Events { PLAY, STOP, PAUSE, EJECT, LOAD, FORWARD, BACK }
Beans cdPlayer and library are just used with a sample to drive the application.
@Bean public CdPlayer cdPlayer() { return new CdPlayer(); } @Bean public Library library() { return Library.buildSampleLibrary(); }
We can define extended state variable key as simple enums.
public static enum Variables { CD, TRACK, ELAPSEDTIME } public static enum Headers { TRACKSHIFT }
We wanted to make this samply type safe so we’re defining our own annotation @StatesOnTransition which have a mandatory meta annotation @OnTransition.
@Target(ElementType.METHOD) @Retention(RetentionPolicy.RUNTIME) @OnTransition public static @interface StatesOnTransition { States[] source() default {}; States[] target() default {}; }
ClosedEntryAction is a entry action for state CLOSED to simply send and PLAY event to a statemachine if cd disc is present.
public static class ClosedEntryAction implements Action<States, Events> { @Override public void execute(StateContext<States, Events> context) { if (context.getTransition() != null && context.getEvent() == Events.PLAY && context.getTransition().getTarget().getId() == States.CLOSED && context.getExtendedState().getVariables().get(Variables.CD) != null) { context.getStateMachine().sendEvent(Events.PLAY); } } }
LoadAction is simply updating extended state variable if event headers contained information about a cd disc to load.
public static class LoadAction implements Action<States, Events> { @Override public void execute(StateContext<States, Events> context) { Object cd = context.getMessageHeader(Variables.CD); context.getExtendedState().getVariables().put(Variables.CD, cd); } }
PlayAction is simply resetting player elapsed time which is kept as an extended state variable.
public static class PlayAction implements Action<States, Events> { @Override public void execute(StateContext<States, Events> context) { context.getExtendedState().getVariables().put(Variables.ELAPSEDTIME, 0l); context.getExtendedState().getVariables().put(Variables.TRACK, 0); } }
PlayGuard is used to guard transition from IDLE to BUSY with event PLAY if extended state variable CD doesn’t indicate that cd disc has been loaded.
public static class PlayGuard implements Guard<States, Events> { @Override public boolean evaluate(StateContext<States, Events> context) { ExtendedState extendedState = context.getExtendedState(); return extendedState.getVariables().get(Variables.CD) != null; } }
PlayingAction is updating extended state variable ELAPSEDTIME which cd player itself can read and update lcd status. Action also handles track shift if user is going back or forward in tracks.
public static class PlayingAction implements Action<States, Events> { @Override public void execute(StateContext<States, Events> context) { Map<Object, Object> variables = context.getExtendedState().getVariables(); Object elapsed = variables.get(Variables.ELAPSEDTIME); Object cd = variables.get(Variables.CD); Object track = variables.get(Variables.TRACK); if (elapsed instanceof Long) { long e = ((Long)elapsed) + 1000l; if (e > ((Cd) cd).getTracks()[((Integer) track)].getLength()*1000) { context.getStateMachine().sendEvent(MessageBuilder .withPayload(Events.FORWARD) .setHeader(Headers.TRACKSHIFT.toString(), 1).build()); } else { variables.put(Variables.ELAPSEDTIME, e); } } } }
TrackAction handles track shift action if user is going back or forward in tracks. If it is a last track of a cd, playing is stopped and STOP event sent to a state machine.
public static class TrackAction implements Action<States, Events> { @Override public void execute(StateContext<States, Events> context) { Map<Object, Object> variables = context.getExtendedState().getVariables(); Object trackshift = context.getMessageHeader(Headers.TRACKSHIFT.toString()); Object track = variables.get(Variables.TRACK); Object cd = variables.get(Variables.CD); if (trackshift instanceof Integer && track instanceof Integer && cd instanceof Cd) { int next = ((Integer)track) + ((Integer)trackshift); if (next >= 0 && ((Cd)cd).getTracks().length > next) { variables.put(Variables.ELAPSEDTIME, 0l); variables.put(Variables.TRACK, next); } else if (((Cd)cd).getTracks().length <= next) { context.getStateMachine().sendEvent(Events.STOP); } } } }
One other important aspect of a state machines is that they have their own responsibilies mostly around handling states and all application level logic should be kept outside. This means that application needs to have a ways to interact with a state machine and below sample is how cdplayer does it order to update lcd status. Also pay attention that we annotated CdPlayer with @WithStateMachine which instructs state machine to find methods from your pojo which are then called with various transitions.
@OnTransition(target = "BUSY") public void busy(ExtendedState extendedState) { Object cd = extendedState.getVariables().get(Variables.CD); if (cd != null) { cdStatus = ((Cd)cd).getName(); } }
In above example we use @OnTransition annotation to hook a callback when transition happens with a target state BUSY.
@StatesOnTransition(target = {States.CLOSED, States.IDLE}) public void closed(ExtendedState extendedState) { Object cd = extendedState.getVariables().get(Variables.CD); if (cd != null) { cdStatus = ((Cd)cd).getName(); } else { cdStatus = "No CD"; } trackStatus = ""; }
@OnTransition we used above can only be used with strings which are matched from enums. @StatesOnTransition is then something what user can create into his own application to get a type safe annotation where a real enums can be used.
Lets see an example how this state machine actually works.
sm>sm start Entry state IDLE Entry state CLOSED State machine started sm>cd lcd No CD sm>cd library 0: Greatest Hits 0: Bohemian Rhapsody 05:56 1: Another One Bites the Dust 03:36 1: Greatest Hits II 0: A Kind of Magic 04:22 1: Under Pressure 04:08 sm>cd eject Exit state CLOSED Entry state OPEN sm>cd load 0 Loading cd Greatest Hits sm>cd play Exit state OPEN Entry state CLOSED Exit state CLOSED Exit state IDLE Entry state BUSY Entry state PLAYING sm>cd lcd Greatest Hits Bohemian Rhapsody 00:03 sm>cd forward sm>cd lcd Greatest Hits Another One Bites the Dust 00:04 sm>cd stop Exit state PLAYING Exit state BUSY Entry state IDLE Entry state CLOSED sm>cd lcd Greatest Hits
What happened in above run:
- State machine is started which causes machine to get initialized.
- CD Player lcd screen status is printed.
- CD Library is printed.
- CD Player deck is opened.
- CD with index 0 is loaded into a deck.
- Play is causing deck to get closed and immediate playing because cd was inserted.
- We print lcd status and request next track.
- We stop playing.
This chapter tries to give solutions to question user is most likely to ask.
I want to transit to next state automatically.
There are few choices a state machine developer can choose.
- Implement an action and send appropriate event into a state machine which triggers a transition into a proper target state.
- Define deferred event within a state and before sending an event send a event which will be deferred and thus causing next appropriate state transition when it is more convenient to handle that event.
- Implement a triggerless transition which will automatically cause state transition into a next state when state has entry and its actions has been completed.
How I can initialise variables on state machine start.
Important concept in a state machine is that nothing really happens unless there is a trigger which is causing a state transition which then can fire actions. However, having said that, Spring Statemachine always have an initial transition when state machine is started. With this initial transition user can execute a simple action which within a StateContext can do whatever it likes with an extended state variables.
This appendix provides generic information about used classes and material in this reference documentation.
This appendix provides generic information about state machines.
Assuming we have states STATE1, STATE2 and events EVENT1, EVENT2, logic of state machine can be defined as shown in below quick example.
static enum States { STATE1, STATE2 } static enum Events { EVENT1, EVENT2 }
@Configuration @EnableStateMachine static class Config1 extends EnumStateMachineConfigurerAdapter<States, Events> { @Override public void configure(StateMachineStateConfigurer<States, Events> states) throws Exception { states .withStates() .initial(States.STATE1) .states(EnumSet.allOf(States.class)); } @Override public void configure(StateMachineTransitionConfigurer<States, Events> transitions) throws Exception { transitions .withExternal() .source(States.STATE1).target(States.STATE2) .event(Events.EVENT1) .and() .withExternal() .source(States.STATE2).target(States.STATE1) .event(Events.EVENT2); } }
@WithStateMachine static class MyBean { @OnTransition(target = "STATE1") void toState1() { } @OnTransition(target = "STATE2") void toState2() { } }
static class MyApp { @Autowired StateMachine<States, Events> stateMachine; void doSignals() { stateMachine.sendEvent(Events.EVENT1); stateMachine.sendEvent(Events.EVENT2); } }
- State Machine
- Main entity driving a collection of states together with regions, transitions and events.
- State
- A state models a situation during which some invariant condition holds. State is the main entity of a state machine where state changes are driven by an events.
- Transition
- A transition is a relationship between a source state and a target state. It may be part of a compound transition, which takes the state machine from one state configuration to another, representing the complete response of the state machine to an occurrence of an event of a particular type.
- Event
- An entity which is send to a state machine which then drives a various state changes.
- Initial State
- A special state in which the state machine starts. Initial state is always bound to a particulal state machine or a region. A state machine with a multiple regions may have a multiple initial states.
- End State
- Also called as a final state is a special kind of state signifying that the enclosing region is completed. If the enclosing region is directly contained in a state machine and all other regions in the state machine also are completed, then it means that the entire state machine is completed.
- Region
- A region is an orthogonal part of either a composite state or a state machine. It contains states and transitions.
- Guard
- Is a boolean expression evaluated dynamically based on the value of extended state variables and event parameters. Guard conditions affect the behavior of a state machine by enabling actions or transitions only when they evaluate to TRUE and disabling them when they evaluate to FALSE.
- Action
- A action is a behaviour executed during the triggering of the transition.
This appendix provides generic crash course to a state machine concepts.
A state is a model which a state machine can be in. It is always easier to describe state as a real world example rather than trying to abstract concepts with a generic documentation. For example lets take a simple example of a keyboard most of use are using every single day. If you have a full keyboard which has normal keys on a left side and the numeric keypad on a right side you may have noticed that the numeric keypad may be in a two different stated depending whether numlock is activated or not. If it is not active then typing will result navigation using arrows, etc. If numpad is active then typing will result numbers to be used. Essentially numpad part of a keyboard can be in two different states.
To relate state concept to programming it means that instead of using flags, nested if/else/break clauses or other impractical logic you simply rely on state, state variables or other interaction with a state machine.
Guard conditions are expressions which evaluates either to TRUE or FALSE based on extended state variables and event parameters. Guards are used with actions and transitions to dynamically choose if particular action or transition should be executed. Aspects of guards, event parameters and extended state variables are simply to make state machine desing much more simple.
Event is the most used trigger behaviour to drive a state machine. There are other ways to trigger behaviour to happen in state machine like a timer but events are the ones which really allows user to interact with a state machine. Events are also called as signals to possibly alter a state machine state.
A transition is a relationship between a source state and a target state. A switch from a state to another is a state transition caused by a trigger.
Internal transition is used when action needs to be executed without causing a state transition. With internal transition source and target state is always a same and it is identical with self-transition in the absence of state entry and exit actions.
Most of the cases external and local transition are functionally equivalent expect in cases where transition is happening between super and sub states. Local transition doesn’t cause exit and entry to source state if target state is a substate of a source state. Other way around, local transition doesn’t cause exit and entry to target state if target is a superstate of a source state.
Above image shows a different between local and external transitions with a very simplistic super and sub states.
Actions are the ones which really glues state machine state changes with a users own code. State machine can execute action on various changes and steps in a state machine like entering or exiting a state, or doing a state transition.
Actions usually have access to a state context which gives running code a choice to interact with a state machine in a various ways. State context i.e. is exposing a whole state machine so user can access extended state variables, event headers if transition is based on an event, or actual transition where it is possible to see more detailed where this state change is coming from and where it is going.
Concept of a hierarchical state machine is used to simplify state design when particular states can only exist together.
Hierarchical states are really an innovation in UML state machine over a traditional state machines like Mealy or Moore machines. Hierarchical states allows to define some level of abstraction is a sense how java developer would define a class structure with abstract classes. For example having a nested state machine user is able to define transition on a multiple level of states possibly with a different conditions. State machine will always try to see if current state is able to handle an event together with a transition guard conditions. If these conditions are not evaluated to true, state machine will simply see what a super state can handle.
Regions which are also called as orthogonal regions are usually viewed as exclusive OR operation applied to a states. Concept of a region in terms of a state machine is usually a little difficult to understang but things gets a little simpler with a simple example.
Some of use have a full size keyboard with main keys on a left side and numeric keys on a right side. You’ve probably noticed that both sides really have their own state which you see if you press a numlock key which only alters behaviour of numbad itself. If you don’t have a full size keyboard you can buy a simple external usb numbad having only numbad part of a keys. If left and right side can freely exist without the other they must have a totally different states which means they are operating on different state machines.
It would be a little inconvenient to handle two different statemachines as totally separate entities because in a sense they are still working together in a sense. This is why orthogonal regios can combine together a multiple simultaneous states withing a single state in a state machine.