resonate-recursive-fan-out-pattern-java

Resonate Recursive Fan-Out 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). Every code block here is compile-verified against 0.1.1 and drawn from the example-fan-out-fan-in-java / example-recursive-factorial-java repos and develop/java.mdx (docs PR #230).

Overview

Recursive fan-out dispatches multiple child invocations in parallel, awaits them individually, and optionally recurses deeper. The Java expression is a two-loop pattern: a dispatch loop builds a List<ResonateFuture<T>>, then a separate await loop reads each result. Mixing dispatch and await serializes the children — the single most common mistake.

For the language-agnostic mental model (promise deduplication, load-balancing, detached vs. result-gathering), see resonate-recursive-fan-out-pattern-typescript.

When to use

• Batch processing where items are independent and each needs durability
• Map-reduce shaped workflows (fan out N workers, aggregate results)
• Recursive tree / graph traversal with dynamic depth
• Any case where a crash mid-fan-out must resume, not restart from zero

Dispatch-then-await shape

The canonical fan-out from example-fan-out-fan-in-java — dispatch all children first, await all second:

import io.resonatehq.resonate.Context;
import io.resonatehq.resonate.Context.ResonateFuture;
import java.util.ArrayList;
import java.util.List;

public record Delivery(String channel, boolean ok) {}

public static List<Delivery> fanout(Context ctx, List<String> channels, String message) {
    // Fan out: spawn a child per channel, collecting futures without awaiting yet.
    List<ResonateFuture<Delivery>> futures = new ArrayList<>();
    for (String channel : channels) {
        futures.add(ctx.run(FanOutFanIn::send, channel, message));
    }

    // Fan in: await every child and aggregate.
    List<Delivery> delivered = new ArrayList<>();
    for (ResonateFuture<Delivery> future : futures) {
        delivered.add(future.await());
    }
    return delivered;
}

public static Delivery send(Context ctx, String channel, String message) {
    return new Delivery(channel, true);
}