The solution to these issues arrives in the form of the CompletableFuture. This com‐
bines the IOU idea of a Future with using callbacks to handle event-driven work. The key point about the CompletableFuture is that you can compose different instances in a way that doesn’t result in the pyramid of doom.
You might have encountered the concept behind the CompletableFu ture before; various other languages call them a deferred object or a promise. In the Google Guava Library and the Spring Framework these are referred to as ListenableFutures.
I’ll illustrate some usage scenarios by rewriting Example 9-9 to use CompletableFu ture, rather than Future, as in Example 9-10.
Example 9-10. Downloading album information from some external web services using CompletableFutures
public Album lookupByName(String albumName) { CompletableFuture<List<Artist>> artistLookup = loginTo("artist")
.thenCompose(artistLogin -> lookupArtists(albumName, artistLogin));
return loginTo("track")
.thenCompose(trackLogin -> lookupTracks(albumName, trackLogin)) .thenCombine(artistLookup, (tracks, artists)
-> new Album(albumName, tracks, artists)) .join();
}
Completable Futures | 149
In Example 9-10 loginTo, lookupArtists, and lookupTracks all return a Completa bleFuture instead of a Future. The key “trick” to the CompletableFuture API is to register lambda expressions and chain higher-order functions. The methods are dif‐
ferent, but the concept is incredibly similar to the Streams API design.
At we use the thenCompose method to transform our Credentials into a Completa bleFuture that contains the artists. This is a bit like taking an IOU for money from a friend and spending the money on Amazon when you get it. You don’t immediately get a new book—you just get an email from Amazon saying that your book is on its way: a different form of IOU.
At we again use thenCompose and the Credentials from our Track API login in order to generate a CompletableFuture of tracks. We introduce a new method, thenCom bine, at . This takes the result from a CompletableFuture and combines it with an‐
other CompletableFuture. The combining operation is provided by the end user as a lambda expression. We want to take our tracks and artists and build up an Album object, so that’s what we do.
At this point, it’s worth reminding yourself that just like with the Streams API, we’re not actually doing things; we’re building up a recipe that says how to do things. Our method can’t guarantee that the CompletableFuture has completed until one of the final meth‐
ods is called. Because CompletableFuture implements Future, we could just call the get method again. CompletableFuture contains the join method, which is called at and does the same job. It doesn’t have a load of the nasty checked exceptions that hin‐
dered our use of get.
You’ve probably got the basic idea of how to use CompletableFuture, but creating them is another matter. There are two different aspects of creating a CompletableFuture: creating the object itself and actually completing it by giving it the value that it owes its client code.
As Example 9-11 shows, it’s pretty easy to create a CompletableFuture object. You just call its constructor! This object can now be handed out to client code for chaining operations. We also keep a reference to this object in order to process the work on another thread.
Example 9-11. Completing a future by providing a value
CompletableFuture<Artist> createFuture(String id) {
CompletableFuture<Artist> future = new CompletableFuture<>();
startJob(future);
return future;
}
Once we’ve performed the work that needs to be done on whatever thread we’re using, we need to tell the CompletableFuture what value it represents. Remember that this
work can by done through a number of different threading models. For example, we can submit a task to an ExecutorService, use an event loop-based system such as Vert.x, or just spin up a Thread and do work on it. As shown in Example 9-12, in order to tell the CompletableFuture that it’s ready, you call the complete method. It’s time to pay back the IOU.
Example 9-12. Completing a future by providing a value
future.complete(artist);
Figure 9-4. A completable future is an IOU that can be processed by handlers
Of course, a very common usage of CompletableFuture is to asynchronously run a block of code. This code completes and returns a value. In order to avoid lots of people having to implement the same code over and over again, there is a useful factory method for creating a CompletableFuture, shown in Example 9-13, called supplyAsync. Example 9-13. Example code for asynchronously creating a CompletableFuture
CompletableFuture<Track> lookupTrack(String id) { return CompletableFuture.supplyAsync(() -> { // Some expensive work is done here // ...
return track;
}, service);
}
The supplyAsync method takes a Supplier that gets executed. The key point, shown at , is that this Supplier can do some time-consuming work without blocking the current thread—thus the Async in the method name. The value returned at is used to complete the CompletableFuture. At we provide an Executor, called service, that tells the
Completable Futures | 151
CompletableFuture where to perform the work. If no Executor is provided, it just uses the same fork/join thread pool that parallel streams execute on.
Of course, not every IOU has a happy ending. Sometimes we encounter exceptional circumstances and can’t pay our debts. As Example 9-14 demonstrates, the Completa bleFuture API accounts for these situations by letting you completeExceptionally. This can be called as an alternative to complete. You shouldn’t call both complete and completeExceptionally on a CompletableFuture, though.
Example 9-14. Completing a future if there’s an error
future.completeExceptionally(new AlbumLookupException("Unable to find " + name));
A complete investigation of the CompletableFuture API is rather beyond the scope of this chapter, but in many ways it is a hidden goodie bag. There are quite a few useful methods in the API for composing and combining different instances of Completable Future in pretty much any way imaginable. Besides, by now you should be familiar with the fluent style of chaining sequences of higher-order functions to tell the computer what to do.
Let’s take a brief look at a few of those use cases:
• If you want to end your chain with a block of code that returns nothing, such as a Consumer or Runnable, then take a look at thenAccept and thenRun.
• Transforming the value of the CompletableFuture, a bit like using the map method on Stream, can be achieved using thenApply.
• If you want to convert situations in which your CompletableFuture has completed with an exception, the exceptionally method allows you to recover by registering a function to make an alternative value.
• If you need to do a map that takes account of both the exceptional case and regular use cases, use handle.
• When trying to figure out what is happening with your CompletableFuture, you can use the isDone and isCompletedExceptionally methods.
CompletableFuture is really useful for building up concurrent work, but it’s not the only game in town. We’re now going to look at a related concept that offers a bit more flexibility in exchange for more complex code.