Spring Statemachine - Reference Documentation 05.07.

2021, 21:55

When persisting machines with regions or generally relying on any functionalities to reset a machine, you may
need to have a dedicated ID for a region. By default, this ID is a generated UUID. As the following example
shows, StateConfigurer has a method called region(String id) that lets you set the ID for a region:

J AAVVA
@Configuration
@EnableStateMachine
public class Config10RegionId
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)
.region("R1")
.initial(States2.S2I)
.state(States2.S21)
.end(States2.S2F)
.and()
.withStates()
.parent(States2.S2)
.region("R2")
.initial(States2.S3I)
.state(States2.S31)
.end(States2.S3F);
}

Configuring Transitions
We support three di!erent types of transitions: external , internal , and local . Transitions are triggered
either by a signal (which is an event sent into a state machine) or by a timer. The following example shows how
to de"ne all three kinds of transitions:

J AAVVA
@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));
}

https://docs.spring.io/spring-statemachine/docs/3.0.0/reference/#statemachine-recipes Page 20 of 231

Spring Statemachine - Reference Documentation 05.07.2021, 21:55

@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);
}

Configuring Guards
You can use guards to protect state transitions. You can use the Guard interface to do an evaluation where a
method has access to a StateContext . The following example shows how to do so:

J AAVVA
@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;
}
};
}

https://docs.spring.io/spring-statemachine/docs/3.0.0/reference/#statemachine-recipes Page 21 of 231

Spring Statemachine - Reference Documentation 05.07.2021, 21:55

In the preceding example, we used two di!erent types of guard con"gurations. First, we created a simple
Guard as a bean and attached it to the transition between states S1 and S2 .

Second, we used a SPeL expression as a guard to dicate that the expression must return a BOOLEAN value.
Behind the scenes, this expression-based guard is a SpelExpressionGuard . We attached it to the transition
between states S2 and S3 . Both guards always evaluate to true .

Configuring Actions
You can de"ne actions to be executed with transitions and states. An action is always run as a result of a
transition that originates from a trigger. The following example shows how to de"ne an action:

J AAVVA
@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 the preceding example, a single Action is de"ned as a bean named action and associated with a
transition from S1 to S2 . The following example shows how to use an action multiple times:

J AAVVA
@Configuration
@EnableStateMachine

https://docs.spring.io/spring-statemachine/docs/3.0.0/reference/#statemachine-recipes Page 22 of 231

Spring Statemachine - Reference Documentation 05.07.2021, 21:55

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
}
};
}

Usually, you would not de"ne the same Action instance for di!erent stages, but we did it here to not
make too much noise in a code snippet.

In the preceding example, a single Action is de"ned by the bean named action and associated with states
S1 , S2 , and S3 . We need to clarify what is going on here:

We de"ned an action for the initial state, S1 .

We de"ned an entry action for state S1 and left the exit action empty.

We de"ned an exit action for state S2 and left the entry action empty.

We de"ned a single state action for state S2 .

We de"ned both entry and exit actions for state S3 .

Note that state S1 is used twice with initial() and state() functions. You need to do this only if you
want to de"ne entry or exit actions with initial state.

De"ning action with initial() function only runs a particular action when a state machine or sub state
is started. This action is an initializing action that is run only once. An action de"ned with state() is then
run if the state machine transitions back and forward between initial and non-initial states.

https://docs.spring.io/spring-statemachine/docs/3.0.0/reference/#statemachine-recipes Page 23 of 231

Spring Statemachine - Reference Documentation 05.07.2021, 21:55

State Actions
State actions are run di!erently compared to entry and exit actions, because execution happens after state has
been entered and can be cancelled if state exit happens before a particular action has been completed.

State actions are executed using normal reactive #ow by subscribing with a Reactor’s default parallel scheduler.
This means that, whatever you do in your action, you need to be able to catch InterruptedException or, more
generally, periodically check whether Thread is interrupted.

The following example shows typical con"guration that uses default the IMMEDIATE_CANCEL , which would
immediately cancel a running task when its state is complete:

J AAVVA
@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");
}
}

You can set a policy to TIMEOUT_CANCEL together with a global timeout for each machine. This changes state
behavior to await action completion before cancelation is requested. The following example shows how to do
so:

https://docs.spring.io/spring-statemachine/docs/3.0.0/reference/#statemachine-recipes Page 24 of 231

Spring Statemachine - Reference Documentation 05.07.2021, 21:55

J AAVVA
@Override
public void configure(StateMachineConfigurationConfigurer<String, String> config) throws Exception {
config
.withConfiguration()
.stateDoActionPolicy(StateDoActionPolicy.TIMEOUT_CANCEL)
.stateDoActionPolicyTimeout(10, TimeUnit.SECONDS);
}

If Event directly takes a machine into a state so that event headers are available to a particular action, you can
also use a dedicated event header to set a speci"c timeout (de"ned in millis ). You can use the reserved
header value StateMachineMessageHeaders.HEADER_DO_ACTION_TIMEOUT for this purpose. The following
example shows how to do so:

J AAVVA
@Autowired
StateMachine<String, String> stateMachine;

void sendEventUsingTimeout() {
stateMachine
.sendEvent(Mono.just(MessageBuilder
.withPayload("E1")
.setHeader(StateMachineMessageHeaders.HEADER_DO_ACTION_TIMEOUT, 5000)
.build()))
.subscribe();

Transition Action Error Handling

You can always catch exceptions manually. However, with actions de"ned for transitions, you can de"ne an
error action that is called if an exception is raised. The exception is then available from a StateContext passed
to that action. The following example shows how to create a state that handles an exception:

J AAVVA
@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

https://docs.spring.io/spring-statemachine/docs/3.0.0/reference/#statemachine-recipes Page 25 of 231