Quick Start with Spring StateMachine: Build a Simple Order Workflow

Spring StateMachine is a relatively new framework for Spring developers, with its third release (1.2.0) adding automatic configuration for Spring Boot. The article uses this release to demonstrate a quick‑start example that models a simple order process.

Quick‑Start Example

The example assumes an order lifecycle with three actions: order creation, payment, and receipt.

Step 1: Create a Spring Boot Project

Generate a basic Spring Boot application and add the spring-statemachine-core dependency to pom.xml.

Step 2: Define State and Event Enums

Based on the order scenario, define the following enums:

public enum States { UNPAID, WAITING_FOR_RECEIVE, DONE }
public enum Events { PAY, RECEIVE }

Step 3: Configure the State Machine

Create a configuration class and enable the framework with @EnableStateMachine. The class contains three configuration methods:

configure(StateMachineStateConfigurer<States, Events> states)

– declares all states and sets the initial state ( UNPAID).

configure(StateMachineTransitionConfigurer<States, Events> transitions)

– defines transitions: PAY moves from UNPAID to WAITING_FOR_RECEIVE, and RECEIVE moves from WAITING_FOR_RECEIVE to DONE.

configure(StateMachineConfigurationConfigurer<States, Events> config)

– registers a StateMachineListener to handle transition events.

Step 4: Implement the Listener

The listener is created via StateMachineListener<States, Events> listener(). In the example it simply prints messages for each transition, but in real applications it can contain business logic. The listener can also be defined as a separate bean and injected.

Step 5: Create the Application Main Class

In the run method, start the state machine, then fire sendEvent(Events.PAY) and sendEvent(Events.RECEIVE). The console output shows the state changes handled by the listener.

Summary of the Process

Define state and event enums.

Configure all states and the initial state.

Configure state transitions.

Register a listener to process transition events.

Annotation‑Based Listener

Spring StateMachine also supports configuring the listener via annotations, which removes the need for explicit if checks and makes the code more concise and readable. The annotated version achieves the same functionality as the manual listener shown earlier.