CompletableFuture | thenApply vs thenCompose

I can't get my head around the difference between thenApply and thenCompose.

So, could someone provide a valid use case?

From the Java docs:

thenApply(Function<? super T,? extends U> fn)

> Returns a new CompletionStage that, when this stage completes > normally, is executed with this stage's result as the argument to the > supplied function.

thenCompose(Function<? super T,? extends CompletionStage<U>> fn)

> Returns a new CompletionStage that, when this stage completes > normally, is executed with this stage as the argument to the supplied > function.

I get that the 2nd argument of thenCompose extends the CompletionStage where thenApply does not.

Could someone provide an example in which case I have to use thenApply and when thenCompose?

thenApply is used if you have a synchronous mapping function.

CompletableFuture<Integer> future = 
    CompletableFuture.supplyAsync(() -> 1)
                     .thenApply(x -> x+1);

thenCompose is used if you have an asynchronous mapping function (i.e. one that returns a CompletableFuture). It will then return a future with the result directly, rather than a nested future.

CompletableFuture<Integer> future = 
    CompletableFuture.supplyAsync(() -> 1)
                     .thenCompose(x -> CompletableFuture.supplyAsync(() -> x+1));

I think the answered posted by @Joe C is misleading.

Let me try to explain the difference between thenApply and thenCompose with an example.

Let's suppose that we have 2 methods: getUserInfo(int userId) and getUserRating(UserInfo userInfo):

public CompletableFuture<UserInfo> getUserInfo(userId)

public CompletableFuture<UserRating> getUserRating(UserInfo)

Both method return types are CompletableFuture.

We want to call getUserInfo() first, and on its completion, call getUserRating() with the resulting UserInfo.

On the completion of getUserInfo() method, let's try both thenApply and thenCompose. The difference is in the return types:

CompletableFuture<CompletableFuture<UserRating>> f =
    userInfo.thenApply(this::getUserRating);
 
CompletableFuture<UserRating> relevanceFuture =
    userInfo.thenCompose(this::getUserRating);

thenCompose() works like Scala's flatMap which flattens nested futures.

thenApply() returned the nested futures as they were, but thenCompose() flattened the nested CompletableFutures so that it is easier to chain more method calls to it.

The updated Javadocs in Java 9 will probably help understand it better:

thenApply

<U> CompletionStage<U> thenApply​(Function<? super T,? extends U> fn) > > Returns a new CompletionStage that, when this stage completes > normally, is executed with this stage's result as the argument to the > supplied function. > > This method is analogous to Optional.map and Stream.map. > > See the CompletionStage documentation for rules covering > exceptional completion.

thenCompose

<U> CompletionStage<U> thenCompose​(Function<? super T,? extends CompletionStage<U>> fn)

> Returns a new CompletionStage that is completed with the same > value as the CompletionStage returned by the given function. > > When this stage completes normally, the given function is invoked with > this stage's result as the argument, returning another > CompletionStage. When that stage completes normally, the > CompletionStage returned by this method is completed with the same > value. > > To ensure progress, the supplied function must arrange eventual > completion of its result. > > This method is analogous to Optional.flatMap and > Stream.flatMap. > > See the CompletionStage documentation for rules covering > exceptional completion.

thenApply and thenCompose are methods of CompletableFuture. Use them when you intend to do something to CompletableFuture's result with a Function.

thenApply and thenCompose both return a CompletableFuture as their own result. You can chain multiple thenApply or thenCompose together. Supply a Function to each call, whose result will be the input to the next Function.

The Function you supplied sometimes needs to do something synchronously. The return type of your Function should be a non-Future type. In this case you should use thenApply.

CompletableFuture.completedFuture(1)
    .thenApply((x)->x+1) // adding one to the result synchronously, returns int
    .thenApply((y)->System.println(y)); // value of y is 1 + 1 = 2

Other times you may want to do asynchronous processing in this Function. In that case you should use thenCompose. The return type of your Function should be a CompletionStage. The next Function in the chain will get the result of that CompletionStage as input, thus unwrapping the CompletionStage.

// addOneAsync may be implemented by using another thread, or calling a remote method
abstract CompletableFuture<Integer> addOneAsync(int input);

CompletableFuture.completedFuture(1)
    .thenCompose((x)->addOneAsync(x)) // doing something asynchronous, returns CompletableFuture<Integer>
    .thenApply((y)->System.println(y)); // y is an Integer, the result of CompletableFuture<Integer> above

This is a similar idea to Javascript's Promise. Promise.then can accept a function that either returns a value or a Promise of a value. The reason why these two methods have different names in Java is due to generic erasure. Function<? super T,? extends U> fn and Function<? super T,? extends CompletionStage<U>> fn are considered the same Runtime type - Function. Thus thenApply and thenCompose have to be distinctly named, or Java compiler would complain about identical method signatures. The end result being, Javascript's Promise.then is implemented in two parts - thenApply and thenCompose - in Java.

