thenCombine

thenCombine is a method of CompletableFuture that creates a new stage which completes when two independent computations have finished. It takes another CompletionStage and a BiFunction that combines the two results into a new value.

The typical signature is something like thenCombine(CompletionStage<U> other, BiFunction<? super T, ? super U, ? extends V> fn) and returns a CompletableFuture<V>. The new future completes after both sources have completed normally; the BiFunction is applied to the two results to produce the final value.

Behavior and threading: if either of the two input futures completes exceptionally, the resulting future completes exceptionally with the same exception. If both complete normally, the BiFunction is invoked with the two results and its return value completes the new future. The execution of the combining function can occur in the thread that completes the second stage by default, or in a separate thread if using the asynchronous variants or an explicit executor.

Variants and executors: there are asynchronous variants, such as thenCombineAsync, which schedule the combining step to run asynchronously, optionally using a provided Executor. This gives control over which threads perform the combination work.

Common use: thenCombine is useful when two independent asynchronous tasks fetch or compute data, and you need a single result derived from both outcomes, for example summing two values obtained from separate services or combining two related datasets.

Example: CompletableFuture<Integer> a = fetchA(); CompletableFuture<Integer> b = fetchB(); CompletableFuture<Integer> sum = a.thenCombine(b, (x, y) -> x + y);

See also: thenAcceptBoth, which consumes both results without producing a combined value.