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.

<code>CompletableFuture&lt;RpcResponse&lt;Object&gt;&gt; resultFuture = new CompletableFuture&lt;&gt;();
resultFuture.complete(rpcResponse);
</code>

<code>CompletableFuture&lt;String&gt; future = CompletableFuture.completedFuture("hello!");
assertEquals("hello!", future.get());
</code>

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:

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

Exception Handling

Use

handle

,

exceptionally

, or

whenComplete

to process errors without breaking the pipeline.

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

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.

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

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

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.

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

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

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.