Building a Non Blocking State Machine in Spring Boot (Java 21+)

June 7, 2025 · 6 min read

Developer

Modern backend systems demand reactive, scalable, and maintainable architectures especially for event driven workflows like document processing, user provisioning, or IoT orchestration. In this blog post, we’ll explore how to build a non blocking, production ready Spring StateMachine using Java 21, Spring Boot 3.3+, and Project Reactor. We'll follow architectural standards, observability best practices, and layer in a moderately complex real world example.

✨ Why Non-Blocking State Machines Matter

A State Machine models the behavior of a system by defining possible states, events, and transitions. Using a non blocking (reactive) implementation brings huge benefits:

Improved scalability: Threads aren’t blocked, allowing efficient resource usage
Better responsiveness: Especially under high concurrency or I/O load
Clean workflow orchestration: Explicitly model and track business state transitions
Excellent integration: With Kafka, WebFlux, and Micrometer

🎓 Theory Refresher: What is a Finite State Machine (FSM)?

A Finite State Machine (FSM) consists of:

A finite set of states
A set of events that trigger transitions
Transition functions that define valid state changes
Optional entry/exit actions per state

FSMs are ideal for modeling lifecycle workflows like:

Order processing
User registration
Document approval
IoT device management

In Spring StateMachine, FSM concepts are implemented with strong typing, clear configuration, and extensible action/guard hooks.

🔄 Architectural Patterns & Principles

Below is a detailed table of architectural best practices and how they apply to Spring StateMachine:

Principle	Explanation
Separation of Concerns	Keep states, transitions, and business logic (actions/guards) clearly separated
Single Responsibility	Each machine or service should handle a specific workflow
Event-driven Design	Transitions are triggered by events from Kafka, WebFlux, or internal logic
Observability	Track metrics, transitions, and errors using Prometheus + Micrometer
Resilience	Use fallback states, retries, and guards to handle failures
Configuration over Convention	Define states, transitions, and actions declaratively using DSL
External Transitions Emphasis	Prefer external transitions with actions for full control and traceability
Stateless Machines	Machines don’t persist state internally; use Redis or DB externally
Separation of Actions/Guards	Actions and guards should be defined as Spring beans or components

🧱 Configuration Example

State & Event Enums

public enum DocState {
    NEW, VALIDATING, PROCESSING, REVIEW_PENDING, APPROVED, FAILED
}

public enum DocEvent {
    VALIDATE, PROCESS, SEND_FOR_REVIEW, APPROVE, FAIL
}

State Machine Configuration

First, define separate Action classes for clarity and reuse:

@Component
public class ValidateAction implements Action<DocState, DocEvent> {
    public void execute(StateContext<DocState, DocEvent> context) {
        System.out.println("[Action] Validating document " + context.getStateMachine().getId());
    }
}

@Component
public class ProcessAction implements Action<DocState, DocEvent> {
    public void execute(StateContext<DocState, DocEvent> context) {
        System.out.println("[Action] Processing document " + context.getStateMachine().getId());
    }
}

@Component
public class ApproveAction implements Action<DocState, DocEvent> {
    public void execute(StateContext<DocState, DocEvent> context) {
        System.out.println("[Action] Approving document " + context.getStateMachine().getId());
    }
}

Now, wire them into your state machine configuration:java @Configuration

@Configuration
@EnableStateMachineFactory
@RequiredArgsConstructor
public class DocumentStateMachineConfig extends EnumStateMachineConfigurerAdapter<DocState, DocEvent> {
    private final ValidateAction validateAction;
    private final ProcessAction processAction;
    private final ApproveAction approveAction;

    @Override
    public void configure(StateMachineStateConfigurer<DocState, DocEvent> states) throws Exception {
        states.withStates()
                .initial(DocState.NEW)
                .state(DocState.VALIDATING)
                .state(DocState.PROCESSING)
                .state(DocState.REVIEW_PENDING)
                .end(DocState.APPROVED)
                .end(DocState.FAILED);
    }

    @Override
    public void configure(StateMachineTransitionConfigurer<DocState, DocEvent> transitions) throws Exception {
        transitions.withExternal().source(DocState.NEW).target(DocState.VALIDATING).event(DocEvent.VALIDATE).action(validateAction)
                .and()
                .withExternal().source(DocState.VALIDATING).target(DocState.PROCESSING).event(DocEvent.PROCESS).action(processAction)
                .and()
                .withExternal().source(DocState.PROCESSING).target(DocState.REVIEW_PENDING).event(DocEvent.SEND_FOR_REVIEW)
                .and()
                .withExternal().source(DocState.REVIEW_PENDING).target(DocState.APPROVED).event(DocEvent.APPROVE).action(approveAction)
                .and()
                .withExternal().source(DocState.VALIDATING).target(DocState.FAILED).event(DocEvent.FAIL)
                .and()
                .withExternal().source(DocState.PROCESSING).target(DocState.FAILED).event(DocEvent.FAIL);
    }

    private Action<DocState, DocEvent> log(String message) {
        return context -> System.out.printf("[Action] %s for doc: %s\n", message, context.getStateMachine().getId());
    }
}

⚙️ Running a Reactive State Machine

@Service
public class DocumentWorkflowService {

    private final StateMachineFactory<DocState, DocEvent> factory;

    public DocumentWorkflowService(StateMachineFactory<DocState, DocEvent> factory) {
        this.factory = factory;
    }