You can read my other answer if you are also confused about a related function thenApplyAsync.

thenCompose() is better for chaining CompletableFuture.

thenApply() is better for transform result of Completable future.

You can achieve your goal using both techniques, but one is more suitable for one use case then other.

public CompletableFuture<Integer> process(Integer i) {
    CompletableFuture<Integer> completableFuture = CompletableFuture.supplyAsync(
            () -> new HeavyTask(i).execute());
    return completableFuture;
}

@SneakyThrows
public CompletableFuture<Integer> thenApplyVsThenCompose() {
    // each time calling thenApply() function returns CompletionState
    // so you will get nested Futures 
    // you can think about it like map() java optional
    CompletableFuture<Future<Integer>> cf1 = CompletableFuture.supplyAsync(
            () -> new HeavyTask().execute())
            .thenApply(i -> process(i));

    // to get result you will have to get nested get() calls
    Integer resultFromThenApply = cf1.get().get();

    // when calling thenCompose() nested Futures are flatten
    // you can think about it like flatMap() java optional
    CompletableFuture<Integer> cf2;
    cf2 = CompletableFuture.supplyAsync(
            () -> new HeavyTask().execute())
            .thenCompose(this::process);

    // you have to just call one get() since thenCompose was flatten
    Integer resultFromThenCompose = cf2.get();
    return null;
} 

Other problem that can visualize difference between those two

How would you implement solution when you do not know how many time you have to apply thenApply()/thenCompose() (in case for example recursive methods)?

public void nested() throws ExecutionException, InterruptedException {
    CompletableFuture<Integer> completableFutureToCompose = CompletableFuture.completedFuture(1);
    for (int i = 0; i < 10; i++) {
        log.info("Composing");
        completableFutureToCompose = completableFutureToCompose.thenCompose(this::process);
    }
    completableFutureToCompose.get();

    // not achievable using then apply
    CompletableFuture<Integer> completableFutureToApply = CompletableFuture.completedFuture(1);
    for (int i = 0; i < 10; i++) {
        log.info("Applying");
        completableFutureToApply = completableFutureToApply.thenApply(this::process).get();
    }
    completableFutureToCompose.get();
}

public CompletableFuture<Integer> process(Integer i) {
    log.info("PROCESSING");
    CompletableFuture<Integer> completableFuture = CompletableFuture.supplyAsync(
            () -> new HeavyTask(i).execute());
    return completableFuture;
}

• Using composing you first create receipe how futures are passed one to other and then execute

• Using apply you execute logic after each apply invocation

JoeC's answer is correct, but I think the better comparison that can clear the purpose of the thenCompose is the comparison between thenApply and thenApply! Once when a synchronous mapping is passed to it and once when an asynchronous mapping is passed to it.

If the mapping passed to the thenApply returns an String(a non-future, so the mapping is synchronous), then its result will be CompletableFuture<String>. Now similarly, what will be the result of the thenApply, when the mapping passed to the it returns a CompletableFuture>(a future, so the mapping is asynchronous)? The end result will be CompletableFuture<CompletableFuture<String>>, which is unnecessary nesting(future of future is still future!). Here's where we can use thenCompose to be able to "compose"(nest) multiple asynchronous tasks in each other without getting futures nested in the result.

private void test1() throws ExecutionException, InterruptedException {

    //thenApply返回的是之前的CompletableFuture
    CompletableFuture<Integer> future = CompletableFuture.supplyAsync(() -> 1)
            .thenApply((x) -> {
                x = x + 1;
                log.info("thenApply, 1, x:{}", x);
                return x;
            });

    System.out.println(future.get());
}

//thenCompose返回的是新的CompletableFuture
private void test2() throws ExecutionException, InterruptedException {
    CompletableFuture<Integer> future = CompletableFuture.supplyAsync(() -> 1)
            .thenCompose((x) -> {
                return CompletableFuture.supplyAsync(() -> {
                    Integer y = x + 1;
                    log.info("thenCompose, 1, x:{}", y);
                    return y;
                });
            });

    System.out.println(future.get());
}

And if you are still confused about what makes the real difference in code when I use thenApply vs thenCompose and what a nested future looks like then please look at the full working example.

package com.graphql.demo.garphqlapi;

import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.function.Supplier;

public class ComposeVsThenApply {

