spotify/completable-futures

To use completable-futures in your Java 8 project, add the following dependency to your pom.xml. The library has no additional dependencies.

<dependency>
    <groupId>com.spotify</groupId>
    <artifactId>completable-futures</artifactId>
    <version>0.3.1</version>
</dependency>

exceptionallyCompose is similar to CompletableFuture.exceptionally, but it allows you to return a new CompletionStage (e.g., a fallback future) instead of a direct value.

CompletionStage<String> composed = CompletableFutures.exceptionallyCompose(future, throwable -> completedFuture("fallback"));

Use CompletableFutures.allAsList to join a List of futures of the same type into a single future that completes to a list containing all the values.

List<CompletableFuture<String>> futures = asList(completedFuture("a"), completedFuture("b"));
CompletableFuture<List<String>> joined = CompletableFutures.allAsList(futures);

The combine method allows you to merge multiple futures of different types into a single result using a provided function. It supports combining between 2 and 5 futures directly via overloaded methods.

CompletableFutures.combine(f1, f2, (a, b) -> a + b);
CompletableFutures.combine(f1, f2, f3, (a, b, c) -> a + b + c);
CompletableFutures.combine(f1, f2, f3, f4, (a, b, c, d) -> a + b + c + d);
CompletableFutures.combine(f1, f2, f3, f4, f5, (a, b, c, d, e) -> a + b + c + d + e);

To combine more than five futures of different types, use the combine method that accepts a vararg of futures and a function. The function receives a CombinedFutures object, which provides a safe .get(future) method to extract values. This is safer than calling .join() on the input futures directly, as it prevents IllegalArgumentException if a future is not part of the combination.

CompletionStage<String> f1;
CompletionStage<String> f2;
CompletionStage<String> result = combine(combined -> combined.get(f1) + combined.get(f2), f1, f2);

// In a combineFutures form:
CompletionStage<String> f1;
CompletionStage<String> f2;
CompletionStage<String> result = dereference(combine(combined -> completedFuture(combined.get(f1) + combined.get(f2)), f1, f2));

joinMap is a stream collector that applies an asynchronous operation to each element in a stream and associates the result with a key derived from the original element.

collection.stream()
    .collect(joinMap(this::toKey, this::someAsyncFunc))
    .thenApply(this::consumeMap)

If you are dealing with a long-running external task that only exposes a polling API, you can transform it into a future using CompletableFutures.poll. You provide a Supplier<Optional<T>> for the task, a Duration for the frequency, and an Executor.

Supplier<Optional<T>> pollingTask = () -> Optional.ofNullable(resource.result());
Duration frequency = Duration.ofSeconds(2);
CompletableFuture<T> result = CompletableFutures.poll(pollingTask, frequency, executor);

exceptionallyCompletedFuture creates a new future that is already completed with the provided exception.

return CompletableFutures.exceptionallyCompletedFuture(new RuntimeException("boom"));

joinList is a stream collector that combines multiple futures into a single list. This is useful when applying an asynchronous operation to a collection of entities.

collection.stream()
    .map(this::someAsyncFunction)
    .collect(CompletableFutures.joinList())
    .thenApply(this::consumeList)

supplyAsyncCompose is like CompletableFuture.supplyAsync, but it automatically unwraps a CompletionStage<CompletionStage<T>> to a plain CompletionStage<T> when the Supplier returns a CompletionStage.

CompletionStage<String> suppliedStage = completedFuture("hello").thenApply(stage -> stage + "-chained");
CompletionStage<String> outputStage = CompletableFutures.supplyAsyncCompose(suppliedStage);

Use combineFutures to combine multiple futures into a new future (e.g., when the combining function itself returns a CompletableFuture).

CompletableFutures.combineFutures(f1, f2, (a, b) -> completedFuture(a + b));
CompletableFutures.combineFutures(f1, f2, f3, (a, b, c) -> completedFuture(a + b + c));
CompletableFutures.combineFutures(f1, f2, f3, f4, (a, b, c, d) -> completedFuture(a + b + c + d));
CompletableFutures.combineFutures(f1, f2, f3, f4, f5, (a, b, c, d, e) -> completedFuture(a + b + c + d + e));

dereference unwraps a CompletionStage<CompletionStage<T>> into a plain CompletionStage<T>.

CompletionStage<CompletionStage<String>> wrapped = completedFuture(completedFuture("hello"));
CompletionStage<String> unwrapped = CompletableFutures.dereference(wrapped);