    public void runWorkflow(String docId) {
        var sm = factory.getStateMachine(docId);
        sm.startReactively()
                .then(sm.sendEvent(Mono.just(MessageBuilder.withPayload(DocEvent.VALIDATE).build())))
                .then(sm.sendEvent(Mono.just(MessageBuilder.withPayload(DocEvent.PROCESS).build())))
                .then(sm.sendEvent(Mono.just(MessageBuilder.withPayload(DocEvent.SEND_FOR_REVIEW).build())))
                .then(sm.sendEvent(Mono.just(MessageBuilder.withPayload(DocEvent.APPROVE).build())))
                .then(sm.stopReactively())
                .subscribe();
    }
}

❗ Handling Errors in Actions and Ensuring Transitions

In a robust state machine, handling exceptions within Action classes is critical to avoid broken workflows or silent failures.

🔒 Safe Action Execution Pattern

You should catch exceptions within your Action class to prevent the state machine from halting unexpectedly:

@Component
public class ValidateAction implements Action<DocState, DocEvent> {
    public void execute(StateContext<DocState, DocEvent> context) {
        try {
            // Perform validation logic
            System.out.println("[Action] Validating " + context.getStateMachine().getId());
        } catch (Exception ex) {
            context.getExtendedState().getVariables().put("error", ex.getMessage());
            context.getStateMachine().sendEvent(DocEvent.FAIL);  // Trigger failure transition
        }
    }
}

🚨 Configure Error Transitions

Make sure to define fallback transitions that catch these programmatic failures and move the machine to a safe state:

.withExternal()
  .source(DocState.VALIDATING)
  .target(DocState.FAILED)
  .event(DocEvent.FAIL)
  .action(errorHandler)

Define an optional errorHandler to log or notify:

@Component
public class ErrorHandler implements Action<DocState, DocEvent> {
    public void execute(StateContext<DocState, DocEvent> context) {
        String reason = (String) context.getExtendedState().getVariables().get("error");
        System.err.println("Transitioned to FAILED due to: " + reason);
    }
}

🛡️ Global Error Listener (Optional)

Catch unhandled exceptions:

@Override
public void configure(StateMachineConfigurationConfigurer<DocState, DocEvent> config) throws Exception {
    config.withConfiguration()
            .listener(new StateMachineListenerAdapter<>() {
                @Override
                public void stateMachineError(StateMachine<DocState, DocEvent> stateMachine, Exception exception) {
                    log.error("StateMachine encountered an error: ", exception);
                }
            });
}

📊 Observability and Kafka Integration

Metric Listener with Micrometer

@Bean
public StateMachineListener<DocState, DocEvent> metricListener(MeterRegistry registry) {
    return new StateMachineListenerAdapter<>() {
        @Override
        public void stateChanged(State<DocState, DocEvent> from, State<DocState, DocEvent> to) {
            registry.counter("doc_state_transition", "from", from.getId().name(), "to", to.getId().name()).increment();
        }
    };
}

Kafka Event Trigger

@KafkaListener(topics = "doc.events")
public void handleEvent(String json) {
    DocEvent event = parse(json);
    String docId = extractId(json);

    var sm = factory.getStateMachine(docId);
    sm.startReactively()
            .then(sm.sendEvent(Mono.just(MessageBuilder.withPayload(event).build())))
            .subscribe();
}

🖼️ DOT Export for Visualization

To visualize your state machine, use the StateMachineSerialisationUtils utility provided by Spring StateMachine. Make sure you include the dependency:

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

Then export the DOT file like so:

String dot = StateMachineSerialisationUtils.toDot(stateMachine);
Files.writeString(Path.of("statemachine.dot"), dot);

Render via:

dot -Tpng statemachine.dot -o statemachine.png

📏 Additional Standards and Extensions

🧩 State Persistence with Redis or DB

@Bean
public StateMachinePersister<DocState, DocEvent, String> persister() {
    return new InMemoryStateMachinePersister<>(); // Replace with Redis or JPA-based implementation
}

Use:

persister.persist(stateMachine, docId);
persister.restore(stateMachine, docId);

📉 Real Time Dashboards (Prometheus + Grafana)

sum by (from, to) (rate(doc_state_transition[5m]))

🧪 Testing with Spring Test Plan

@Test
void shouldTransitionFromNewToValidating() throws Exception {
    StateMachine<DocState, DocEvent> machine = factory.getStateMachine();
    machine.startReactively().block();
    boolean result = machine.sendEvent(Mono.just(MessageBuilder.withPayload(DocEvent.VALIDATE).build())).block();
    assertThat(machine.getState().getId()).isEqualTo(DocState.VALIDATING);
}

📐 FAQ: Best Practices

Why emphasize external transitions? Easier to test and debug.

Why stateless machines? More scalable and testable.

Separate actions/guards? Yes — improves traceability and reuse.

Visualize workflows? Use DOT export + Graphviz.

Manage large flows? Use nested or orthogonal states.

✨ Why Non-Blocking State Machines Matter​

🎓 Theory Refresher: What is a Finite State Machine (FSM)?​

A Finite State Machine (FSM) consists of:​

FSMs are ideal for modeling lifecycle workflows like:​

🔄 Architectural Patterns & Principles​

🧱 Configuration Example​

State & Event Enums​

State Machine Configuration​

⚙️ Running a Reactive State Machine​

❗ Handling Errors in Actions and Ensuring Transitions​

🔒 Safe Action Execution Pattern​

🚨 Configure Error Transitions​

🛡️ Global Error Listener (Optional)​

📊 Observability and Kafka Integration​

Metric Listener with Micrometer​

Kafka Event Trigger​

🖼️ DOT Export for Visualization​

📏 Additional Standards and Extensions​

🧩 State Persistence with Redis or DB​

📉 Real Time Dashboards (Prometheus + Grafana)​

🧪 Testing with Spring Test Plan​

📐 FAQ: Best Practices​