What is the difference between 'CompletionStage' and 'CompletableFuture'

Question

I have seen an example in each of them, but I need to know exactly what is the difference in deep, Because sometimes I think I can use both of them to get the same result, So I want know so that I can choose the correct one?

What is the benefit of using each of them?

Like this example both works:

public CompletionStage<Result> getNextQueryUUID() {
    return CompletableFuture.supplyAsync(() -> {
        String nextId = dbRequestService.getNextRequestQueryUUID();
        return ok(nextId);
    }, executor);
}


public CompletableFuture<Result> getNextQueryUUID() {
    return CompletableFuture.supplyAsync(() -> {
        String nextId = dbRequestService.getNextRequestQueryUUID();
        return ok(nextId);
    }, executor);
}

This example run in Play framework.

Answer 1

CompletionStage<T> is an interface of which CompletableFuture<T> is the only current implementing class. By looking at the javadoc for CompletionStage<T>, you'll notice it provides methods for taking one CompletionStage<T> and transforming it into another CompletionStage<T>. However, the returned values by the CompletionStage<T> are actually themselves CompletabeFuture<T> objects.

So using CompletabeFuture<T> is kind of the same thing as using a CompletionStage<T> but the latter can be used as the base interface for possible new classes in the future as well as being a target type for many descending types just as we tend to do List<Integer> integerList = new ArrayList<>(); rather than ArrayList<Integer> integerList = new ArrayList<>();

Answer 2

A CompletableFuture is a CompletionStage. However, as its name suggests, it is

• completable: It can be completed using complete or completeExceptionally.
• a Future: You can use get method, etc. to get the result.

IMHO, in most APIs, like in your example, you should use CompletionStage, because

• The implementation usually provides the mechanism to complete the stage. You don't need/want to expose methods like complete to the caller.
• The caller is expected to use the returned value in an async manner instead of using blocking calls like get provided by Future.