59

I have seen an example in each of them, but I need to know exactly what is the difference in deep because I think I can use both of them to get the same result, So I want to know then 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 runs in the Play framework.

Ebraheem Alrabeea
  • 2,130
  • 3
  • 23
  • 42

3 Answers3

53

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<>();

Ousmane D.
  • 54,915
  • 8
  • 91
  • 126
  • I think for the first time it is like the difference between `Thread` class and `Runnable` interface, So that there is more methods to use, but even more that will be benefit when I define a field of type `CompletableFuture` instead of returning value by a method. – Ebraheem Alrabeea Nov 30 '17 at 11:22
  • @EbraheemAlrabee the `CompletionStage` interface simply contains abstract methods for computations which may or may not be asynchronous. so, of course, the _implementing_ type will almost always have more functionality than it's base type, so as mentioned by Eugene within his post unless you're using some other implementation of that interface then it probably makes sense to use `CompletableFuture` as the target type _for now_.However there may be more implementing classes in the future, you never know. – Ousmane D. Nov 30 '17 at 11:31
  • As nicely explained by @Xiao, one should prefer to return `CompletionStage` rather than `CompletableFuture`. – Hermes Aug 18 '21 at 14:46
  • 1
    To me, returning `CompletionStage` provides callers with an impaired implementation. Notable missing methods include `get`, `join`, and `cancel`. You can get these by calling `toCompletableFuture()` but that feels like code clutter if you need to do it often. It also sort of makes returning the interface moot if you are converting it to concrete constantly. – jocull Nov 09 '22 at 04:45
40

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.
Xiao
  • 571
  • 6
  • 6
3

One is an interface and the other is a class. Usually you return the interface and not the implementation, but I doubt this is the case here. Returning CompletableFuture makes more sense for me.

Unless you are using some other implementation of that interface of course, like Spring's DelegatingCompletableFuture, but from your examples you are not.

Eugene
  • 117,005
  • 15
  • 201
  • 306
  • 1
    Returning a 'concrete class' should be avoided if there is a way to return the 'the super class/interface', unless the CALLER is looking for a 'subclass/concrete-class'. I agree to the answer by @xiao. – RafiAlhamd Mar 03 '20 at 10:27
  • 1
    You are both saying the same thing – acmoune Mar 10 '20 at 13:40
  • As nicely explained by @Xiao, one should prefer to return `CompletionStage` rather than `CompletableFuture`. – Hermes Aug 18 '21 at 14:47