whenComplete

whenComplete is a method used in the Java CompletableFuture and more generally the CompletionStage interface. It registers a callback to be executed when the asynchronous computation completes, whether normally or abnormally. The callback is provided as a BiConsumer that receives two arguments: the result (if completed normally) and the throwable (if completed exceptionally).

The action passed to whenComplete is intended for side effects rather than transformation. When the stage completes normally, the BiConsumer gets the result and a null throwable. When it completes exceptionally, the BiConsumer gets a null result and the corresponding Throwable. The whenComplete method itself returns a new CompletionStage that completes in the same way as the original stage: with the same result or exception, unless the action itself throws. If the action throws, the returned stage completes exceptionally with that exception, potentially masking the original failure.

Variants and common usage patterns include whenCompleteAsync, which executes the callback asynchronously using the common fork-join pool, and whenCompleteAsync with a specified Executor to control threading. This makes it suitable for non-blocking logging, resource cleanup, or metric collection that should occur after a computation finishes, without altering the computation's outcome.

Compared to related methods, whenComplete does not modify the final value, whereas handle can transform the result and may produce a different type. ThenAccept and thenRun focus on subsequent actions that do not alter the final outcome. When implementing robust asynchronous workflows, whenComplete is a lightweight way to observe completion while preserving the original result.