resonate-saga-pattern-java

Resonate Saga Pattern — Java

Prerelease note. resonate-sdk-java is published on Maven Central — pin io.resonatehq:resonate-sdk-java:0.1.1. The API mirrors the Python SDK and may change before a stable 1.0. Requires Java 21+ (virtual threads, a feature generally available in Java 21). There is no Java saga example repo yet, so every code block here uses only documented SDK surface, compile-verified against 0.1.1 and cross-checked against develop/java.mdx (docs PR #230) and the SDK source.

Overview

A saga is a long-running transaction split into discrete steps, each with a compensating action. Forward steps execute top-to-bottom; on any failure, completed compensations run bottom-to-top. Because the whole workflow body re-runs on resume, the completed list is reconstructed deterministically on replay — each ctx.run short-circuits its settled durable promise in the same order, so the list is rebuilt identically before reaching the point of failure.

Java's exception model makes the saga read more like the TypeScript/Python idiom than Go's: the forward path lives in a try block, and a single catch triggers compensation — there is no per-step (T, error) check to thread by hand.

For the language-agnostic mental model — choreography vs orchestration, idempotency requirements, when not to use sagas — see resonate-saga-pattern-typescript.

When to use

• Multi-step workflow where intermediate state is visible to other systems between steps
• Each step is individually compensable (inventory hold, payment charge, shipment create)
• You need "all or nothing" consistency without a distributed 2PC transaction
• Steps span services and may take seconds to minutes each
• Compensation logic exists and is idempotent for every committed step

Basic shape

package io.resonatehq.examples.saga;

import io.resonatehq.resonate.Context;
import io.resonatehq.resonate.Context.Opts;
import io.resonatehq.resonate.Handle.ResonateHandle;
import io.resonatehq.resonate.Resonate;
import io.resonatehq.resonate.Retry.Exponential;
import java.util.ArrayList;
import java.util.List;

public final class Saga {
    private Saga() {}

    /** The forward steps that can be committed; the enum + switch gives closed-set compensation dispatch. */
    public enum Step { INVENTORY, PAYMENT, SHIPMENT }

    public record SagaResult(String status, String orderId, List<String> compensated) {}

    /**
     * The saga orchestrator. Forward steps run in sequence inside a try; the first failure throws,
     * and the catch runs compensations in reverse. Each ctx.run is a durable checkpoint, so a
     * crash mid-saga resumes from the last settled step — committed steps do not re-execute.
     */
    public static SagaResult placeOrder(Context ctx, String orderId) {
        List<Step> completed = new ArrayList<>();
        try {
            ctx.run(Saga::reserveInventory, orderId).await();
            completed.add(Step.INVENTORY);

            ctx.run(Saga::chargePayment, orderId).await();
            completed.add(Step.PAYMENT);

            ctx.run(Saga::createShipment, orderId).await();
            completed.add(Step.SHIPMENT);

            return new SagaResult("success", orderId, List.of());
        } catch (Exception forwardErr) {
            // await() sneaky-throws the rejection, which may be unchecked OR a sneakily-rethrown
            // checked exception — catch Exception so no failure path slips past the compensator.
            return compensateAll(ctx, orderId, completed);
        }
    }

    /** Iterate completed steps in reverse, running each compensation as its own durable ctx.run. */
    public static SagaResult compensateAll(Context ctx, String orderId, List<Step> completed) {
        List<String> names = new ArrayList<>();
        for (int i = completed.size() - 1; i >= 0; i--) {
            Step step = completed.get(i);
            // A compensation that exhausts retries is a real inconsistency — give it a generous policy.
            ctx.options(new Opts().withRetryPolicy(new Exponential(1, 5, 2, 30)))
                    .run(Saga::compensate, step, orderId)
                    .await();
            names.add(step.name());
        }
        return new SagaResult("failed", orderId, names);
    }

    /** Dispatch to the correct undo action via a switch. Each branch must be idempotent. */
    public static String compensate(Context ctx, Step step, String orderId) {
        return switch (step) {
            case SHIPMENT -> "shipment-cancelled:" + orderId;   // cancelShipment(orderId)
            case PAYMENT -> "payment-refunded:" + orderId;      // refundPayment(orderId)
            case INVENTORY -> "inventory-released:" + orderId;  // releaseInventory(orderId)
        };
    }

    // Forward leaf stubs — replace with real service calls.
    public static String reserveInventory(Context ctx, String orderId) {
        return "reserved:" + orderId;
    }

    public static String chargePayment(Context ctx, String orderId) {
        return "charged:" + orderId;
    }

    public static String createShipment(Context ctx, String orderId) {
        // Simulate a transient failure to trigger compensation.
        throw new IllegalStateException("shipment service unavailable");
    }

    public static void main(String[] args) {
        Resonate r = Resonate.builder().url("http://localhost:8001").build();
        r.register(Saga::placeOrder);
        try {
            ResonateHandle<SagaResult> handle = r.run("order-1", Saga::placeOrder, "order-1");
            System.out.println(handle.result());
        } finally {
            r.stop();
        }
    }
}