Preface​

The concept of a state machine is most likely older than any reader of this reference documentation and definitely older than the Java language itself. Description of finite automata dates back to 1943 when gentlemen Warren McCulloch and Walter Pitts wrote a paper about it. Later George H. Mealy presented a state machine concept (known as a “Mealy Machine”) in 1955. A year later, in 1956, Edward F. Moore presented another paper, in which he described what is known as a “Moore Machine”. If you have ever read anything about state machines, the names, Mealy and Moore, should have popped up at some point.

This reference documentation contains the following parts:

Introduction contains introduction to this reference documentation.

Using Spring Statemachine describes the usage of Spring Statemachine(SSM).

State Machine Examples contains more detailed state machine examples.

FAQ contains frequently asked questions.

Appendices contains generic information about used material and state machines.

Introduction

Spring Statemachine (SSM) is a framework that lets application developers use traditional state machine concepts with Spring applications. SSM provides the 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, we recommend going through the appendices Glossary and A State Machine Crash Course to get a generic idea of what state machines are. The rest of the documentation expects you to be familiar with state machine concepts.

Background​

State machines are powerful because their behavior is always guaranteed to be consistent and relatively easily debugged due to how operational rules are written in stone when a machine is started. The idea is that your application is now in and may exist in a finite number of states. Then something happens that takes your application from one state to the next. A state machine is driven by triggers, which are based on either events or timers.

It is much easier to design high-level logic outside of your application and then interact with a state machine in various different ways. You can interact with a state machine by sending events, listening to what a state machine does, or requesting the current state.

Traditionally, state machines are added to an existing project when developers realize that the code base is starting to look like a plate full of spaghetti. Spaghetti code looks like a never ending, hierarchical structure of IF, ELSE, and BREAK clauses, and compilers should probably ask developers to go home when things are starting to look too complex.

Usage Scenarios​

A project is a good candidate to use a state machine when:

• You can represent the application or part of its structure as states.

• You want to split complex logic into smaller manageable tasks.

• The application is already suffering concurrency issues with (for example) something happening asynchronously.

You are already trying to implement a state machine when you:

• Use boolean flags or enums to model situations.

• Have variables that have meaning only for some part of your application lifecycle.

• Loop through an if-else structure (or, worse, multiple such structures), check whether a particular flag or enum is set, and then make further exceptions about what to do when certain combinations of your flags and enums exist or do not exist.

Getting started

If you are just getting started with Spring Statemachine, this is the section for you! Here, we answer the basic “what?”, “how?” and “why?” questions. We start with a gentle introduction to Spring Statemachine. We then build our first Spring Statemachine application and discuss some core principles as we go.

System Requirement​

Spring Statemachine 4.0.0 is built and tested with JDK 8 (all artifacts have JDK 7 compatibility) and Spring Framework 6.0.14. It does not require any other dependencies outside of Spring Framework within its core system.

Other optional parts (such as Using Distributed States) have dependencies on Zookeeper, while State Machine Examples has dependencies on spring-shell and spring-boot, which pull other dependencies beyond the framework itself. Also, the optional security and data access features have dependencies to on Spring Security and Spring Data modules.

Modules​

The following table describes the modules that are available for Spring Statemachine.

Using Gradle​

The following listing shows a typical build.gradle file created by choosing various settings at https://start.spring.io:

buildscript {
	ext {
		springBootVersion = '3.1.6'
	}
	repositories {
		mavenCentral()
		maven { url "https://repo.spring.io/snapshot" }
		maven { url "https://repo.spring.io/milestone" }
	}
	dependencies {
		classpath("org.springframework.boot:spring-boot-gradle-plugin:${springBootVersion}")
	}
}

apply plugin: 'java'
apply plugin: 'eclipse'
apply plugin: 'org.springframework.boot'
apply plugin: 'io.spring.dependency-management'

group = 'com.example'
version = '0.0.1-SNAPSHOT'
sourceCompatibility = 1.8

repositories {
	mavenCentral()
	maven { url "https://repo.spring.io/snapshot" }
	maven { url "https://repo.spring.io/milestone" }
}


ext {
	springStatemachineVersion = '4.0.0'
}

dependencies {
	compile('org.springframework.statemachine:spring-statemachine-starter')
	testCompile('org.springframework.boot:spring-boot-starter-test')
}

dependencyManagement {
	imports {
		mavenBom "org.springframework.statemachine:spring-statemachine-bom:${springStatemachineVersion}"
	}
}

With a normal project structure, you can build this project with the following command:

# ./gradlew clean build

The expected Spring Boot-packaged fat jar would be build/libs/demo-0.0.1-SNAPSHOT.jar.

