Introduction to CompletableFutures

CompletableFuture is a new addition in Java 1.8. It's a type of Future object allowing execution of code upon completion. To explain the idea, let's first recap what a future object is.

A future, or promise as it's sometimes called in other languages, is an object that represents future result of an action. Rather than returning the result immediately, a future is returned which will contain the result at a later point. Consider for instance a get operation on a database. The database is a different process on the server, or on a different server. The database API library has to send the request to the database, and wait for the result. The method for the get request might look something like public DbResult get(String key). This function is blocking. This means means when we call get(), the API will wait until he result is available before returning it. The thread will sit idle while the database is processing the request. Other threads can of course continue to execute, but we could be doing other things while we wait for the database.

One solution would be a future object. We change the method signature to public Future<DbResult> get(String key). Now the API library immediately returns a future object. We can query the future object later to check if it has completed:

Future<DbResult> future = dbLib.get("mykey");
// get() returns immediately, and the result may not yet be available.
// Do other things while the database is executing.
// ...
// We now need the result from the database, wait for it.
DbResult result = future.get();

The advantage of using the future object is other things can be done while we wait for external resources. This means lower response times and better resource utilisation. However, there is still a problem: future.get() blocks. There are ways to inspect future objects to see if they're done, but that's beyond the scope of this article. In the end we still have to wait for the result to become available. What if there was a way we could tell the future object to execute some code whenever its ready?

Enter CompletableFuture. If you're familair with JavaScript, you may already be familiar with "promises" or "thenables". My personal favourite is the Q library, which implements an idea like CompletableFuture. Consider the database example from above:

CompletableFuture<DbResult> future = dbLib.get("mykey");
// Again, get() returns immediately.
// We then set up future processing.
future.thenAccept(result -> {
    // Process the result.
});
// Carry on doing other things which don't depend on the database result.

The completable future calls thenAccept() as soon it's completed. This is one of the many ways to interact with completable futures. There is no longer any need to block the current thread to wait for anything. There are a few other then...() methods. Before diving into some of them in detail, here's a quick summary of the most useful ones:

When the future completes

The first method we will examine is thenAccept(). We touched on this method in the previous example:

System.out.println("Requesting");
get("mykey").thenAccept(result -> {
    System.out.println("Processing");
});
System.out.println("Requested");

This will print:

Requesting
Requested
Processing

As we see, get() returns immediately. The call to thenAccept() tells the future we want more work done when the result is ready. I should note here that thenAccept() itself returns a CompletableFuture<Void>. Later we will cover how to chain many futures together in stages.

public Person parse(String data) {
    Person person = new Person();
    // Parse data and set values on person.
    return person;
}

CompletableFuture<Person> future = get(id).thenApply((result) -> {
    // Result is a String. Send it to the parse method.
    Person person = parse(result);
    // Now return the Person back out.
    return person;
});

public CompletableFuture<Person> get(String id) {
    // When creating future manually, it's important to include try/catch blocks.
    // This is because when an exception is thrown, we want to wrap it in a failed future.
    try {
        // cache is a simple Map<String, Person>.
        Person cached = cache.get(id);
        // If we have the object cached, simply wrap and return it.
        if (cached != null) {
            return CompletableFuture.completedFuture(cached);
        }
        // Object was not cached, create CompletableFuture to represent its future availability.
        CompletableFuture<Person> future = new CompletableFuture<>();
        // Code to fetch the Person here.
        // This example uses a legacy callback class as an example, but it could be any type of asynchronous code.
        databaseFetch(id, person -> {
            // Cache the person. (this step is specific to this example, included for completeness)
            cache.put(id, person);
            // Send the result to the future.
            future.complete(person);
        });
        // Return the future.
        return future;
    }
    // Wrap all errors in a failed future.
    catch (Throwable e) {
        // If errors happen, we use completeExceptionally() to report them.
        // The get() method itself should not throw any exceptions.
        CompletableFuture<Person> future = new CompletableFuture<>();
        future.completeExceptionally(e);
        return future;
    }
}

CompletableFuture<Person> personFuture = fetchPerson(id);
CompletableFuture<Company> companyFuture = personFuture.thenCombine(person -> {
    return fetchCompany(person.getCompanyId());
});
CompletableFuture<Void> future = companyFuture.thenAccept(company -> {
    // We now have the company.
});

CompletableFuture<Void> future = fetchPerson(id).thenCompose(person -> {
    return fetchCompany(person.getCompanyId()).thenAccept(company -> {
        // Now we have a reference to both objects.
    });
});

fetch(id).thenAccept((result) -> {
    // Block A: do something with result.
}).exceptionally((error) -> {
    // Block B: handle errors.
    return null;
});

String result = provider.fetch(id).get();

CompletableFuture<String> future = CompletableFuture.completedFuture("foo");
future = future.thenApply(str -> {
    System.out.println("Stage 1: " + str);
    return "bar";
});
future = future.thenApply(str -> {
    System.out.println("Stage 2: " + str);
    throw new RuntimeException();
});
future = future.thenApply(str -> {
    System.out.println("Stage 3: " + str);
});
future.exceptionally(e -> {
    System.out.println("Exceptionally");
});

CompletableFuture<String> future = CompletableFuture.completedFuture("foo");
future.thenApply(str -> {
    System.out.println("Stage 1: " + str);
    return "bar";
});
future.thenApply(str -> {
    System.out.println("Stage 2: " + str);
    throw new RuntimeException();
});
future.thenApply(str -> {
    System.out.println("Stage 3: " + str);
    return "abc";
});
future.exceptionally(e -> {
    System.out.println("Exceptionally");
    return null;
});

Stage 1: foo
Stage 2: bar
Exceptionally

Stage 1: foo
Stage 2: foo
Stage 3: foo

CompletableFuture<String> future = new CompletableFuture<>();
future.thenApply(str -> {
    System.out.println("Stage 1: " + str);
    return "bar";
});
future.thenApply(str -> {
    System.out.println("Stage 2: " + str);
    throw new RuntimeException();
});
future.thenApply(str -> {
    System.out.println("Stage 3: " + str);
    return "abc";
});
future.exceptionally(e -> {
    System.out.println("Exceptionally");
    return null;
});
future.complete("foo");

Stage 3: foo
Stage 2: foo
Stage 1: foo