Working with Exceptions in Java CompletableFuture

1. Introduction

Java 8 has introduced a new abstraction based on Future to run asynchronous tasks – CompletableFuture class. It basically came to overcome the issues of the old Future API.

In this tutorial, we’re going to look into the ways to work with exceptions when we use CompletableFuture.

2. CompletableFuture Recap

First, we might need to recap a little bit about what the CompletableFuture is. CompletableFuture is a Future implementation that allows us to run and, most importantly, chain asynchronous operations. In general, there are three possible outcomes for the async operation to complete – normally, exceptionally, or can be canceled from outside. CompletableFuture has various API methods to address all of these possible outcomes.

As with lots of the other methods in CompletableFuture, these methods have non-async, async, and async using specific Executor variations. So, without further delay, let’s look at ways to handle exceptions in CompletableFuture one by one.

3. handle()

First, we have a handle() method. By using this method, we can access and transform the entire result of the CompletionStage regardless of the outcome. That is, the handle() method accepts a BiFunction functional interface. So, this interface has two inputs. In the handle() method case, parameters will be the result of the previous CompletionStage and the Exception that occurred.

The important thing is that both of these parameters are optional, meaning that they can be null. This is obvious in some sense since the previous CompletionStage was completed normally. Then the Exception should be null since there was no any, similarly with CompletionStage result value nullability.

Let’s now look at an example of handle() method usage:

@ParameterizedTest
@MethodSource("parametersSource_handle")
void whenCompletableFutureIsScheduled_thenHandleStageIsAlwaysInvoked(int radius, long expected)
  throws ExecutionException, InterruptedException {
    long actual = CompletableFuture
      .supplyAsync(() -> {
          if (radius <= 0) {
              throw new IllegalArgumentException("Supplied with non-positive radius '%d'");
          }
          return Math.round(Math.pow(radius, 2) * Math.PI);
      })
      .handle((result, ex) -> {
          if (ex == null) {
              return result;
          } else {
              return -1L;
          }
      })
      .get();

    Assertions.assertThat(actual).isEqualTo(expected);
}

static Stream<Arguments> parameterSource_handle() {
    return Stream.of(Arguments.of(1, 3), Arguments.of(1, -1));
}

The thing to notice here is that the handle() method returns a new CompletionStage that will always execute, regardless of the previous CompletionStage result. So, handle() transforms the source value from the previous stage to some output value. Therefore, the value that we’re going to obtain via the get() method is the one returned from the handle() method.

4. exceptionally()

The handle() method is not always convenient, especially if we want to process exceptions only if there is one. Luckily, we have an alternative – exceptionally().

This method allows us to provide a callback to be executed only if the previous CompletionStage ended up with an Exception. If no exceptions were thrown, then the callback is omitted, and the execution chain is continued to the next callback (if any) with the value of the previous one.

To understand, let’s look at a concrete example:

@ParameterizedTest
@MethodSource("parametersSource_exceptionally")
void whenCompletableFutureIsScheduled_thenExceptionallyExecutedOnlyOnFailure(int a, int b, int c, long expected)
  throws ExecutionException, InterruptedException {
    long actual = CompletableFuture
      .supplyAsync(() -> {
          if (a <= 0 || b <= 0 || c <= 0) {
              throw new IllegalArgumentException(String.format("Supplied with incorrect edge length [%s]", List.of(a, b, c)));
          }
          return a * b * c;
      })
      .exceptionally((ex) -> -1)
      .get();

    Assertions.assertThat(actual).isEqualTo(expected);
}

static Stream<Arguments> parametersSource_exceptionally() {
    return Stream.of(
      Arguments.of(1, 5, 5, 25),
      Arguments.of(-1, 10, 15, -1)
    );
}

So here, it works in the same manner as handle(), but we have an Exception instance as a parameter to our callback. This parameter will never be null, so our code is a bit simpler now.

