Java CompletableFuture

What is Java CompletableFuture?

Java CompletableFuture is used when you have a task that needs to be run asynchronously and you want to wait for the task to complete and obtain a value OR to force a task to complete. It also allows chaining multiple tasks together or executing a task after a few other tasks are completed. The power of Java CompletableFuture lies in its ability to Join tasks in multiple ways thereby providing a high level of flexibility in organizing asynchronous tasks.
It has been added in Java 1.8 and extends the functionality of Future.

Example of creating a Java CompletableFuture.

Java CompletableFuture can be created by the following methods:

Creating an empty Java CompletableFuture

Create an empty CompletableFuture and add stages to it. It is incomplete and can be completed.

Create an async Java CompletableFuture using a Supplier.

Create a completableFuture Using a Supplier<U>. The supplier provides the return value and the CompletableFuture is asynchronously completed.

By Default the async process uses the ForkJoinPool, however we can pass our own Executor framework.

Create an async Java CompletableFuture Using a Runnable.

If you don’t need to return a value, use the runAsync method instead. It takes in a Runnable

Ways to complete a Java CompletableFuture.

CompletableFuture allows you to complete a task explicitly from the calling thread. It is possible to complete a task cleanly or to complete a task to through an Exception. Let’s look at some of the ways to complete.

complete a Java CompletableFuture without exception

Lets first see how to cleanly complete a CompletableFuture. In the example below we first create a CompletableFuture using the supplyAsync method and we put a sleep of 10 seconds inside the async task. We then complete the future externally. Since there is a sleep of 10s the internal task would not have a chance to complete and it will never return the value of “finished”. A ‘get()’ call simply returns the value that we pass to the complete() function and isDone() returns true.

complete a Java CompletableFuture with exception

In the previous example, we completed the CompletableFuture so that it just returns without throwing an exception, in this example we tell the async task to complete by throwing an Exception.

CompletionStage methods of Java CompletableFuture – Chaining Tasks

CompletableFuture implements the CompletionStage interface and this interface provides a group of methods to arrange CompletableFuture Tasks. Lets look at some of the methods

Perform an action when one of two CompletableFuture completes

If there are two CompletableFutures and we need to perform an action with the first action that completes, then use acceptEither. Has an async variation.

The applyToEither variation performs an operation on the result and returns the result of that operation.

Handle both the result and Exception from a CompletableFuture

The CompletableFuture may either complete without problems or throw and Exception. Use the ‘handle’ method to handle both cases together.

Perform a Task after two CompletableFuture finish

Perform a Task that accepts the results of two CompletableFutures

Return a CompletableFuture when any one of a group of CompletableFuture complete

Return a CompletableFuture when All of a group of CompletableFuture complete

This method can be used to wait till all the asynchronous processes complete. No results are

We have described some of the methods of Java CompletableFuture. To look at the complete list, check out the CompletionStage docs.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.