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