Skip to content
javahacks.dev
Microservices

Saga Pattern Java Implementation With Orchestration

Implement the saga pattern in Java: choreography versus orchestration, compensating actions, persisted state and failure handling.

7 min read
Summarize in AI
Flat illustration of a producer, a topic with partitions and consumers, with the OpenJDK, Spring Boot and Redis logos.

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

Text
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:

java
@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:

Text
OrderPlaced -> inventory reserves -> StockReserved -> payment charges -> PaymentCaptured -> shipping ...
PaymentFailed -> inventory listens and releases

There 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

  1. 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.
  2. Idempotent and retried. Compensation must be safe to run twice and must eventually succeed. Keep retrying with back off, then alert a person.
  3. Semantic locks. A pending state ("reserved", "awaiting payment") protects the data between steps.
  4. 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.

SagaDemo.javajava
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;
}
Text
failure at create-shipment
  run        reserve-stock
  run        charge-card
  failed     create-shipment rejected the request
  compensate charge-card
  compensate reserve-stock
  result     COMPENSATED

Using 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.

SQL
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.

java
@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.

Share

Keep reading

Get new posts by email

We send one email when a new post is published. No spam.

Unsubscribe in one click. No spam, ever.