How To Manage Timeout for CompletableFuture

1. Overview

When we’re building a service that depends on other services, we often need to handle cases where a dependent service responds too slowly.

If we use CompletableFuture to manage the calls to our dependencies asynchronously, its timeout capabilities enable us to set a maximum waiting time for the result. If the expected result doesn’t arrive within the specified time, we can take action, such as providing a default value, to prevent our application from getting stuck in a lengthy process.

In this article, we’ll discuss three different ways to manage timeouts in CompletableFuture.

2. Manage Timeout

Imagine an e-commerce app that requires calls to external services for special product offers. We can use CompletableFuture with timeout settings to maintain responsiveness. This can throw errors or provide a default value if a service fails to respond quickly enough.

For example, in this case, let’s say we are going to make a request to an API that returns PRODUCT_OFFERS. Let’s call it fetchProductData(), which we can wrap with a CompletableFuture so we can handle the timeout:

private CompletableFuture<String> fetchProductData() {
    return CompletableFuture.supplyAsync(() -> {
        try {
            URL url = new URL("http://localhost:8080/api/dummy");
            HttpURLConnection connection = (HttpURLConnection) url.openConnection();

            try (BufferedReader in = new BufferedReader(new InputStreamReader(connection.getInputStream()))) {
                String inputLine;
                StringBuffer response = new StringBuffer();

                while ((inputLine = in.readLine()) != null) {
                    response.append(inputLine);
                }

                return response.toString();
            } finally {
                connection.disconnect();
            }
        } catch (IOException e) {
            return "";
        }
    });
}

To test timeouts using WireMock, we can easily configure a mock server for timeouts by following the WireMock usage guide. Let’s assume a reasonable web page load time on a typical internet connection is 1000 milliseconds, so we set a DEFAULT_TIMEOUT to that value:

private static final int DEFAULT_TIMEOUT = 1000; // 1 seconds

Then, we’ll create a wireMockServer that gives a body response of PRODUCT_OFFERS and set a delay of 5000 milliseconds or 5 seconds, ensuring that this value exceeds DEFAULT_TIMEOUT to ensure a timeout occurs:

stubFor(get(urlEqualTo("/api/dummy"))
  .willReturn(aResponse()
    .withFixedDelay(5000) // must be > DEFAULT_TIMEOUT for a timeout to occur.
    .withBody(PRODUCT_OFFERS)));

3. Using completeOnTimeout()

The completeOnTimeout() method resolves the CompletableFuture with a default value if the task doesn’t finish within the specified time.

With this method, we can set the default value <T> to return when a timeout occurs. This method returns the CompletableFuture on which this method is invoked.

In this example, let’s default to DEFAULT_PRODUCT:

CompletableFuture<Integer> productDataFuture = fetchProductData();
productDataFuture.completeOnTimeout(DEFAULT_PRODUCT, DEFAULT_TIMEOUT, TimeUnit.MILLISECONDS);
assertEquals(DEFAULT_PRODUCT, productDataFuture.get());

If we aim for results that remain meaningful even in the event of a failure or timeout during the request, then this approach is appropriate.

In an e-commerce scenario, for instance, when presenting product promotions, if retrieving special promo product data fails or exceeds the timeout, the system displays the default product instead.

4. Using orTimeout()

We can use orTimeout() to augment a CompletableFuture with timeout handling behavior if the future is not completed within a specific time.

This method returns the same CompletableFuture on which this method is applied and will throw a TimeoutException in case of a timeout.

Then, to test this method, we should use assertThrows() to prove an exception was raised:

CompletableFuture<Integer> productDataFuture = fetchProductData();
productDataFuture.orTimeout(DEFAULT_TIMEOUT, TimeUnit.MILLISECONDS);
assertThrows(ExecutionException.class, productDataFuture::get);

If our priority is responsiveness or time-consuming tasks and we want to provide quick action when a timeout occurs, then this is a suitable approach.

However, proper handling of these exceptions is required for good performance because this method explicitly throws exceptions.

Additionally, the approach is applicable in various scenarios, such as managing network connections, handling IO operations, processing real-time data, and managing queues.

5. Using completeExceptionally()

The CompletableFuture class’s completeExceptionally() method lets us complete the future exceptionally with a specific exception. Subsequent calls to result retrieval methods like get() and join() will throw the specified exception.

This method returns true if the method call resulted in the transition of the CompletableFuture to a completed state. Otherwise, it returns false.

Here, we’ll use ScheduledExecutorService, which is an interface in Java used to schedule and manage task executions at specific times or with delays. It provides flexibility in scheduling recurring tasks, handling timeouts, and managing errors in a concurrent environment:

ScheduledExecutorService executorService = Executors.newScheduledThreadPool(1);
//...
CompletableFuture<Integer> productDataFuture = fetchProductData();
executorService.schedule(() -> productDataFuture.completeExceptionally(
  new TimeoutException("Timeout occurred")), DEFAULT_TIMEOUT, TimeUnit.MILLISECONDS);
assertThrows(ExecutionException.class, productDataFuture::get);

If we need to handle TimeoutException along with other exceptions or we want to make it custom or specific, maybe this is a suitable way. We commonly use this approach to handle failed data validation, fatal errors, or when a task does not have a default value.

6. Comparison: completeOnTimeout() vs orTimeout() vs completeExceptionally()

With all these methods, we can manage and control the behavior of CompletableFuture in different scenarios, especially when working with asynchronous operations that require timing and handling timeouts or errors.

Let’s compare the advantages and disadvantages of the completeOnTimeout(), orTimeout(), and completeExceptionally():

7. Conclusion

In this article, we’ve looked at three different ways of responding to a timeout in an asynchronous process inside CompletableFuture.

When selecting our approach, we should consider our needs for managing long-running tasks. We should decide between default values, indicating asynchronous operation timeouts with specific exceptions.

As always, the full source code is available over on GitHub.