Master Java CompletableFuture: From Basics to Advanced Async Patterns

Future Overview

The Future interface represents the result of an asynchronous computation. It allows a program to submit a time‑consuming task to a separate thread, continue doing other work, and later retrieve the result without blocking the main thread.

CompletableFuture Introduction

Java 8 introduced CompletableFuture, which extends Future and implements CompletionStage. It provides a richer set of methods for composing, combining, and handling asynchronous tasks, enabling functional‑style programming and non‑blocking pipelines.

Creating CompletableFuture Instances

You can create a CompletableFuture directly with the new operator, or use the static factory methods runAsync and supplyAsync. The latter two accept a Runnable or Supplier and optionally a custom Executor for better thread‑pool control.

CompletableFuture<RpcResponse<Object>> resultFuture = new CompletableFuture<>();
resultFuture.complete(rpcResponse);

CompletableFuture<String> future = CompletableFuture.completedFuture("hello!");
assertEquals("hello!", future.get());

Common Operations

thenApply

– transforms the result using a Function. thenAccept – consumes the result with a Consumer (no return value). thenRun – runs a Runnable after completion, without accessing the result. whenComplete – receives both the result and any thrown Throwable for final processing.

Example of chaining transformations:

CompletableFuture<String> future = CompletableFuture.completedFuture("hello!")
    .thenApply(s -> s + "world!")
    .thenApply(s -> s + "nice!");
assertEquals("hello!world!nice!", future.get());

Exception Handling

Use handle, exceptionally, or whenComplete to process errors without breaking the pipeline.

CompletableFuture<String> future = CompletableFuture.supplyAsync(() -> {
    if (true) throw new RuntimeException("Computation error!");
    return "hello!";
}).handle((res, ex) -> res != null ? res : "fallback");
assertEquals("fallback", future.get());

Composing Futures

thenCompose

creates a dependent chain where the second task receives the first task’s result. thenCombine merges two independent futures once both complete.

CompletableFuture<String> future = CompletableFuture.supplyAsync(() -> "hello!")
    .thenCompose(s -> CompletableFuture.supplyAsync(() -> s + "world!"));
assertEquals("hello!world!", future.get());

CompletableFuture<String> combined = CompletableFuture.supplyAsync(() -> "hello!")
    .thenCombine(CompletableFuture.supplyAsync(() -> "world!"), (s1, s2) -> s1 + s2);
assertEquals("hello!world!", combined.get());

Parallel Execution with allOf / anyOf

CompletableFuture.allOf

waits for a set of futures to finish before proceeding, while anyOf continues as soon as any one completes.

CompletableFuture<Void> all = CompletableFuture.allOf(future1, future2);
all.join(); // blocks until both are done

CompletableFuture<Object> any = CompletableFuture.anyOf(future1, future2);
System.out.println(any.get()); // prints result of whichever finishes first

Best Practices

Prefer a custom ThreadPoolExecutor over the default ForkJoinPool.commonPool() to avoid contention.

Avoid blocking calls like get() unless a timeout is specified.

Handle exceptions explicitly with whenComplete, exceptionally, or handle to prevent silent failures.

Combine tasks using the appropriate method ( thenCompose, thenCombine, acceptEither, allOf, anyOf) based on dependency and parallelism requirements.