Using Maven​

The following example shows a typical pom.xml file, which was created by choosing various options at https://start.spring.io:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>

	<groupId>com.example</groupId>
	<artifactId>demo</artifactId>
	<version>0.0.1-SNAPSHOT</version>
	<packaging>jar</packaging>

	<name>gs-statemachine</name>
	<description>Demo project for Spring Statemachine</description>

	<parent>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-parent</artifactId>
		<version>3.1.6</version>
		<relativePath/> <!-- lookup parent from repository -->
	</parent>

	<properties>
		<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
		<project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
		<java.version>1.8</java.version>
		<spring-statemachine.version>4.0.0</spring-statemachine.version>
	</properties>

	<dependencies>
		<dependency>
			<groupId>org.springframework.statemachine</groupId>
			<artifactId>spring-statemachine-starter</artifactId>
		</dependency>

		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-test</artifactId>
			<scope>test</scope>
		</dependency>
	</dependencies>

	<dependencyManagement>
		<dependencies>
			<dependency>
				<groupId>org.springframework.statemachine</groupId>
				<artifactId>spring-statemachine-bom</artifactId>
				<version>${spring-statemachine.version}</version>
				<type>pom</type>
				<scope>import</scope>
			</dependency>
		</dependencies>
	</dependencyManagement>

	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
			</plugin>
		</plugins>
	</build>

	<repositories>
		<repository>
			<id>spring-snapshots</id>
			<name>Spring Snapshots</name>
			<url>https://repo.spring.io/snapshot</url>
			<snapshots>
				<enabled>true</enabled>
			</snapshots>
		</repository>
		<repository>
			<id>spring-milestones</id>
			<name>Spring Milestones</name>
			<url>https://repo.spring.io/milestone</url>
			<snapshots>
				<enabled>false</enabled>
			</snapshots>
		</repository>
	</repositories>

	<pluginRepositories>
		<pluginRepository>
			<id>spring-snapshots</id>
			<name>Spring Snapshots</name>
			<url>https://repo.spring.io/snapshot</url>
			<snapshots>
				<enabled>true</enabled>
			</snapshots>
		</pluginRepository>
		<pluginRepository>
			<id>spring-milestones</id>
			<name>Spring Milestones</name>
			<url>https://repo.spring.io/milestone</url>
			<snapshots>
				<enabled>false</enabled>
			</snapshots>
		</pluginRepository>
	</pluginRepositories>


</project>

With a normal project structure, you can build this project with the following command:

# mvn clean package

The expected Spring Boot-packaged fat-jar would be target/demo-0.0.1-SNAPSHOT.jar.

Developing Your First Spring Statemachine Application​

You can start by creating a simple Spring Boot Application class that implements CommandLineRunner. The following example shows how to do so:

@SpringBootApplication
public class Application implements CommandLineRunner {

    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }

}

Then you need to add states and events, as the following example shows:

public enum States {
    SI, S1, S2
}

public enum Events {
    E1, E2
}

Then you need to add state machine configuration, as the following example shows:

@Configuration
@EnableStateMachine
public class StateMachineConfig
        extends EnumStateMachineConfigurerAdapter<States, Events> {

    @Override
    public void configure(StateMachineConfigurationConfigurer<States, Events> config)
            throws Exception {
        config
            .withConfiguration()
                .autoStartup(true)
                .listener(listener());
    }

    @Override
    public void configure(StateMachineStateConfigurer<States, Events> states)
            throws Exception {
        states
            .withStates()
                .initial(States.SI)
                    .states(EnumSet.allOf(States.class));
    }

    @Override
    public void configure(StateMachineTransitionConfigurer<States, Events> transitions)
            throws Exception {
        transitions
            .withExternal()
                .source(States.SI).target(States.S1).event(Events.E1)
                .and()
            .withExternal()
                .source(States.S1).target(States.S2).event(Events.E2);
    }

    @Bean
    public StateMachineListener<States, Events> listener() {
        return new StateMachineListenerAdapter<States, Events>() {
            @Override
            public void stateChanged(State<States, Events> from, State<States, Events> to) {
                System.out.println("State change to " + to.getId());
            }
        };
    }
}

Then you need to implement CommandLineRunner and autowire StateMachine. The following example shows how to do so:

@Autowired
private StateMachine<States, Events> stateMachine;

@Override
public void run(String... args) throws Exception {
    stateMachine.sendEvent(Events.E1);
    stateMachine.sendEvent(Events.E2);
}

Depending on whether you build your application with Gradle or Maven, you can run it by using java -jar build/libs/gs-statemachine-0.1.0.jar or java -jar target/gs-statemachine-0.1.0.jar, respectively.