    public static void main(String[] args) {
        ComposeVsThenApply cva = new ComposeVsThenApply();
        //thenCompose usage : Using the thenCompose for simplifying the return type of dependent processing.
        System.out.println("Starting thenCompose demo");
        CompletableFuture<StockRating> flattenedFuture = cva.getStockDetails("Apple").thenCompose((stock) -> {
            return cva.getRating(stock);
        });
        //Retrive results
        try {
            StockRating stockViaThenCompose = flattenedFuture.get();
            System.out.println("\n\t\tStock summery :" + stockViaThenCompose.getStockName() + ", Rating :" + stockViaThenCompose.getRating());
            System.out.println("--- thenCompose demo ended ---");
        } catch (InterruptedException e) {
            e.printStackTrace();
        } catch (ExecutionException e) {
            e.printStackTrace();
        }

        //ThenAply: thenApply is good for result transformation but sucks when we have two asynchronous dependent processing. Now you get nested future.
        System.out.println("\n\n\nStarting thenApply demo");
        CompletableFuture<CompletableFuture<StockRating>> nestedFuture = cva.getStockDetails("Apple").thenApply((stock) -> {
            return cva.getRating(stock);
        });
        //Retrive results
        try {
            StockRating stockrViaThenApply = nestedFuture.get().get();
            System.out.println("\n\t\tStock summery :" + stockrViaThenApply.getStockName() + ", Rating :" + stockrViaThenApply.getRating());
            System.out.println("--- thenApply demo ended---");
        } catch (InterruptedException e) {
            e.printStackTrace();
        } catch (ExecutionException e) {
            e.printStackTrace();
        }
    }

    class Stock {
        private String name;

        public Stock(String name) {
            this.name = name;
        }

        public String getName() {
            return name;
        }

        public void setName(String name) {
            this.name = name;
        }
    }

    class StockRating {
        private Double rating;

        public boolean isBuyCall() {
            return buyCall;
        }

        public void setBuyCall(boolean buyCall) {
            this.buyCall = buyCall;
        }

        public String getStockName() {
            return stockName;
        }

        public void setStockName(String stockName) {
            this.stockName = stockName;
        }

        private boolean buyCall;

        public StockRating(Double rating, boolean buyCall, String stockName) {
            this.rating = rating;
            this.buyCall = buyCall;
            this.stockName = stockName;
        }

        private String stockName;

        public StockRating(Double rating) {
            this.rating = rating;
        }

        public Double getRating() {
            return rating;
        }

        public void setRating(Double rating) {
            this.rating = rating;
        }
    }

    class StockSupplier implements Supplier<Stock> {
        private String name;

        public StockSupplier(String name) {
            this.name = name;
        }

        @Override
        public Stock get() {
            try {
                System.out.println("\n\t\tRetriving details for " + this.name);
                TimeUnit.SECONDS.sleep(4);
                System.out.println("\n\t\tDone with details retrival for " + this.name);
            } catch (InterruptedException e) {
                e.printStackTrace();
            }
            return new Stock(name);
        }
    }

    class RatingSupplier implements Supplier<StockRating> {
        private Stock stock;

        public RatingSupplier(Stock stock) {
            this.stock = stock;
        }

        @Override
        public StockRating get() {
            try {
                System.out.println("\n\t\tRetriving stock rating for " + this.stock.getName());
                TimeUnit.SECONDS.sleep(4);
                System.out.println("\n\t\tDone with rating retrival for " + this.stock.getName());
            } catch (InterruptedException e) {
                e.printStackTrace();
            }
            return new StockRating(10d, true, this.stock.getName());
        }
    }

    public CompletableFuture<Stock> getStockDetails(String name) {
        return CompletableFuture.supplyAsync(new StockSupplier(name));
    }

    public CompletableFuture<StockRating> getRating(Stock stock) {
        return CompletableFuture.supplyAsync(new RatingSupplier(stock));
    }

    public String getSummeryReport(Stock stock, StockRating sr) {
        return stock.getName() + "/n " + sr.getRating();
    }
}

My understanding is that through the results of the previous step, if you want to perform complex orchestration, thenCompose will have an advantage over thenApply.

The following example is, through the results of the first step, go to two different places to calculate, whoever returns sooner, you can see the difference between them

    CompletableFuture<Integer> result = CompletableFuture.supplyAsync(() -> 1);
    // thenCompose
    System.out.println(result.thenCompose(i -> CompletableFuture.anyOf(CompletableFuture.supplyAsync(() -> i + 1), CompletableFuture.supplyAsync(() -> i + 2))).join());
    System.out.println(result.thenCompose(i -> CompletableFuture.supplyAsync(() -> i + 1).applyToEither(CompletableFuture.supplyAsync(() -> i + 2), j -> j)).join());
    // ----- thenApply
    System.out.println(result.thenApply(i -> CompletableFuture.anyOf(CompletableFuture.supplyAsync(() -> i + 1), CompletableFuture.supplyAsync(() -> i + 2)).join()).join());
    System.out.println(result.thenApply(i -> CompletableFuture.supplyAsync(() -> i + 1).applyToEither(CompletableFuture.supplyAsync(() -> i + 2), j -> j).join()).join());