CompletableFuture provides several ways to handle exceptions gracefully. Here's a comprehensive guide:

Basic Exception Handling Methods

1. exceptionally() - Basic Exception Recovery

import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutionException;
public class BasicExceptionHandling {
public static void main(String[] args) throws ExecutionException, InterruptedException {
CompletableFuture<String> future = CompletableFuture.supplyAsync(() -> {
if (Math.random() > 0.5) {
throw new RuntimeException("Something went wrong!");
}
return "Success!";
});
// Handle exceptions with exceptionally()
CompletableFuture<String> safeFuture = future.exceptionally(ex -> {
System.out.println("Exception caught: " + ex.getMessage());
return "Default Value";
});
System.out.println("Result: " + safeFuture.get());
}
}

2. handle() - Handle Both Success and Exception

public class HandleMethodExample {
public static void main(String[] args) throws ExecutionException, InterruptedException {
CompletableFuture<Integer> future = CompletableFuture.supplyAsync(() -> {
int number = (int) (Math.random() * 10);
if (number % 2 == 0) {
throw new RuntimeException("Even numbers are not allowed: " + number);
}
return number;
});
CompletableFuture<String> handled = future.handle((result, ex) -> {
if (ex != null) {
return "Error: " + ex.getMessage();
} else {
return "Success: " + result;
}
});
System.out.println(handled.get());
}
}

3. whenComplete() - Side Effects Without Recovery

public class WhenCompleteExample {
public static void main(String[] args) {
CompletableFuture<Integer> future = CompletableFuture.supplyAsync(() -> {
int num = Integer.parseInt("NOT_A_NUMBER"); // This will throw NumberFormatException
return num * 2;
});
CompletableFuture<Void> logged = future.whenComplete((result, ex) -> {
if (ex != null) {
System.err.println("Task failed with: " + ex.getClass().getSimpleName());
// Can't recover here, just log
} else {
System.out.println("Task completed with: " + result);
}
});
try {
logged.get();
} catch (Exception e) {
System.out.println("Exception still propagates: " + e.getCause());
}
}
}

Advanced Exception Handling Patterns

4. Chaining Exception Handling

public class ChainedExceptionHandling {
public static void main(String[] args) throws ExecutionException, InterruptedException {
CompletableFuture<String> pipeline = CompletableFuture
.supplyAsync(() -> {
System.out.println("Step 1: Data extraction");
if (Math.random() > 0.7) {
throw new RuntimeException("Extraction failed");
}
return "Raw Data";
})
.thenApplyAsync(data -> {
System.out.println("Step 2: Data processing - " + data);
if (Math.random() > 0.7) {
throw new RuntimeException("Processing failed");
}
return data.toUpperCase();
})
.thenApplyAsync(data -> {
System.out.println("Step 3: Data transformation - " + data);
if (Math.random() > 0.7) {
throw new RuntimeException("Transformation failed");
}
return data + " - TRANSFORMED";
})
.exceptionally(ex -> {
System.err.println("Pipeline failed at some stage: " + ex.getMessage());
return "Fallback Result";
})
.thenApply(result -> {
System.out.println("Final step with: " + result);
return result + " - COMPLETED";
});
System.out.println("Final result: " + pipeline.get());
}
}

5. Retry Mechanism with CompletableFuture

import java.util.concurrent.CompletableFuture;
import java.util.concurrent.atomic.AtomicInteger;
public class RetryMechanism {
public static <T> CompletableFuture<T> withRetry(
Supplier<CompletableFuture<T>> task, 
int maxRetries, 
long delayMs) {
AtomicInteger retries = new AtomicInteger(0);
CompletableFuture<T> result = new CompletableFuture<>();
retry(task, maxRetries, delayMs, retries, result);
return result;
}
private static <T> void retry(
Supplier<CompletableFuture<T>> task,
int maxRetries,
long delayMs,
AtomicInteger retries,
CompletableFuture<T> result) {
task.get().whenComplete((success, error) -> {
if (error != null) {
int currentRetry = retries.incrementAndGet();
if (currentRetry <= maxRetries) {
System.out.println("Retry attempt " + currentRetry + " after error: " + error.getMessage());
CompletableFuture.delayedExecutor(delayMs, TimeUnit.MILLISECONDS)
.execute(() -> retry(task, maxRetries, delayMs, retries, result));
} else {
result.completeExceptionally(error);
}
} else {
result.complete(success);
}
});
}
public static void main(String[] args) throws Exception {
AtomicInteger attempt = new AtomicInteger(0);
CompletableFuture<String> retryFuture = withRetry(() -> {
return CompletableFuture.supplyAsync(() -> {
int currentAttempt = attempt.incrementAndGet();
if (currentAttempt < 3) {
throw new RuntimeException("Simulated failure on attempt " + currentAttempt);
}
return "Success on attempt " + currentAttempt;
});
}, 3, 1000); // 3 retries, 1 second delay
System.out.println("Final result: " + retryFuture.get());
}
}

