Problem statement
Implement the event chain that drives an order through its lifecycle: each stage handler advances the order exactly one step, guards against re-delivered events, and rejects illegal transitions.
Requirements
Every stage handler
Each handler owns one stage: OrderCreatedHandler owns CREATED, OrderPaidHandler owns PAID, and OrderShippedHandler owns SHIPPED. Every handler must:
- Receive its stage event whenever one is published, and handle it in the background on the provided chain executor, never on the thread that served the HTTP request; every recorded stage execution runs on a thread whose name starts with chain-
- First consult StageExecutionLog.hasRun with the order id and the handler's own stage; when that stage has already been handled for that order, finish immediately and silently: no status change, no new stage record, no further event, and in particular no illegal transition warning, however many times the already-handled event is delivered again
- Otherwise load the order and compare its status to the handler's own stage; when they differ, the event is an illegal transition: log a warning through the handler's logger reading exactly "Illegal transition " followed by the handler's stage, then " for order ", then the order id (for example "Illegal transition SHIPPED for order 1"), and finish without changing the status, without recording any stage execution, and without publishing anything
- Otherwise handle the stage as described for the handler below, recording exactly one stage execution through StageExecutionLog.record with the order id and the handler's own stage
- Advance the one existing order row in place; the chain never creates or removes orders
- Track everything per order: events for one order never change another order's status or records, a re-delivered event on one order never disturbs another order's chain, and a rejected event on one order never blocks another order's chain
OrderCreatedHandler
- Set the order's status to PAID and save it, record the CREATED stage, then publish an OrderPaidEvent carrying the same order id
OrderPaidHandler
- Set the order's status to SHIPPED and save it, record the PAID stage, then publish an OrderShippedEvent carrying the same order id
OrderShippedHandler
- Record the SHIPPED stage and publish nothing; the chain for that order is complete and its status stays SHIPPED
The full chain
- Creating an order runs the chain to completion: the order ends with status SHIPPED and exactly one StageExecution row per stage (CREATED, PAID, and SHIPPED; three rows in total)
- The chain advances one step at a time and in order: the stages are recorded in the order CREATED, PAID, SHIPPED, and the recorded execution times never move backwards along the chain
- The chain can be entered at any stage: when the event matching an order's current status arrives, the remaining handlers advance the order the rest of the way, and each handler contributes only its own stage row
- An order that was rejected for an illegal transition is not stuck: when the event matching its actual stage arrives, the chain still runs to completion
Provided endpoints
- POST /orders saves a new order with status CREATED and publishes the OrderCreatedEvent that starts the chain
- POST /orders/{id}/events/{stage} re-publishes the given stage event for that order, exactly as if it were delivered again
- GET /orders/{id} returns the order; an unknown id returns 404 Not Found with the error message "Order not found with id: " followed by the requested id
- GET /orders/{id}/stages returns the recorded stage executions of that order
- One demonstration order with status CREATED is seeded at startup, with no event published for it
Sample Requests & Responses
Expand to view details on sample requests and responses.
POST /orders
Response (201 Created):
{
"id": 2,
"status": "CREATED"
}
GET /orders/2 (a moment later, after the chain has run)
Response (200 OK):
{
"id": 2,
"status": "SHIPPED"
}
GET /orders/2/stages
Response (200 OK):
[
{
"id": 1,
"orderId": 2,
"stage": "CREATED",
"executedAt": "2026-08-05T23:43:27.823068"
},
{
"id": 2,
"orderId": 2,
"stage": "PAID",
"executedAt": "2026-08-05T23:43:27.826008"
},
{
"id": 3,
"orderId": 2,
"stage": "SHIPPED",
"executedAt": "2026-08-05T23:43:27.827214"
}
]
POST /orders/2/events/PAID (re-delivering an already-handled event)
Response (202 Accepted):
{
"orderId": 2,
"stage": "PAID"
}
GET /orders/2/stages (unchanged: the re-delivered event terminated silently)
Response (200 OK):
[
{
"id": 1,
"orderId": 2,
"stage": "CREATED",
"executedAt": "2026-08-05T23:43:27.823068"
},
{
"id": 2,
"orderId": 2,
"stage": "PAID",
"executedAt": "2026-08-05T23:43:27.826008"
},
{
"id": 3,
"orderId": 2,
"stage": "SHIPPED",
"executedAt": "2026-08-05T23:43:27.827214"
}
]
POST /orders/1/events/SHIPPED (order 1 is the seeded demonstration order, still CREATED)
Response (202 Accepted):
{
"orderId": 1,
"stage": "SHIPPED"
}
Application log:
WARN 80424 --- [ chain-1] c.s.api.listener.OrderShippedHandler : Illegal transition SHIPPED for order 1
GET /orders/1 (unchanged: the illegal transition was rejected)
Response (200 OK):
{
"id": 1,
"status": "CREATED"
}
GET /orders/1/stages
Response (200 OK):
[]
GET /orders/99
Response (404 Not Found):
{
"error": "Order not found with id: 99",
"timestamp": "2026-08-05T23:43:30.913196",
"path": "/orders/99"
}