The result of this command should be normal Spring Boot output. However, you should also find the following lines:

State change to SI
State change to S1
State change to S2

These lines indicate that the machine you constructed is moving from one state to another, as it should.

What’s New

In 1.1​

Spring Statemachine 1.1 focuses on security and better interoperability with web applications. It includes the following:

• Comprehensive support for Spring Security has been added. See State Machine Security.

• Context integration with `@WithStateMachine' has been greatly enhanced. See Context Integration.

• StateContext is now a first class citizen, letting you interact with a State Machine. See Using StateContext.

• Features around persistence have been enhanced with built-in support for redis. See Using Redis.

• A new feature helps with persist operations. See Using StateMachinePersister.

• Configuration model classes are now in a public API.

• New features in timer-based events.

• New Junction pseudostate. See Junction State.

• New Exit Point and Entry Point pseudostates. See Exit and Entry Point States.

• Configuration model verifier.

• New samples. See Security and Event Service.

• UI modeling support using Eclipse Papyrus. See Eclipse Modeling Support.

In 1.2​

Spring Statemachine 1.2 focuses on generic enhancements, better UML support, and integrations with external config repositories. It includes the following:

• Support for UML sub-machines. See Using a Sub-Machine Reference.

• A new repository abstraction that keeps machine configuration in an external repository. See Repository Support.

• New support for state actions. See State Actions.

• New transition error action concepts. See Transition Action Error Handling.

• New action error concepts. See State Action Error Handling.

• Initial work for Spring Boot support. See Spring Boot Support.

• Support for tracing and monitoring. See Monitoring a State Machine.

In 1.2.8​

Spring Statemachine 1.2.8 contains a bit more functionality than normally not seen in a point release, but these changes did not merit a fork of Spring Statemachine 1.3. It includes the following:

• JPA entity classes have changed table names. See JPA.

• A new sample. See Data Persist.

• New entity classes for persistence. See Repository Persistence.

• Transition conflict policy. See Configuring Common Settings

In 2.0​

Spring Statemachine 2.0 focuses on Spring Boot 2.x support.

In 2.0.0​

Spring Statemachine 2.0.0 includes the following:

• The format of monitoring and tracing has been changed. See Monitoring and Tracing.

• The spring-statemachine-boot module has been renamed to spring-statemachine-autoconfigure.

In 3.0​

Spring Statemachine 3.0.0 focuses on adding a Reactive support. Moving from 2.x to 3.x is introducing some breaking changes which are detailed in Reactor Migration Guide.

With 3.0.x we have deprecated all blocking methods which will get removed at some point in a future releases.

At this point most of a documentation has been changed to showcase reactive interfaces while we still keep some notes around to users still using old blocking methods.

Using Spring Statemachine

This part of the reference documentation explains the core functionality that Spring Statemachine provides to any Spring based application.

It includes the following topics:

• Statemachine Configuration describes the generic configuration support.

• State Machine ID describes the use of machine id.

• State Machine Factories describes the generic state machine factory support.

• Using Deferred Events describes the deferred event support.

• Using Scopes describes the scope support.

• Using Actions describes the actions support.

• Using Guards describes the guard support.

• Using Extended State describes the extended state support.

• Using StateContext describes the state context support.

• Triggering Transitions describes the use of triggers.

• Listening to State Machine Events describes the use of state machine listeners.

• Context Integration describes the generic Spring application context support.

• Using StateMachineAccessor describes the state machine internal accessor support.

• Using StateMachineInterceptor describes the state machine error handling support.

• State Machine Security describes the state machine security support.

• State Machine Error Handling describes the state machine interceptor support.

• State Machine Services describes the state machine service support.

• Persisting a State Machine describes the state machine persisting support.

• Spring Boot Support describes the Spring Boot support.

• Monitoring a State Machine describes the monitoring and trancing support.

• Using Distributed States describes the distributed state machine support.

• Testing Support describes the state machine testing support.

• Eclipse Modeling Support describes the state machine UML modeling support.

• Repository Support describes the state machine repository config support.

Statemachine Configuration​

One of the common tasks when using a state machine is to design its runtime configuration. This chapter focuses 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.

Using enable Annotations​

We use two familiar Spring enabler annotations to ease configuration: @EnableStateMachine and @EnableStateMachineFactory. These annotations, when placed in a @Configuration class, enable some basic functionality needed by a state machine.

You can use @EnableStateMachine when you need a configuration to create an instance of StateMachine. Usually, a @Configuration class extends adapters (EnumStateMachineConfigurerAdapter or StateMachineConfigurerAdapter), which lets you override configuration callback methods. We automatically detect whether you use these adapter classes and modify the runtime configuration logic accordingly.

You can use @EnableStateMachineFactory when you need a configuration to create an instance of a StateMachineFactory.

Configuring States​

We get into more complex configuration examples a bit later in this guide, but we first start with something simple. For most simple state machine, you can use EnumStateMachineConfigurerAdapter and define possible states and choose the initial and optional end states.

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

}

You can also use strings instead of enumerations as states and events by using StateMachineConfigurerAdapter, as shown in the next example. Most of the configuration examples ues enumerations, but, generally speaking, you can interchange strings and enumerations.

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

}

Configuring Hierarchical States​

You can define hierarchical states can by using multiple withStates() calls, where you can use parent() to indicate that these particular states are sub-states of some other state. The following example shows how to do so:

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

}

Configuring Regions​

There are no special configuration methods to mark a collection of states to be part of an orthogonal state. To put it simply, orthogonal state is created when the same hierarchical state machine has multiple sets of states, each of which has an 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. The following example shows how to define 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);
	}

}

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:

@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 different 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 define all three kinds of transitions:

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

}

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:

@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 the preceding example, we used two different types of guard configurations. 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 define 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 define an action:

@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 defined 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:

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

}

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

• We defined an action for the initial state, S1.

• We defined an entry action for state S1 and left the exit action empty.

• We defined an exit action for state S2 and left the entry action empty.

• We defined a single state action for state S2.

• We defined 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 define entry or exit actions with initial state.

State Actions​

State actions are run differently 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 flow 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 configuration that uses default the IMMEDIATE_CANCEL, which would immediately cancel a running task when its 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");
	}
}

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:

@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 specific timeout (defined 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:

@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 defined for transitions, you can define 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:

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

}

If need be, you can manually create similar logic for every action. The following example shows how to do so:

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

State Action Error Handling​

Logic similar to the logic that handles errors in state transitions is also available for entry to a state and exit from a state.

For these situations, StateConfigurer has methods called stateEntry, stateDo, and stateExit. These methods define an error action together with a normal (non-error) action. The following example shows how to use all three methods:

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

Configuring Pseudo States​

Pseudo state configuration is usually done by configuring states and transitions. Pseudo states are automatically added to state machine as states.

Initial State​

You can mark a particular state as initial state by using the initial() method. This initial action is good, for example, to initialize extended state variables. The following example shows how to use the initial() method:

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

}

Terminate State​

You can mark a particular state as being an end state by using the end() method. You can do so at most once for each individual sub-machine or region. The following example shows how to use the end() method:

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

}

State History​

You can define state history once for each individual state machine. You need to choose its state identifier and set either History.SHALLOW or History.DEEP. The following example uses History.SHALLOW:

@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 the preceding example shows, you can optionally 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, the machine has never been entered — thus, no history would be available. If a default state transition is not defined, then normal entry into a region is done. This default transition is also used if a machine’s history is a final state.

Choice State​

Choice needs to be defined in both states and transitions to work properly. You can mark a particular state as being a choice state by using the choice() method. This state needs to match source state when a transition is configured for this choice.

You can configure a transition by using withChoice(), where you define source state and a first/then/last structure, which is equivalent to a normal if/elseif/else. With first and then, you can specify a guard just as you would use a condition with if/elseif clauses.

A transition needs to be able to exist, so you must make sure to use last. Otherwise, the configuration is ill-formed. The following example shows how to define a choice state:

@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 run with both incoming and outgoing transitions of a choice pseudostate. As the following example shows, one dummy lambda action is defined that leads into a choice state and one similar dummy lambda action is defined for one outgoing transition (where it also defines 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
					});
	}
}

Junction State​

You need to define a junction in both states and transitions for it to work properly. You can mark a particular state as being a choice state by using the junction() method. This state needs to match the source state when a transition is configured for this choice.

You can configure the transition by using withJunction() where you define source state and a first/then/last structure (which is equivalent to a normal if/elseif/else). With first and then, you can specify a guard as you would use a condition with if/elseif clauses.

A transition needs to be able to exist, so you must make sure to use last. Otherwise, the configuration is ill-formed. The following example uses a junction:

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

}

Fork State​

You must define a fork in both states and transitions for it to work properly. You can mark a particular state as being a choice state by using the fork() method. This state needs to match source state when a transition is configured for this fork.

The target state needs to be a super state or an immediate state in a regions. Using a super state as a target takes all regions into initial states. Targeting individual state gives more controlled entry into regions. The following example uses a fork:

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

}