6. Timeout Handling

import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ScheduledExecutorService;
import java.util.concurrent.Executors;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;
public class TimeoutHandling {
private static final ScheduledExecutorService scheduler = 
Executors.newScheduledThreadPool(1);
public static <T> CompletableFuture<T> withTimeout(
CompletableFuture<T> future, 
long timeout, 
TimeUnit unit) {
return future.orTimeout(timeout, unit)
.exceptionally(ex -> {
if (ex instanceof TimeoutException) {
System.err.println("Task timed out after " + timeout + " " + unit);
// Return default value or throw custom exception
return null; // or throw new CustomTimeoutException();
}
throw new CompletionException(ex);
});
}
// Alternative manual timeout implementation
public static <T> CompletableFuture<T> withTimeoutManual(
CompletableFuture<T> future, 
long timeout, 
TimeUnit unit,
T defaultValue) {
CompletableFuture<T> timeoutFuture = new CompletableFuture<>();
scheduler.schedule(() -> {
if (!future.isDone()) {
timeoutFuture.complete(defaultValue);
future.cancel(true);
}
}, timeout, unit);
return future.applyToEither(timeoutFuture, Function.identity())
.exceptionally(ex -> {
if (ex instanceof CancellationException) {
System.out.println("Task was cancelled due to timeout");
return defaultValue;
}
throw new CompletionException(ex);
});
}
public static void main(String[] args) throws Exception {
CompletableFuture<String> slowTask = CompletableFuture.supplyAsync(() -> {
try {
Thread.sleep(3000); // Simulate slow task
return "Slow Result";
} catch (InterruptedException e) {
throw new RuntimeException(e);
}
});
// Using orTimeout (Java 9+)
CompletableFuture<String> withTimeout = withTimeout(slowTask, 2, TimeUnit.SECONDS);
try {
System.out.println("Result: " + withTimeout.get());
} catch (ExecutionException e) {
System.out.println("Exception: " + e.getCause());
}
}
}

Real-World Examples

7. API Call with Fallback

import java.util.concurrent.CompletableFuture;
public class ApiCallWithFallback {
public CompletableFuture<String> callPrimaryApi(String request) {
return CompletableFuture.supplyAsync(() -> {
// Simulate API call
if (Math.random() > 0.3) {
throw new RuntimeException("Primary API unavailable");
}
return "Response from Primary API for: " + request;
});
}
public CompletableFuture<String> callFallbackApi(String request) {
return CompletableFuture.supplyAsync(() -> {
// Simulate fallback API call
if (Math.random() > 0.2) {
throw new RuntimeException("Fallback API also unavailable");
}
return "Response from Fallback API for: " + request;
});
}
public CompletableFuture<String> callApiWithFallback(String request) {
return callPrimaryApi(request)
.exceptionallyCompose(primaryEx -> {
System.out.println("Primary API failed: " + primaryEx.getMessage());
System.out.println("Trying fallback API...");
return callFallbackApi(request);
})
.exceptionally(ex -> {
System.err.println("All APIs failed: " + ex.getMessage());
return "Default Response";
});
}
public static void main(String[] args) throws Exception {
ApiCallWithFallback client = new ApiCallWithFallback();
CompletableFuture<String> response = client.callApiWithFallback("test-request");
System.out.println("Final response: " + response.get());
}
}

8. Bulk Operations with Individual Exception Handling

