Saga Pattern Java Implementation With Orchestration
Implement the saga pattern in Java: choreography versus orchestration, compensating actions, persisted state and failure handling.

Placing an order touches inventory, payment and shipping, each with its own database. Two-phase commit across them is slow, fragile and unavailable in most message-driven systems. The saga pattern trades atomicity for availability and defines how to recover.
The idea
reserve stock -> charge payment -> create shipment
| |
release stock refund payment (compensations, run in reverse on failure)Each step commits locally. If "charge payment" fails, the saga runs the compensation of every completed step: release the stock. Intermediate states are visible to other transactions, so the data model needs a "pending" state, and the business must accept that.
Orchestration
A coordinator holds the saga's state and sends commands:
@Service
class OrderSaga {
enum State { STARTED, STOCK_RESERVED, PAID, COMPLETED, CANCELLED }
private final SagaRepository sagas;
private final InventoryClient inventory;
private final PaymentClient payments;
private final ShippingClient shipping;
@Transactional
void start(Order order) {
sagas.save(new SagaRecord(order.id(), State.STARTED));
run(order.id());
}
void run(long orderId) {
SagaRecord saga = sagas.lock(orderId); // select ... for update
try {
switch (saga.state()) {
case STARTED -> { inventory.reserve(orderId); saga.to(State.STOCK_RESERVED); run(orderId); }
case STOCK_RESERVED -> { payments.charge(orderId); saga.to(State.PAID); run(orderId); }
case PAID -> { shipping.create(orderId); saga.to(State.COMPLETED); }
default -> { }
}
} catch (BusinessFailure e) {
compensate(saga);
}
}
void compensate(SagaRecord saga) {
if (saga.reached(State.PAID)) payments.refund(saga.orderId());
if (saga.reached(State.STOCK_RESERVED)) inventory.release(saga.orderId());
saga.to(State.CANCELLED);
}
}The state is persisted after each step, so a restart continues from the last committed state. Calls to other services use idempotent commands keyed by the order id, since a retry after a timeout must not charge twice, using the techniques in idempotency keys. In production the calls go through a message broker, with a reply handler advancing the state.
Choreography
Each service reacts to events and publishes its own:
OrderPlaced -> inventory reserves -> StockReserved -> payment charges -> PaymentCaptured -> shipping ...
PaymentFailed -> inventory listens and releasesThere is no central code, so no single point of failure, and the flow is spread across services, which makes it hard to follow and to change. It suits two or three steps. Beyond that, orchestration gives one place to read the process and to see where each instance is. Event handling needs the safeguards in duplicate and out-of-order messages.
Rules for compensation
- Business-level undo. Refund, release, cancel. Not every step can be compensated (an email cannot be unsent), so order the steps with the irreversible ones last.
- Idempotent and retried. Compensation must be safe to run twice and must eventually succeed. Keep retrying with back off, then alert a person.
- Semantic locks. A pending state ("reserved", "awaiting payment") protects the data between steps.
- Timeouts. A saga waiting for a reply forever blocks resources. Set deadlines and compensate on expiry.
Atomic publish with the outbox
A step must update its database and publish a message atomically. Without that, a crash between them loses the message. The transactional outbox writes the event to a table in the same transaction and a relay publishes it, an approach that lives alongside event sourcing.
Tools
Workflow engines such as Temporal run the orchestration with durable state and retries, so you write the saga as ordinary code. Axon provides saga support, see Axon, and Camunda and Spring State Machine are other options.
A saga you can run and watch compensate
The orchestration snippet above depends on a framework. The mechanism itself fits in sixty lines of plain Java, and running it shows the property that matters: when step *n* fails, the steps before it are undone in reverse order. The program runs the same three-step saga four times, failing a different step each time.
interface Step {
String name();
void run(Map<String, String> ctx);
void compensate(Map<String, String> ctx);
}
static boolean execute(List<Step> steps) {
Deque<Step> completed = new ArrayDeque<>();
Map<String, String> ctx = new LinkedHashMap<>();
for (Step step : steps) {
try {
step.run(ctx);
completed.push(step);
} catch (RuntimeException e) {
System.out.println(" failed " + e.getMessage());
while (!completed.isEmpty()) completed.pop().compensate(ctx);
return false;
}
}
return true;
}failure at create-shipment
run reserve-stock
run charge-card
failed create-shipment rejected the request
compensate charge-card
compensate reserve-stock
result COMPENSATEDUsing a Deque as a stack gives the reverse order for free. Run the full program and the other three cases show the same logic: a failure at reserve-stock compensates nothing, since nothing completed, and a failure at charge-card compensates only the reservation. The failing step itself is never compensated here, because it did not complete. That is a decision, not a law: a step that can fail halfway, such as a payment call that times out, needs a compensation that is safe to run whether or not the charge happened.
Steps fail in the middle, so compensations must be idempotent
The in-memory demo cannot lose a message. A real saga can. The orchestrator may crash after calling charge-card and before recording the result, and on restart it asks again. Every forward step and every compensation therefore has to tolerate being called twice. The standard approach is to give each saga instance an identifier and pass sagaId plus the step name as the idempotency key to the service, which stores it and replays its first answer.
CREATE TABLE saga_instance (
id UUID PRIMARY KEY,
type VARCHAR(60) NOT NULL,
state VARCHAR(20) NOT NULL, -- RUNNING, COMPENSATING, COMPLETED, COMPENSATED, FAILED
step INT NOT NULL, -- index of the next step to run or undo
payload JSONB NOT NULL,
updated_at TIMESTAMPTZ NOT NULL
);
CREATE INDEX saga_stuck ON saga_instance (state, updated_at);The orchestrator updates this row in the same local transaction as it records the command it sends (the outbox pattern from the section above). A scheduled job then looks for rows in RUNNING or COMPENSATING whose updated_at is older than a threshold and resumes them. A saga with no such recovery works until the first crash, and the crash is when it is needed.
Isolation is the cost you pay
A database transaction hides intermediate states. A saga exposes them: between reserve-stock and charge-card, other requests can see the reservation. Three habits keep that from producing wrong answers. Model the intermediate state explicitly, with an order status PENDING that other code treats as not yet real. Use semantic locks, such as a reserved_by_saga column that prevents a second saga from taking the same stock. And order steps so the one that cannot be undone, such as sending an email or shipping, goes last, after everything that can still fail.
Test failure at every step
The demo loop is the test: for each step index, inject a failure and assert the end state. Do the same against the real services in an integration test, and add the crash case by stopping the orchestrator between steps and restarting it.
@ParameterizedTest
@ValueSource(ints = {0, 1, 2})
void compensatesEverythingBeforeTheFailure(int failingStep) {
var steps = stepsFailingAt(failingStep);
assertThat(saga.execute(steps)).isFalse();
assertThat(stock.reserved("A-1")).isZero();
assertThat(payments.charged("order-1")).isZero();
}Assert on business state (stock back to zero, no charge), not only on the call sequence. The sequence can be right and the money still wrong.
What to log so a stuck saga can be diagnosed
When a customer reports an order that never arrived, the question is which step it reached and what that step answered. Log one line per transition with the saga id, the step, the direction (forward or compensating) and the outcome, and make the saga id the correlation id in every downstream call so one search shows the whole story across services. Expose the count of sagas per state as a metric and alert when COMPENSATING or RUNNING older than the threshold is nonzero. A saga that compensates is normal; one that stays in COMPENSATING for an hour means a compensation itself is failing, and that needs a person, with the payload and the failed step on hand, not another automatic retry.
Plan for the compensation that cannot succeed. A refund to a closed card, a shipment already handed to a courier: these end in a FAILED state that raises a ticket with everything needed to finish by hand. Deciding in advance who receives that ticket is part of the design, not an operational detail.
Where this does not apply
If the services share a database and the process is short, a local transaction is simpler, and a modular monolith avoids the question, see Spring Modulith. The reference is the saga pattern on microservices.io, and the original paper by Garcia-Molina and Salem defines it.