The important thing to notice here is the exceptionally() method’s callback executes only if the previous stage completes with an Exception. It basically means that if the Exception occurred somewhere in the execution chain, and there already was a handle() method that caught it – the excpetionally() callback won’t be executed afterward:

@ParameterizedTest
@MethodSource("parametersSource_exceptionally")
void givenCompletableFutureIsScheduled_whenHandleIsAlreadyPresent_thenExceptionallyIsNotExecuted(int a, int b, int c, long expected)
  throws ExecutionException, InterruptedException {
    long actual = CompletableFuture
      .supplyAsync(() -> {
          if (a <= 0 || b <= 0 || c <= 0) {
              throw new IllegalArgumentException(String.format("Supplied with incorrect edge length [%s]", List.of(a, b, c)));
          }
          return a * b * c;
      })
      .handle((result, throwable) -> {
          if (throwable != null) {
              return -1;
          }
          return result;
      })
      .exceptionally((ex) -> {
          System.exit(1);
          return 0;
      })
      .get();

    Assertions.assertThat(actual).isEqualTo(expected);
}

Here, exceptionally() is not invoked since the handle() method already catches the Exception, if any. Therefore, unless the Exception occurs inside the handle() method, the exceptionally() method here won’t be ever executed.

5. whenComplete()

We also have a whenComplete() method in the API. It accepts the BiConsumer with two parameters: the result and the exception from the previous stage, if any. This method, however, is significantly different from the ones above.

The difference is that whenComplete() will not translate any exceptional outcomes from the previous stages. So, even considering that whenComplete()‘s callback will always run, the exception from the previous stage, if any, will propagate further:

@ParameterizedTest
@MethodSource("parametersSource_whenComplete")
void whenCompletableFutureIsScheduled_thenWhenCompletedExecutedAlways(Double a, long expected) {
    try {
        CountDownLatch countDownLatch = new CountDownLatch(1);
        long actual = CompletableFuture
          .supplyAsync(() -> {
              if (a.isNaN()) {
                  throw new IllegalArgumentException("Supplied value is NaN");
              }
              return Math.round(Math.pow(a, 2));
          })
          .whenComplete((result, exception) -> countDownLatch.countDown())
          .get();
        Assertions.assertThat(countDownLatch.await(20L, java.util.concurrent.TimeUnit.SECONDS));
        Assertions.assertThat(actual).isEqualTo(expected);
    } catch (Exception e) {
        Assertions.assertThat(e.getClass()).isSameAs(ExecutionException.class);
        Assertions.assertThat(e.getCause().getClass()).isSameAs(IllegalArgumentException.class);
    }
}

static Stream<Arguments> parametersSource_whenComplete() {
    return Stream.of(
      Arguments.of(2d, 4),
      Arguments.of(Double.NaN, 1)
    );
}

As we can see here, callback inside whenCompleted() runs in both test invocations. However, in the second invocation, we completed with the ExecutionException, which has the cause of our IllegalArgumentException. So, as we can see, the exception from the callback propagates to the callee. We’ll cover the reasons why it happens in the next section.

6. Unhandled Exceptions

Finally, we need to touch on unhandled exceptions a bit. In general, if an exception remains uncaught, then the CompletableFuture completes with an Exception that doesn’t propagate to the callee. In our case above, we get the ExecutionException from the get() method invocation. So, this is because we tried to access the result when CompletableFuture ended up with an Exception.

Thus, we need to check the result of the CompletableFuture before the get() invocation. There are a couple of ways to do so. The first and probably the most familiar to all approach is via isCompletedExceptionally()/isCancelled()/isDone() methods. Those methods return a boolean in case CompletableFutre completes with the exception, is cancelled from outside, or is completed successfully.

However, it is worth mentioning that there is also a state() method that returns a State enum instance. This instance represents the state of the CompletableFuture, like RUNNING, SUCCESS, etc. So, this is another way to access the outcome of the CompletableFuture.

7. Conclusion

In this article, we’ve explored the ways to handle exceptions that occur in CompletableFuture stages.