import java.util.*;
import java.util.concurrent.*;
import java.util.stream.*;
public class BulkOperations {
public static List<CompletableFuture<String>> processItems(List<String> items) {
return items.stream()
.map(item -> CompletableFuture.supplyAsync(() -> processItem(item))
.exceptionally(ex -> "Failed for " + item + ": " + ex.getMessage()))
.collect(Collectors.toList());
}
private static String processItem(String item) {
if (item.startsWith("fail")) {
throw new RuntimeException("Intentional failure for: " + item);
}
try {
Thread.sleep(100); // Simulate work
return item.toUpperCase();
} catch (InterruptedException e) {
throw new RuntimeException(e);
}
}
public static CompletableFuture<Void> processAllWithIndividualHandling(List<String> items) {
List<CompletableFuture<String>> futures = processItems(items);
return CompletableFuture.allOf(
futures.toArray(new CompletableFuture[0])
).thenApply(v -> {
List<String> results = futures.stream()
.map(CompletableFuture::join)
.collect(Collectors.toList());
System.out.println("All processing completed:");
results.forEach(System.out::println);
return null;
});
}
// Continue processing despite some failures
public static CompletableFuture<List<String>> processWithTolerance(List<String> items) {
List<CompletableFuture<Optional<String>>> futures = items.stream()
.map(item -> CompletableFuture.supplyAsync(() -> {
try {
return Optional.of(processItem(item));
} catch (Exception e) {
System.err.println("Item failed: " + item + " - " + e.getMessage());
return Optional.empty();
}
}))
.collect(Collectors.toList());
return CompletableFuture.allOf(futures.toArray(new CompletableFuture[0]))
.thenApply(v -> futures.stream()
.map(CompletableFuture::join)
.filter(Optional::isPresent)
.map(Optional::get)
.collect(Collectors.toList()));
}
public static void main(String[] args) throws Exception {
List<String> items = Arrays.asList("apple", "banana", "fail1", "cherry", "fail2");
processAllWithIndividualHandling(items).get();
CompletableFuture<List<String>> tolerant = processWithTolerance(items);
System.out.println("Successful results: " + tolerant.get());
}
}

9. Composition with Exception Propagation

public class CompositionWithExceptions {
public static CompletableFuture<Integer> parseNumber(String input) {
return CompletableFuture.supplyAsync(() -> {
try {
return Integer.parseInt(input);
} catch (NumberFormatException e) {
throw new RuntimeException("Invalid number: " + input, e);
}
});
}
public static CompletableFuture<Integer> doubleNumber(int number) {
return CompletableFuture.supplyAsync(() -> {
if (number > 1000) {
throw new RuntimeException("Number too large: " + number);
}
return number * 2;
});
}
public static CompletableFuture<String> processResult(int number) {
return CompletableFuture.supplyAsync(() -> {
return "Result: " + number;
});
}
public static CompletableFuture<String> processNumber(String input) {
return parseNumber(input)
.thenCompose(CompositionWithExceptions::doubleNumber)
.thenCompose(CompositionWithExceptions::processResult)
.exceptionally(ex -> {
// Handle any exception in the chain
if (ex instanceof RuntimeException) {
return "Processing failed: " + ex.getMessage();
}
return "Unexpected error: " + ex.getMessage();
});
}
// Using handle() at each stage for fine-grained control
public static CompletableFuture<String> processNumberWithStagedHandling(String input) {
return parseNumber(input)
.handle((num, ex) -> {
if (ex != null) {
System.err.println("Parsing failed");
throw new CompletionException(ex);
}
return num;
})
.thenCompose(CompositionWithExceptions::doubleNumber)
.handle((num, ex) -> {
if (ex != null) {
System.err.println("Doubling failed");
return -1; // Recover with default value
}
return num;
})
.thenCompose(CompositionWithExceptions::processResult);
}
public static void main(String[] args) throws Exception {
// Test valid input
CompletableFuture<String> result1 = processNumber("42");
System.out.println(result1.get());
// Test invalid input
CompletableFuture<String> result2 = processNumber("abc");
System.out.println(result2.get());
// Test large number
CompletableFuture<String> result3 = processNumber("2000");
System.out.println(result3.get());
}
}

Best Practices

1. Always handle exceptions - Don't let them propagate silently
2. Use exceptionally() for recovery - When you want to provide a fallback value
3. Use handle() for inspection - When you need to examine both result and exception
4. Use whenComplete() for side effects - When you need to log but not recover
5. Chain exception handling appropriately - Place exceptionally() where you want recovery to happen
6. Consider timeouts - Always set reasonable timeouts for async operations
7. Log exceptions appropriately - Use proper logging in exception handlers

These patterns will help you build robust asynchronous applications with proper error handling and recovery mechanisms.