CompletableFuture

🔍 What Is It?

CompletableFuture API:

Creating:

• →supplyAsync(Supplier) — async, returns value
• →runAsync(Runnable) — async, no return value
• →completedFuture(value) — already completed with value

Transforming result:

• →thenApply(Function) — transform result (like Stream.map)
• →thenCompose(Function<T, CompletableFuture<U>>) — chain async operations (like flatMap)
• →thenAccept(Consumer) — consume result, no return
• →thenRun(Runnable) — run after completion, ignores result

Combining:

• →thenCombine(other, BiFunction) — combine two futures when both complete
• →allOf(futures...) — wait for all to complete
• →anyOf(futures...) — complete when first finishes

Exception handling:

• →exceptionally(Function<Throwable, T>) — recover from exception
• →handle(BiFunction<T, Throwable, U>) — handle both result and exception
• →whenComplete(BiConsumer) — side effect on completion (success or failure)

Async variants:

• →thenApplyAsync, thenComposeAsync etc. — run callback in executor (not inline)

🎯 Why Do We Need It?

CompletableFuture solves the "callback hell" of raw threads and the blocking of Future.get():

// Old Future: blocking
Future<User> userFuture = executor.submit(() -> fetchUser(id));
Future<Orders> ordersFuture = executor.submit(() -> fetchOrders(id));
User user = userFuture.get();    // blocks!
Orders orders = ordersFuture.get();  // blocks!

// CompletableFuture: non-blocking composition
CompletableFuture<User> userFuture = CompletableFuture.supplyAsync(() -> fetchUser(id));
CompletableFuture<Orders> ordersFuture = CompletableFuture.supplyAsync(() -> fetchOrders(id));
CompletableFuture.allOf(userFuture, ordersFuture)
    .thenRun(() -> {
        User user = userFuture.join();
        Orders orders = ordersFuture.join();
        buildResponse(user, orders);
    });

🏗️ What Happens in Real Projects?

Common in enterprise microservices:

• →Parallel API calls to multiple services
• →Async database operations
• →Spring @Async methods returning CompletableFuture
• →Non-blocking HTTP clients (WebClient)

⚙️ How It Works

Execution model:

By default, CompletableFuture.supplyAsync() uses ForkJoinPool.commonPool(). For production, always provide your own executor to control thread count and naming.

thenApply vs thenApplyAsync:

• →thenApply: callback runs in the same thread that completed the future (or the calling thread if already complete)
• →thenApplyAsync: callback runs in the executor (ForkJoinPool or provided executor)
• →For I/O operations in callbacks, use Async variants to avoid blocking the completing thread

💻 Example

CompletableFuture in Enterprise Code — Async patterns for microservice communication and parallel operations.

// Parallel API calls — much faster than sequential
public CompletableFuture<OrderSummary> getOrderSummary(Long orderId) {
    ExecutorService executor = Executors.newFixedThreadPool(10);
    
    // Start all three calls simultaneously
    CompletableFuture<Order> orderFuture = 
        CompletableFuture.supplyAsync(() -> orderService.getOrder(orderId), executor);
    
    CompletableFuture<Customer> customerFuture = orderFuture
        .thenComposeAsync(order -> 
            CompletableFuture.supplyAsync(
                () -> customerService.getCustomer(order.getCustomerId()), executor
            ), executor);
    
    CompletableFuture<List<Product>> productsFuture = orderFuture
        .thenComposeAsync(order ->
            CompletableFuture.supplyAsync(
                () -> productService.getProducts(order.getProductIds()), executor
            ), executor);
    
    // Combine when all complete
    return orderFuture.thenCombineAsync(
        customerFuture.thenCombineAsync(
            productsFuture,
            (customer, products) -> new CustomerProducts(customer, products),
            executor
        ),
        (order, cp) -> new OrderSummary(order, cp.customer(), cp.products()),
        executor
    );
}

// Exception handling
public CompletableFuture<String> fetchWithFallback(String userId) {
    return CompletableFuture.supplyAsync(() -> primaryService.fetch(userId))
        .exceptionally(ex -> {
            log.warn("Primary service failed: {}, using fallback", ex.getMessage());
            return fallbackService.fetch(userId);  // fallback value
        });
}

// handle — process both success and failure
public CompletableFuture<ApiResponse> callApi(String url) {
    return CompletableFuture.supplyAsync(() -> httpClient.get(url))
        .handle((result, ex) -> {
            if (ex != null) {
                return ApiResponse.error(ex.getMessage());
            }
            return ApiResponse.success(result);
        });
}

🤔 Common Confusions

🚨 Common Production Issues

✅ Best Practices

🏛️ Architect's Note

💬 Frequently Asked Questions

🎯 Key Takeaways

🔗 Related Topics

🎯 Practice this topic in interviews

↗ Where this topic fits