resonate-basic-durable-world-usage-java

Resonate Basic Durable World Usage — 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+ — the SDK uses virtual threads, a feature generally available in Java 21. Every code block here is compile-verified against 0.1.1 with a Java 21 toolchain, and cross-checked against the resonatehq-examples/*-java repos and develop/java.mdx (docs PR #230).

Overview

A durable function in Java is an ordinary static method whose first parameter is a Context, followed by up to five JSON-serializable application arguments. Every Context method returns a ResonateFuture right away — the future object is allocated immediately, while the durable promise behind it is created on the server (inline in local mode, a network round-trip against a real server). You call future.await() to read the result. If the awaited promise is still pending, await suspends the workflow and re-enters it when the promise settles — and suspension is durable, so any worker (including this one after a restart) can resume the continuation.

This skill covers the Context API surface used inside durable functions. The ephemeral-world counterpart (the builder, register, top-level run/rpc/get) lives in resonate-basic-ephemeral-world-usage-java.

When to use

Use this skill whenever you are writing the body of a Java method that will be registered with r.register or handed as a method reference to ctx.run. The moment you touch ctx.run, ctx.rpc, ctx.sleep, ctx.promise, or ctx.detached, this skill applies.

Function shape

A durable function takes a Context first, then up to five args. Both leaf functions and workflows share the shape — a "workflow" is a function that itself performs durable ops:

import io.resonatehq.resonate.Context;

public final class Greeter {
    private Greeter() {}

    // A leaf: no durable op, just computes a value.
    public static String formatGreeting(Context ctx, String name) {
        return "hello, " + name + "!";
    }

    // A workflow: orchestrates sub-tasks via the Context.
    public static String greetWorkflow(Context ctx, String name) {
        return ctx.run(Greeter::formatGreeting, name).await();
    }
}