Spring Statemachine - Quick Reference
Full Reference: See advanced.md for @WithStateMachine annotation, hierarchical states, choice pseudostates, timer transitions, listeners, persistence, and testing.
Deep Knowledge: Use mcp__documentation__fetch_docs with technology: spring-statemachine for comprehensive documentation.
Dependencies
<!-- Spring Statemachine 4.0+ for Spring Boot 3.x -->
<dependency>
<groupId>org.springframework.statemachine</groupId>
<artifactId>spring-statemachine-starter</artifactId>
<version>4.0.0</version>
</dependency>
<!-- For persistence -->
<dependency>
<groupId>org.springframework.statemachine</groupId>
<artifactId>spring-statemachine-data-jpa</artifactId>
<version>4.0.0</version>
</dependency>
Core Concepts
┌─────────────────────────────────────────────────────────────┐
│ State Machine │
│ │
│ ┌──────────┐ EVENT_A ┌──────────┐ │
│ │ STATE_1 │ ─────────────▶ │ STATE_2 │ │
│ │ (initial)│ │ │ │
│ └──────────┘ └────┬─────┘ │
│ │ │
│ EVENT_B │
│ │ │
│ ▼ │
│ ┌──────────┐ │
│ │ STATE_3 │ │
│ │ (final) │ │
│ └──────────┘ │
└─────────────────────────────────────────────────────────────┘
Basic Configuration
States and Events
public enum OrderStates {
CREATED,
PENDING_PAYMENT,
PAID,
PROCESSING,
SHIPPED,
DELIVERED,
CANCELLED,
REFUNDED
}
public enum OrderEvents {
SUBMIT,
PAY,
PROCESS,
SHIP,
DELIVER,
CANCEL,
REFUND
}
State Machine Configuration
@Configuration
@EnableStateMachineFactory
public class OrderStateMachineConfig
extends EnumStateMachineConfigurerAdapter<OrderStates, OrderEvents> {
@Override
public void configure(StateMachineStateConfigurer<OrderStates, OrderEvents> states)
throws Exception {
states
.withStates()
.initial(OrderStates.CREATED)
.state(OrderStates.PENDING_PAYMENT)
.state(OrderStates.PAID)
.state(OrderStates.PROCESSING)
.state(OrderStates.SHIPPED)
.end(OrderStates.DELIVERED)
.end(OrderStates.CANCELLED)
.end(OrderStates.REFUNDED);
}
@Override
public void configure(StateMachineTransitionConfigurer<OrderStates, OrderEvents> transitions)
throws Exception {
transitions
.withExternal()
.source(OrderStates.CREATED)
.target(OrderStates.PENDING_PAYMENT)
.event(OrderEvents.SUBMIT)
.and()
.withExternal()
.source(OrderStates.PENDING_PAYMENT)
.target(OrderStates.PAID)
.event(OrderEvents.PAY)
.guard(paymentValidGuard())
.action(paymentAction())
.and()
.withExternal()
.source(OrderStates.PAID)
.target(OrderStates.PROCESSING)
.event(OrderEvents.PROCESS)
.and()
.withExternal()
.source(OrderStates.PROCESSING)
.target(OrderStates.SHIPPED)
.event(OrderEvents.SHIP)
.action(shipAction())
.and()
.withExternal()
.source(OrderStates.SHIPPED)
.target(OrderStates.DELIVERED)
.event(OrderEvents.DELIVER)
.and()
// Cancel from multiple states
.withExternal()
.source(OrderStates.CREATED)
.target(OrderStates.CANCELLED)
.event(OrderEvents.CANCEL)
.and()
.withExternal()
.source(OrderStates.PENDING_PAYMENT)
.target(OrderStates.CANCELLED)
.event(OrderEvents.CANCEL);
}
}
Guards and Actions
Guards (Conditions)
@Configuration
public class OrderGuards {
@Bean
public Guard<OrderStates, OrderEvents> paymentValidGuard() {
return context -> {
Order order = (Order) context.getExtendedState()
.getVariables().get("order");
PaymentInfo payment = (PaymentInfo) context.getMessage()
.getHeaders().get("payment");
return payment != null &&
payment.getAmount().compareTo(order.getTotal()) >= 0;
};
}
@Bean
public Guard<OrderStates, OrderEvents> refundEligibleGuard() {
return context -> {
Order order = (Order) context.getExtendedState()
.getVariables().get("order");
LocalDateTime deliveredAt = order.getDeliveredAt();
// Refund within 30 days
return deliveredAt != null &&
deliveredAt.plusDays(30).isAfter(LocalDateTime.now());
};
}
}
Actions
@Configuration
public class OrderActions {
@Bean
public Action<OrderStates, OrderEvents> paymentAction() {
return context -> {
Order order = (Order) context.getExtendedState()
.getVariables().get("order");
PaymentInfo payment = (PaymentInfo) context.getMessage()
.getHeaders().get("payment");
order.setPaymentId(payment.getTransactionId());
order.setPaidAt(LocalDateTime.now());
orderRepository.save(order);
log.info("Payment processed for order: {}", order.getId());
};
}
@Bean
public Action<OrderStates, OrderEvents> shipAction() {
return context -> {
Order order = (Order) context.getExtendedState()
.getVariables().get("order");
String trackingNumber = shippingService.createShipment(order);
order.setTrackingNumber(trackingNumber);
order.setShippedAt(LocalDateTime.now());
orderRepository.save(order);
notificationService.sendShippingNotification(order);
};
}
// Error action
@Bean
public Action<OrderStates, OrderEvents> errorAction() {
return context -> {
Exception exception = context.getException();
log.error("State machine error: {}", exception.getMessage());
};
}
}
State Machine Service
@Service
@RequiredArgsConstructor
@Slf4j
public class OrderStateMachineService {
private final StateMachineFactory<OrderStates, OrderEvents> factory;
private final OrderRepository orderRepository;
public void processEvent(Long orderId, OrderEvents event, Map<String, Object> headers) {
Order order = orderRepository.findById(orderId)
.orElseThrow(() -> new OrderNotFoundException(orderId));
StateMachine<OrderStates, OrderEvents> sm = build(order);
Message<OrderEvents> message = MessageBuilder
.withPayload(event)
.copyHeaders(headers)
.setHeader("orderId", orderId)
.build();
// Reactive event sending (Spring Statemachine 4.0+)
sm.sendEvent(Mono.just(message))
.doOnComplete(() -> log.info("Event {} processed for order {}", event, orderId))
.doOnError(e -> log.error("Error processing event: {}", e.getMessage()))
.subscribe();
}
private StateMachine<OrderStates, OrderEvents> build(Order order) {
StateMachine<OrderStates, OrderEvents> sm = factory.getStateMachine(
order.getId().toString()
);
sm.stopReactively().block();
sm.getStateMachineAccessor()
.doWithAllRegions(accessor -> {
accessor.resetStateMachineReactively(
new DefaultStateMachineContext<>(
order.getState(), null, null, null
)
).block();
});
sm.getExtendedState().getVariables().put("order", order);
sm.startReactively().block();
return sm;
}
public boolean canTransition(Long orderId, OrderEvents event) {
Order order = orderRepository.findById(orderId).orElseThrow();
StateMachine<OrderStates, OrderEvents> sm = build(order);
return sm.getTransitions().stream()
.anyMatch(t -> t.getSource().getId() == order.getState() &&
t.getTrigger().getEvent() == event);
}
}
Best Practices
| Do |
Don't |
| Define clear states and events |
Use generic state names |
| Use guards for validation |
Put business logic in transitions |
| Persist state machine state |
Keep state only in memory |
| Handle all edge cases |
Assume happy path only |
| Use listeners for monitoring |
Ignore state changes |
Production Checklist
When NOT to Use This Skill
- Simple status fields - Use enum with database column
- Complex orchestration - Use Spring Integration or Camunda BPM
- Business rules - Use Drools or similar rules engine
- Event-driven sagas - Consider Spring Cloud Stream
Anti-Patterns
| Anti-Pattern |
Problem |
Solution |
| State in memory only |
Lost on restart |
Use JPA persistence |
| Complex logic in guards |
Hard to test |
Extract to services |
| Missing error actions |
Silent failures |
Add error handling actions |
| Single machine instance |
Concurrency issues |
Use factory pattern |
| No state validation |
Invalid transitions |
Implement guards properly |
Quick Troubleshooting
| Problem |
Diagnostic |
Fix |
| Event not accepted |
Check current state |
Verify transition exists |
| Guard always false |
Debug guard logic |
Log guard evaluation |
| Action not executed |
Check transition config |
Verify action is attached |
| State not persisted |
Check persister config |
Configure JPA persister |
| Machine not starting |
Check initial state |
Verify initial() configured |
Reference Documentation
claude-dev-suite