Difference Between orTimeout() and completeOnTimeOut() Methods in Java 9

Java 9 introduced several new features and enhancements to further improve the language's capabilities. Among these additions are the orTimeout() and completeOnTimeout() methods that are designed to enhance the handling of timeouts in CompletableFuture instances. These methods provide developers with more control and flexibility when dealing with asynchronous tasks that may take longer than expected.

In this section, we will delve into the differences between the orTimeout() and completeOnTimeout() methods, examining their purposes, behaviors, and use cases.

orTimeout() Vs. completeOnTimeout() Methods

Aspect	orTimeout() Method	completeOnTimeout() Method
Purpose	Introduce a timeout mechanism to CompletableFuture.	Provide a timeout-based completion mechanism.
Behavior	Throws a TimeoutException if no result within the timeout.	Completes with a default value if no result within timeout.
Original State Change	Does not alter the original CompletableFuture's.	Alters the original CompletableFuture's state.
Handling Timeouts	React to timeouts by handling exceptions.	Trigger an alternative flow without raising exceptions.
Use Cases	Ideal for cases where timeout implies a significant issue.	Suitable when timeouts are anticipated and need handling.
Example Use	Network requests where timeout signifies a problem.	Real-time dashboard displaying cached data on timeout.
Exception Handling	Throws Exception	Provides Value Replacement
How Timeouts Are Handled	Throws a TimeoutException that needs to be caught and handled using try-catch or exception propagation.	Completes with a default value that can be directly used, avoiding the need for exception handling.
Original Future State	Unaffected	Altered
Effect on Initial CompletableFuture	Does not modify the original CompletableFuture instance; timeout behavior is added externally.	Modifies the original CompletableFuture's state by completing it with a default value.
Exception Type	TimeoutException	No New Exception Types
Exception Type Introduced for Timeouts	Introduces a TimeoutException type specifically for handling timeouts caused by this method.	No new exception types are introduced by this method.
Dependency on Completion Stage	Attached to CompletableFuture.	Independent of Completion Stage.
Method Attachment Requirement	Requires an initial CompletableFuture to attach the orTimeout() method.	Can be used independently on any CompletableFuture instance.
CompletableFuture Creation	New CompletableFuture Creation.	Alteration of Existing CompletableFuture.
Creation of Alternative CompletableFuture	If a timeout occurs, you might need to create a new CompletableFuture to handle the alternative flow.	Changes the existing CompletableFuture's content and state upon timeout.
Value on Timeout	N/A	Value on Timeout
Specifying Value on Timeout	Does not provide a way to specify a value for the CompletableFuture upon timeout.	Allows specifying a default value to complete the CompletableFuture with when a timeout occurs.
Chaining and Pipelining	Suitable for Pipelining.	Less Suited for Pipelining.
Pipelining Support	May be more suitable for chaining and composing multiple CompletableFuture operations.	The altered state might not be suitable for smooth pipelining of multiple CompletableFuture operations.
Timeout Exception Handling Flexibility	Limited Flexibility	Fallback Value Customization
Customizing Exception Handling on Timeout	Provides a specific exception type (TimeoutException) for handling timeouts distinctly.	Allows customization of the fallback value based on your application's needs.
Custom Actions on Timeout	Limited Custom Actions	Custom Actions on Timeout
Defining Actions Beyond Timeout	The primary action on timeout is raising a TimeoutException. Limited ability to customize this behavior.	Offers more flexibility to define alternative actions when a timeout occurs, including providing fallback values.
Timeout Impact on Future Completion	No Impact on Completion.	Potential Early Completion.
Completion Timing Impact	Timeout handling does not impact the original CompletableFuture's completion.	Completes the CompletableFuture with the default value as soon as the timeout is reached, potentially leading to earlier completion.

Use of orTimeout() Method

OrTimeoutExample.java

import java.util.concurrent.CompletableFuture;
import java.util.concurrent.TimeUnit;
public class OrTimeoutExample {
    public static void main(String[] args) {
        CompletableFuture<String> future = CompletableFuture.supplyAsync(() -> {
            // Simulate a long-running task
            try {
                TimeUnit.SECONDS.sleep(5);
            } catch (InterruptedException e) {
                e.printStackTrace();
            }
            return "Task completed successfully!";
        });
        try {
            String result = future.orTimeout(3, TimeUnit.SECONDS).join();
            System.out.println(result);
        } catch (Exception e) {
            System.out.println("Task did not complete within the specified timeout.");
        }
    }
}

Output:

Task did not complete within the specified timeout.

Use of completeOnTimeout() Method

CompleteOnTimeoutExample.java

import java.util.concurrent.CompletableFuture;
import java.util.concurrent.TimeUnit;
public class CompleteOnTimeoutExample {
    public static void main(String[] args) {
        CompletableFuture<String> future = CompletableFuture.supplyAsync(() -> {
            // Simulate a long-running task
            try {
                TimeUnit.SECONDS.sleep(5);
            } catch (InterruptedException e) {
                e.printStackTrace();
            }
            return "Task completed successfully!";
        });
        String defaultResult = "Fallback: Task did not complete within the specified timeout.";
        CompletableFuture<String> completedFuture = future.completeOnTimeout(defaultResult, 3, TimeUnit.SECONDS);
        String result = completedFuture.join();
        System.out.println(result);
    }
}

Output:

Fallback: Task did not complete within the specified timeout.

Conclusion

In Java 9, the introduction of orTimeout() and completeOnTimeout() methods brings a valuable enhancement to CompletableFuture handling in scenarios involving timeouts. Understanding the differences between these methods is crucial for effectively managing asynchronous operations. By utilizing these methods appropriately, developers can create more robust and responsive applications that gracefully handle timeouts without sacrificing user experience.

Next TopicDisadvantages of Array in Java

← prev next →