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.
![[Note]](images/note.png) | Note |
|---|---|
|
Configuration examples in this section are not feature complete, i.e. you always need to have definitions of both states and transitions, otherwise state machine configuration would be ill-formed. We have simply made code snippets less verbose by leaving other needed parts away. |
We use familiar spring enabler annotations to ease configuration. Two annotations exists, @EnableStateMachine and @EnableStateMachineFactory. These annotations if placed in a @Configuration class will enable some basic functionality needed by a state machines.
@EnableStateMachine is used when a configuration wants to create an
instance of a StateMachine. Usually @Configuration class extends adapters
EnumStateMachineConfigurerAdapter or StateMachineConfigurerAdapter which
allows user to override configuration callback methods. We automatically
detect if user is using these adapter classes and modify runtime configuration
logic.
@EnableStateMachineFactory is used when a configuration wants to create an instance of a StateMachineFactory.
| Note |
|---|---|
|
Usage examples of these are shown in below sections. |
We’ll get into more complex configuration examples a bit later but
let’s 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 class Config1Enums 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)); } }
It’s also possible to use strings instead of enums as states and
events by using StateMachineConfigurerAdapter as shown below. Most
of a configuration examples is using enums but generally speaking
strings and enums can be just interchanged.
@Configuration @EnableStateMachine public class Config1Strings extends StateMachineConfigurerAdapter<String, String> { @Override public void configure(StateMachineStateConfigurer<String, String> states) throws Exception { states .withStates() .initial("S1") .end("SF") .states(new HashSet<String>(Arrays.asList("S1","S2","S3","S4"))); } }
| Note |
|---|---|
|
Using enums will bring more safe set of states and event types but limits possible combinations to compile time. Strings don’t have this limitation and allows user to use more dynamic ways to build state machine configurations but doesn’t allow same level of safety. |
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 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); } }
There are no special configuration methods to mark a collection of states to be part of an orthogonal state. To put it simple, orthogonal state is created when same hierarchical state machine has multiple set of states each having a initial state. Because an individual state machine can only have one initial state, multiple initial states must mean that a specific state must have multiple independent regions.
@Configuration @EnableStateMachine public class Config10 extends EnumStateMachineConfigurerAdapter<States2, Events> { @Override public void configure(StateMachineStateConfigurer<States2, Events> states) throws Exception { states .withStates() .initial(States2.S1) .state(States2.S2) .and() .withStates() .parent(States2.S2) .initial(States2.S2I) .state(States2.S21) .end(States2.S2F) .and() .withStates() .parent(States2.S2) .initial(States2.S3I) .state(States2.S31) .end(States2.S3F); } }
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 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 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
expression 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 to be executed with transitions and states itself. Action is always executed as a result of a transition which originates from a trigger.
@Configuration @EnableStateMachine public class Config51 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 } }; } }
In above a single Action is defined as bean action and associated
with a transition from S1 to S2.
@Configuration @EnableStateMachine public class Config52 extends EnumStateMachineConfigurerAdapter<States, Events> { @Override public void configure(StateMachineStateConfigurer<States, Events> states) throws Exception { states .withStates() .initial(States.S1, action()) .state(States.S1, action(), null) .state(States.S2, null, action()) .state(States.S2, action()) .state(States.S3, action(), action()); } @Bean public Action<States, Events> action() { return new Action<States, Events>() { @Override public void execute(StateContext<States, Events> context) { // do something } }; } }
| Note |
|---|---|
|
Usually you would not define same |
In above a single Action is defined as bean action and associated
with states S1, S2 and S3. There is more going on there which
needs more clarification:
-
We defined action for initial state
S1. -
We defined entry action for state
S1and left exit action empty. -
We defined exit action for state
S2and left entry action empty. -
We defined a single state action for state
S2. -
We defined entry action as well as exit action for state
S3. -
Notice how state
S1is used twice withinitial()andstate()functions. This is only needed if you want to define entry or exit actions with initial state.
![[Important]](images/important.png) | Important |
|---|---|
|
Defining action with |
State actions are executed differently compared to entry and exit actions simply because execution happens after state has been entered and can be cancelled if state exit happens before particular action has been completed.
State Actions are executed using a normal Spring TaskScheduler
wrapped within a Runnable which may get cancelled via
ScheduledFuture. What this means is that whatever you’re doing in your
action, you need to be able to catch InterruptedException or generally
periodically check if Thread is interrupted.
Below shows typical config which uses default IMMEDIATE_CANCEL which would simply cancel running task immediately when state is complete.
@Configuration @EnableStateMachine static class Config1 extends StateMachineConfigurerAdapter<String, String> { @Override public void configure(StateMachineConfigurationConfigurer<String, String> config) throws Exception { config .withConfiguration() .stateDoActionPolicy(StateDoActionPolicy.IMMEDIATE_CANCEL); } @Override public void configure(StateMachineStateConfigurer<String, String> states) throws Exception { states .withStates() .initial("S1") .state("S2", context -> {}) .state("S3"); } @Override public void configure(StateMachineTransitionConfigurer<String, String> transitions) throws Exception { transitions .withExternal() .source("S1") .target("S2") .event("E1") .and() .withExternal() .source("S2") .target("S3") .event("E2"); } }
Policy can be set to TIMEOUT_CANCEL together with a global timeout per machine. This changes state behaviour to wait action completion before cancel is requested.
@Override public void configure(StateMachineConfigurationConfigurer<String, String> config) throws Exception { config .withConfiguration() .stateDoActionPolicy(StateDoActionPolicy.TIMEOUT_CANCEL) .stateDoActionPolicyTimeout(10, TimeUnit.SECONDS); }
If Event directly take machine into a state so that event headers are available to particular action, it is also possible to use dedicated event header to instruct a specific timeout which is defined in millis. Reserved header value StateMachineMessageHeaders.HEADER_DO_ACTION_TIMEOUT is used for this.
@Autowired StateMachine<String, String> stateMachine; void sendEventUsingTimeout() { stateMachine.sendEvent(MessageBuilder .withPayload("E1") .setHeader(StateMachineMessageHeaders.HEADER_DO_ACTION_TIMEOUT, 5000) .build()); }
User can always catch exceptions manually but with actions defined for
transitions it is possible to define error action which is called if
exception is raised. Exception is then available from a StateContext
passed to that action.
@Configuration @EnableStateMachine public class Config53 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(), errorAction()); } @Bean public Action<States, Events> action() { return new Action<States, Events>() { @Override public void execute(StateContext<States, Events> context) { throw new RuntimeException("MyError"); } }; } @Bean public Action<States, Events> errorAction() { return new Action<States, Events>() { @Override public void execute(StateContext<States, Events> context) { // RuntimeException("MyError") added to context Exception exception = context.getException(); exception.getMessage(); } }; } }
Similar logic can be done manually for every action if needed.
@Override public void configure(StateMachineTransitionConfigurer<States, Events> transitions) throws Exception { transitions .withExternal() .source(States.S1) .target(States.S2) .event(Events.E1) .action(Actions.errorCallingAction(action(), errorAction())); }
Similar logic for error handling what is available for transition actions is also available for actions defined for state behaviour and its entry and exit.
For these StateConfigurer has methods stateEntry, stateDo and
stateExit to define error action together with an actual action.
@Configuration @EnableStateMachine public class Config55 extends EnumStateMachineConfigurerAdapter<States, Events> { @Override public void configure(StateMachineStateConfigurer<States, Events> states) throws Exception { states .withStates() .initial(States.S1) .stateEntry(States.S2, action(), errorAction()) .stateDo(States.S2, action(), errorAction()) .stateExit(States.S2, action(), errorAction()) .state(States.S3); } @Bean public Action<States, Events> action() { return new Action<States, Events>() { @Override public void execute(StateContext<States, Events> context) { throw new RuntimeException("MyError"); } }; } @Bean public Action<States, Events> errorAction() { return new Action<States, Events>() { @Override public void execute(StateContext<States, Events> context) { // RuntimeException("MyError") added to context Exception exception = context.getException(); exception.getMessage(); } }; } }
Pseudo state configuration is usually done by configuring states and transitions. Pseudo states are automatically added to state machine as states.
Simply mark a particular state as initial state by using initial()
method. There are two methods where one takes extra argument to define
an initial action. This initial action is good for example initialize
extended state variables.
@Configuration @EnableStateMachine public class Config11 extends EnumStateMachineConfigurerAdapter<States, Events> { @Override public void configure(StateMachineStateConfigurer<States, Events> states) throws Exception { states .withStates() .initial(States.S1, initialAction()) .end(States.SF) .states(EnumSet.allOf(States.class)); } @Bean public Action<States, Events> initialAction() { return new Action<States, Events>() { @Override public void execute(StateContext<States, Events> context) { // do something initially } }; } }
Simply mark a particular state as end state by using end() method.
This can be done max one time per individual sub-machine or region.
@Configuration @EnableStateMachine public class Config1Enums 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)); } }
History state can be defined once for each individual state machine.
You need to choose its state identifier and History.SHALLOW or
History.DEEP respectively.
@Configuration @EnableStateMachine public class Config12 extends EnumStateMachineConfigurerAdapter<States3, Events> { @Override public void configure(StateMachineStateConfigurer<States3, Events> states) throws Exception { states .withStates() .initial(States3.S1) .state(States3.S2) .and() .withStates() .parent(States3.S2) .initial(States3.S2I) .state(States3.S21) .state(States3.S22) .history(States3.SH, History.SHALLOW); } @Override public void configure(StateMachineTransitionConfigurer<States3, Events> transitions) throws Exception { transitions .withHistory() .source(States3.SH) .target(States3.S22); } }
Also as shown above, optionally it is possible to define a default transition from a history state into a state vertex in a same machine. This transition takes place as a default if for example machine has never been entered, thus no history would be available. If default state transition is not defined, then normal entry into a region is done. This default transition is also used if machine’s history is a final state.
Choice needs to be defined in both states and transitions to work
properly. Mark particular state as choice state by using choice()
method. This state needs to match source state when transition is
configured for this choice.
Transition is configured using withChoice() where you define source
state and first/then/last structure which is equivalent to normal
if/elseif/else. With first and then you can specify a guard just
like you’d use a condition with if/elseif clauses.
Transition needs to be able to exist so make sure last is used.
Otherwise configuration is ill-formed.
@Configuration @EnableStateMachine public class Config13 extends EnumStateMachineConfigurerAdapter<States, Events> { @Override public void configure(StateMachineStateConfigurer<States, Events> states) throws Exception { states .withStates() .initial(States.SI) .choice(States.S1) .end(States.SF) .states(EnumSet.allOf(States.class)); } @Override public void configure(StateMachineTransitionConfigurer<States, Events> transitions) throws Exception { transitions .withChoice() .source(States.S1) .first(States.S2, s2Guard()) .then(States.S3, s3Guard()) .last(States.S4); } @Bean public Guard<States, Events> s2Guard() { return new Guard<States, Events>() { @Override public boolean evaluate(StateContext<States, Events> context) { return false; } }; } @Bean public Guard<States, Events> s3Guard() { return new Guard<States, Events>() { @Override public boolean evaluate(StateContext<States, Events> context) { return true; } }; } }
Actions can be executed with both incoming and outgoing transitions of a choice pseudostate. As seeing from below example, one dummy lambda action is defined leading into a choice state and one similar dummy lambda action defined for one outgoing transition where it also define an error action.
@Configuration @EnableStateMachine public class Config23 extends EnumStateMachineConfigurerAdapter<States, Events> { @Override public void configure(StateMachineStateConfigurer<States, Events> states) throws Exception { states .withStates() .initial(States.SI) .choice(States.S1) .end(States.SF) .states(EnumSet.allOf(States.class)); } @Override public void configure(StateMachineTransitionConfigurer<States, Events> transitions) throws Exception { transitions .withExternal() .source(States.SI) .action(c -> { // action with SI-S1 }) .target(States.S1) .and() .withChoice() .source(States.S1) .first(States.S2, c -> { return true; }) .last(States.S3, c -> { // action with S1-S3 }, c -> { // error callback for action S1-S3 }); } }
| Note |
|---|---|
|
Junction have same api format meaning actions can be defined similarly. |
Junction needs to be defined in both states and transitions to work
properly. Mark particular state as choice state by using junction()
method. This state needs to match source state when transition is
configured for this choice.
Transition is configured using withJunction() where you define source
state and first/then/last structure which is equivalent to normal
if/elseif/else. With first and then you can specify a guard just
like you’d use a condition with if/elseif clauses.
Transition needs to be able to exist so make sure last is used.
Otherwise configuration is ill-formed.
@Configuration @EnableStateMachine public class Config20 extends EnumStateMachineConfigurerAdapter<States, Events> { @Override public void configure(StateMachineStateConfigurer<States, Events> states) throws Exception { states .withStates() .initial(States.SI) .junction(States.S1) .end(States.SF) .states(EnumSet.allOf(States.class)); } @Override public void configure(StateMachineTransitionConfigurer<States, Events> transitions) throws Exception { transitions .withJunction() .source(States.S1) .first(States.S2, s2Guard()) .then(States.S3, s3Guard()) .last(States.S4); } @Bean public Guard<States, Events> s2Guard() { return new Guard<States, Events>() { @Override public boolean evaluate(StateContext<States, Events> context) { return false; } }; } @Bean public Guard<States, Events> s3Guard() { return new Guard<States, Events>() { @Override public boolean evaluate(StateContext<States, Events> context) { return true; } }; } }
| Note |
|---|---|
|
Difference between choice and junction is purely academic as both are
implemented with |
Fork needs to be defined in both states and transitions to work
properly. Mark particular state as choice state by using fork()
method. This state needs to match source state when transition is
configured for this fork.
Target state needs to be a super state or immediate states in regions. Using a super state as target will take all regions into initial states. Targeting individual state give more controlled entry into regions.
@Configuration @EnableStateMachine public class Config14 extends EnumStateMachineConfigurerAdapter<States2, Events> { @Override public void configure(StateMachineStateConfigurer<States2, Events> states) throws Exception { states .withStates() .initial(States2.S1) .fork(States2.S2) .state(States2.S3) .and() .withStates() .parent(States2.S3) .initial(States2.S2I) .state(States2.S21) .state(States2.S22) .end(States2.S2F) .and() .withStates() .parent(States2.S3) .initial(States2.S3I) .state(States2.S31) .state(States2.S32) .end(States2.S3F); } @Override public void configure(StateMachineTransitionConfigurer<States2, Events> transitions) throws Exception { transitions .withFork() .source(States2.S2) .target(States2.S22) .target(States2.S32); } }
Join needs to be defined in both states and transitions to work
properly. Mark particular state as choice state by using join()
method. This state doesn’t need to match either source states or
target state in a transition configuration.
Select a target state where transition goes when all source states has been joined. If you use state hosting regions as source, end states of a regions are used as joins. Otherwise you can pick any states from a regions.
@Configuration @EnableStateMachine public class Config15 extends EnumStateMachineConfigurerAdapter<States2, Events> { @Override public void configure(StateMachineStateConfigurer<States2, Events> states) throws Exception { states .withStates() .initial(States2.S1) .state(States2.S3) .join(States2.S4) .state(States2.S5) .and() .withStates() .parent(States2.S3) .initial(States2.S2I) .state(States2.S21) .state(States2.S22) .end(States2.S2F) .and() .withStates() .parent(States2.S3) .initial(States2.S3I) .state(States2.S31) .state(States2.S32) .end(States2.S3F); } @Override public void configure(StateMachineTransitionConfigurer<States2, Events> transitions) throws Exception { transitions .withJoin() .source(States2.S2F) .source(States2.S3F) .target(States2.S4) .and() .withExternal() .source(States2.S4) .target(States2.S5); } }
It is also possible to have multiple transitions originating from a join state. It this case it is advised to use guards and define those so that only one guard evaluates TRUE at any given time as otherwise transition behaviour is not predicted. This is shown above where guard simply checks if extended state has variables.
@Configuration @EnableStateMachine public class Config22 extends EnumStateMachineConfigurerAdapter<States2, Events> { @Override public void configure(StateMachineStateConfigurer<States2, Events> states) throws Exception { states .withStates() .initial(States2.S1) .state(States2.S3) .join(States2.S4) .state(States2.S5) .end(States2.SF) .and() .withStates() .parent(States2.S3) .initial(States2.S2I) .state(States2.S21) .state(States2.S22) .end(States2.S2F) .and() .withStates() .parent(States2.S3) .initial(States2.S3I) .state(States2.S31) .state(States2.S32) .end(States2.S3F); } @Override public void configure(StateMachineTransitionConfigurer<States2, Events> transitions) throws Exception { transitions .withJoin() .source(States2.S2F) .source(States2.S3F) .target(States2.S4) .and() .withExternal() .source(States2.S4) .target(States2.S5) .guardExpression("!extendedState.variables.isEmpty()") .and() .withExternal() .source(States2.S4) .target(States2.SF) .guardExpression("extendedState.variables.isEmpty()"); } }
Exit and Entry Points can be used to do more controlled exit and entry from and into a submachines.
@Configuration @EnableStateMachine static class Config21 extends StateMachineConfigurerAdapter<String, String> { @Override public void configure(StateMachineStateConfigurer<String, String> states) throws Exception { states .withStates() .initial("S1") .state("S2") .state("S3") .and() .withStates() .parent("S2") .initial("S21") .entry("S2ENTRY") .exit("S2EXIT") .state("S22"); } @Override public void configure(StateMachineTransitionConfigurer<String, String> transitions) throws Exception { transitions .withExternal() .source("S1").target("S2") .event("E1") .and() .withExternal() .source("S1").target("S2ENTRY") .event("ENTRY") .and() .withExternal() .source("S22").target("S2EXIT") .event("EXIT") .and() .withEntry() .source("S2ENTRY").target("S22") .and() .withExit() .source("S2EXIT").target("S3"); } }
As shown above you need to mark particular states as exit and entry states. Then you create a normal transitions into those states and also specify withExit() and withEntry() where those states will exit and entry respectively.
Some of a common state machine configuration can be set via a
ConfigurationConfigurer. This allows to set BeanFactory,
TaskExecutor, TaskScheduler, autostart flag for a state machine
and register StateMachineListener instances.
@Configuration @EnableStateMachine public class Config17 extends EnumStateMachineConfigurerAdapter<States, Events> { @Override public void configure(StateMachineConfigurationConfigurer<States, Events> config) throws Exception { config .withConfiguration() .autoStartup(true) .machineId("myMachineId") .beanFactory(new StaticListableBeanFactory()) .taskExecutor(new SyncTaskExecutor()) .taskScheduler(new ConcurrentTaskScheduler()) .listener(new StateMachineListenerAdapter<States, Events>()) .transitionConflictPolicy(TransitionConflictPolicy.CHILD); } }
State machine autoStartup flag is disabled by default because all
instances handling sub-states are controlled by a state machine itself
and cannot be started automatically. Also it is much safer to leave
this decision to a user whether a machine should be started
automatically or not. This flag will only control an autostart of a
top-level state machine.
Setting machineId within a configuration is simply a convenience if
user wants or needs to do it here.
Setting a BeanFactory, TaskExecutor or TaskScheduler exist for
convenience for a user and are also use within a framework itself.
Registering StateMachineListener instances is also partly for
convenience but is required if user wants to catch callback during a
state machine lifecycle like getting notified of a state machine
start/stop events. Naturally it is not possible to listen a state
machine start events if autoStartup is enabled unless listener can
be registered during a configuration phase.
transitionConflictPolicy can be used in cases where multiple
transition paths could be selected. One usual use case for this is if
machine contains anonymous transitions leading out from a sub-state
and a parent state and user want to define a policy which one will be
selected. This is a global setting within a machine instance and
default to CHILD.
DistributedStateMachine is configured via withDistributed() which
allows to set a StateMachineEnsemble which if exists automatically
wraps created StateMachine with DistributedStateMachine and
enables distributed mode.
@Configuration @EnableStateMachine public class Config18 extends EnumStateMachineConfigurerAdapter<States, Events> { @Override public void configure(StateMachineConfigurationConfigurer<States, Events> config) throws Exception { config .withDistributed() .ensemble(stateMachineEnsemble()); } @Bean public StateMachineEnsemble<States, Events> stateMachineEnsemble() throws Exception { // naturally not null but should return ensemble instance return null; } }
More about distributed states, refer to section Chapter 31, Using Distributed States.
StateMachineModelVerifier is an interface what is used internally to
do some sanity checks for a state machine structure. Its purpose is to
fail fast early instead of letting common configuration errors into a
state machine itself. On default verifier is automatically enabled and
DefaultStateMachineModelVerifier implementation is used.
With withVerifier() user can disable verifier or set a custom one if
needed.
@Configuration @EnableStateMachine public class Config19 extends EnumStateMachineConfigurerAdapter<States, Events> { @Override public void configure(StateMachineConfigurationConfigurer<States, Events> config) throws Exception { config .withVerifier() .enabled(true) .verifier(verifier()); } @Bean public StateMachineModelVerifier<States, Events> verifier() { return new StateMachineModelVerifier<States, Events>() { @Override public void verify(StateMachineModel<States, Events> model) { // throw exception indicating malformed model } }; } }
More about config model, refer to section Section 55.1, “StateMachine Config Model”.
| Note |
|---|---|
|
Config methods |
StateMachineModelFactory is a hook to configure statemachine model
without using a manual configuration. Essentially it is a third party
integration to integrate into a configuration model.
StateMachineModelFactory can be hooked into a configuration model by
using a StateMachineModelConfigurer as shown above.
@Configuration @EnableStateMachine public static class Config1 extends StateMachineConfigurerAdapter<String, String> { @Override public void configure(StateMachineModelConfigurer<String, String> model) throws Exception { model .withModel() .factory(modelFactory()); } @Bean public StateMachineModelFactory<String, String> modelFactory() { return new CustomStateMachineModelFactory(); } }
As a custom example CustomStateMachineModelFactory would simply
define two states, S1 and S2 and an event E1 between those
states.
public static class CustomStateMachineModelFactory implements StateMachineModelFactory<String, String> { @Override public StateMachineModel<String, String> build() { ConfigurationData<String, String> configurationData = new ConfigurationData<>(); Collection<StateData<String, String>> stateData = new ArrayList<>(); stateData.add(new StateData<String, String>("S1", true)); stateData.add(new StateData<String, String>("S2")); StatesData<String, String> statesData = new StatesData<>(stateData); Collection<TransitionData<String, String>> transitionData = new ArrayList<>(); transitionData.add(new TransitionData<String, String>("S1", "S2", "E1")); TransitionsData<String, String> transitionsData = new TransitionsData<>(transitionData); StateMachineModel<String, String> stateMachineModel = new DefaultStateMachineModel<String, String>(configurationData, statesData, transitionsData); return stateMachineModel; } @Override public StateMachineModel<String, String> build(String machineId) { return build(); } }
| Note |
|---|---|
|
Defining a custom model is usually not what end user is looking for, although it is possible, however it is a central concept of allowing external access to this configuration model. |
Example of using this model factory integration can be found from Chapter 33, Eclipse Modeling Support. More generic info about custom model integration can be found from Chapter 55, Developer Documentation.
When defining actions, guards or any other references from a
configuration there are things to remember how Spring Framework works
with beans. In below we have defined a normal configuration with
states S1 and S2 and 4 transitions between those. All transitions
are either guarded by guard1 or guard2. Pay attention that
guard1 is created as a real bean because it’s annotated with a
@Bean, while guard2 is not.
What this mean is that event E3 would get guard2 condition as
TRUE and E4 would get guard2 condition as FALSE as those are
simply coming from a plain method calls to those functions.
However because guard1 is defined as a @Bean, it is proxied by a
Spring Framework, thus additional calls to its method will result
only one instantiation of that instance. Event E1 would get first
proxied instance with condition TRUE while event E2 would get same
instance with TRUE condition while method call was defined with
FALSE. This is not a Spring State Machine specific behaviour, it’s
just how Spring Framework works with Beans.
@Configuration @EnableStateMachine public class Config1 extends StateMachineConfigurerAdapter<String, String> { @Override public void configure(StateMachineStateConfigurer<String, String> states) throws Exception { states .withStates() .initial("S1") .state("S2"); } @Override public void configure(StateMachineTransitionConfigurer<String, String> transitions) throws Exception { transitions .withExternal() .source("S1").target("S2").event("E1").guard(guard1(true)) .and() .withExternal() .source("S1").target("S2").event("E2").guard(guard1(false)) .and() .withExternal() .source("S1").target("S2").event("E3").guard(guard2(true)) .and() .withExternal() .source("S1").target("S2").event("E4").guard(guard2(false)); } @Bean public Guard<String, String> guard1(final boolean value) { return new Guard<String, String>() { @Override public boolean evaluate(StateContext<String, String> context) { return value; } }; } public Guard<String, String> guard2(final boolean value) { return new Guard<String, String>() { @Override public boolean evaluate(StateContext<String, String> context) { return value; } }; } }