{"title":"CompletableFuture","description":null,"content":"# CompletableFuture\n\nYou call an external API. While waiting for the response, your thread sits idle. Wasted.\n\nTraditional Futures force you to block. Call `get()` and your thread waits, doing nothing until the result arrives. With multiple async operations, you either block sequentially (slow) or manage callbacks manually (messy).\n\n**CompletableFuture** solves this. It lets you chain operations, combine results, and handle errors, all without blocking. When one operation completes, the next starts automatically.\n\nIn this article, we'll explore:\n\n- Why traditional Futures fall short\n- How CompletableFuture enables non-blocking async code\n- Chaining, combining, and composing operations\n- Error handling strategies\n- Common patterns and pitfalls\n\n---\n\nIf you're enjoying this newsletter and want to get even more value, consider becoming a **[paid subscriber](https://blog.algomaster.io/subscribe)**.\n\nAs a paid subscriber, you'll unlock all **premium articles** and gain full access to all **[premium courses](https://algomaster.io/newsletter/paid/resources)** on **[algomaster.io](https://algomaster.io)**.\n\n[Unlock Full Access](undefined)\n\n---\n\n## 1. The Problem with Traditional Futures\n\nA regular Future represents a pending result. But to get that result, you must block.\n\n\n```java\nFuture future = executor.submit(() -> fetchUser(userId));\n\n// Thread blocks here, doing nothing\nUser user = future.get(); // Waiting...\n\n// Can't do anything until get() returns\nprocessUser(user);\n```\n\n\n### Problems with Blocking\n\n\n```mermaid\nflowchart LR\n subgraph Blocking[\"Traditional Future (Blocking)\"]\n Submit[\"Submit task\"]\n Wait[\"get() - Thread blocked\"]\n Process[\"Process result\"]\n Submit --> Wait --> Process\n end\n\n subgraph Resource[\"Thread State\"]\n Idle[\"Thread idle
consuming memory
doing nothing\"]\n end\n\n Wait --> Idle\n\n style Blocking fill:#ff8787,stroke:#000,color:#000\n style Wait fill:#ffa94d,stroke:#000,color:#000\n style Idle fill:#9775fa,stroke:#000,color:#000\n```\n\n\n**Sequential blocking kills performance:**\n\n\n```java\n// Three API calls, each takes 1 second\n// Total time: 3 seconds (sequential blocking)\nUser user = fetchUser(id).get(); // 1 sec wait\nOrders orders = fetchOrders(user).get(); // 1 sec wait\nPayment payment = fetchPayment(user).get(); // 1 sec wait\n```\n\n\n**Combining results is awkward:**\n\n\n```java\nFuture futureA = executor.submit(() -> computeA());\nFuture futureB = executor.submit(() -> computeB());\n\n// Must block on each, no elegant way to combine\nInteger a = futureA.get();\nInteger b = futureB.get();\nInteger result = a + b;\n```\n\n\n**No built-in error handling:**\n\n\n```java\ntry {\n result = future.get();\n} catch (ExecutionException e) {\n // Manual exception handling\n // No way to provide fallback value in the chain\n}\n```\n\n\n---\n\n## 2. What is CompletableFuture?\n\n**CompletableFuture** is a Future that can be:\n\n- **Completed manually** (not just by executor)\n- **Chained** with callbacks that run when it completes\n- **Combined** with other CompletableFutures\n- **Composed** into pipelines of async operations\n\n\n```mermaid\nflowchart LR\n subgraph CF[\"CompletableFuture\"]\n Stage1[\"Operation 1\"]\n Stage2[\"Operation 2\"]\n Stage3[\"Operation 3\"]\n Result[\"Final Result\"]\n\n Stage1 -->|\"completes\"| Stage2\n Stage2 -->|\"completes\"| Stage3\n Stage3 -->|\"completes\"| Result\n end\n\n Note[\"No blocking between stages
Each stage triggers the next\"]\n\n style CF fill:#69db7c,stroke:#000,color:#000\n style Stage1 fill:#00ceff,stroke:#000,color:#000\n style Stage2 fill:#00ceff,stroke:#000,color:#000\n style Stage3 fill:#00ceff,stroke:#000,color:#000\n style Result fill:#ffa94d,stroke:#000,color:#000\n```\n\n\n### Non-Blocking Chaining\n\n\n```java\nCompletableFuture.supplyAsync(() -> fetchUser(userId))\n .thenApply(user -> fetchOrders(user)) // Runs when user is ready\n .thenApply(orders -> calculateTotal(orders)) // Runs when orders ready\n .thenAccept(total -> sendEmail(total)); // Runs when total ready\n\n// No blocking! Thread continues immediately\n// Callbacks execute as results become available\n```\n\n\n---\n\n## 3. Creating CompletableFutures\n\n### From Async Computation\n\n\n```java\n// Run task asynchronously, return result\nCompletableFuture future = CompletableFuture.supplyAsync(() -> {\n return fetchUserFromDatabase(userId);\n});\n\n// Run task asynchronously, no result\nCompletableFuture future = CompletableFuture.runAsync(() -> {\n sendNotification();\n});\n```\n\n\n### Completed Immediately\n\n\n```java\n// Already completed with value\nCompletableFuture future = CompletableFuture.completedFuture(\"result\");\n\n// Already failed\nCompletableFuture failed = CompletableFuture.failedFuture(new Exception(\"error\"));\n```\n\n\n### Manual Completion\n\n\n```java\nCompletableFuture future = new CompletableFuture<>();\n\n// Somewhere else in code (e.g., callback from external system)\nfuture.complete(\"result\"); // Complete successfully\n// or\nfuture.completeExceptionally(new Exception(\"failed\"));\n```\n\n\n\n```mermaid\nflowchart TD\n subgraph Creation[\"Creating CompletableFuture\"]\n Async[\"supplyAsync()
runAsync()\"]\n Completed[\"completedFuture()
failedFuture()\"]\n Manual[\"new + complete()\"]\n end\n\n Async -->|\"Runs in thread pool\"| Running[\"Running\"]\n Completed -->|\"Immediate\"| Done[\"Completed\"]\n Manual -->|\"External trigger\"| Pending[\"Pending\"]\n\n style Creation fill:#00ceff,stroke:#000,color:#000\n style Async fill:#69db7c,stroke:#000,color:#000\n style Completed fill:#ffa94d,stroke:#000,color:#000\n style Manual fill:#9775fa,stroke:#000,color:#000\n```\n\n\n---\n\n## 4. Chaining Operations\n\nCompletableFuture provides three main methods for chaining based on what you need from the result.\n\n### thenApply: Transform Result\n\nTakes the result, returns a transformed value.\n\n\n```java\nCompletableFuture future = CompletableFuture\n .supplyAsync(() -> fetchUser(id)) // Returns User\n .thenApply(user -> user.getName()) // User -> String\n .thenApply(name -> name.toUpperCase()); // String -> String\n```\n\n\n\n```mermaid\nflowchart LR\n A[\"supplyAsync
() -> User\"]\n B[\"thenApply
User -> String\"]\n C[\"thenApply
String -> String\"]\n Result[\"CompletableFuture<String>\"]\n\n A -->|\"User\"| B\n B -->|\"String\"| C\n C -->|\"String\"| Result\n\n style A fill:#00ceff,stroke:#000,color:#000\n style B fill:#69db7c,stroke:#000,color:#000\n style C fill:#69db7c,stroke:#000,color:#000\n style Result fill:#ffa94d,stroke:#000,color:#000\n```\n\n\n### thenAccept: Consume Result\n\nTakes the result, returns nothing (void).\n\n\n```java\nCompletableFuture future = CompletableFuture\n .supplyAsync(() -> fetchUser(id))\n .thenAccept(user -> saveToCache(user)); // Consumes user, returns void\n```\n\n\n### thenRun: Run After Completion\n\nIgnores the result, just runs after completion.\n\n\n```java\nCompletableFuture future = CompletableFuture\n .supplyAsync(() -> fetchUser(id))\n .thenRun(() -> log(\"User fetched\")); // Ignores result\n```\n\n\n### Summary\n\n\n| ##### Method | ##### Input | ##### Output | ##### Use Case |\n| --- | --- | --- | --- |\n| `thenApply` | Result | New value | Transform data |\n| `thenAccept` | Result | Void | Consume/process data |\n| `thenRun` | Nothing | Void | Run side effect |\n\n\n---\n\n## 5. Combining Multiple Futures\n\n### thenCombine: Combine Two Independent Results\n\nWait for two futures, combine their results.\n\n\n```java\nCompletableFuture userFuture = CompletableFuture.supplyAsync(() -> fetchUser(id));\nCompletableFuture ordersFuture = CompletableFuture.supplyAsync(() -> fetchOrders(id));\n\nCompletableFuture

combined = userFuture.thenCombine(\n ordersFuture,\n (user, orders) -> new Summary(user, orders) // Combine when both ready\n);\n```\n\n\n\n```mermaid\nflowchart TD\n User[\"fetchUser()\"]\n Orders[\"fetchOrders()\"]\n Combine[\"thenCombine
(user, orders) -> Summary\"]\n Result[\"CompletableFuture<Summary>\"]\n\n User --> Combine\n Orders --> Combine\n Combine --> Result\n\n style User fill:#00ceff,stroke:#000,color:#000\n style Orders fill:#00ceff,stroke:#000,color:#000\n style Combine fill:#69db7c,stroke:#000,color:#000\n style Result fill:#ffa94d,stroke:#000,color:#000\n```\n\n\n### thenCompose: Chain Dependent Futures\n\nWhen one async operation depends on another's result (flatMap).\n\n\n```java\n// Wrong: thenApply creates nested future\nCompletableFuture> nested =\n fetchUser(id).thenApply(user -> fetchOrders(user.getId()));\n\n// Right: thenCompose flattens it\nCompletableFuture flat =\n fetchUser(id).thenCompose(user -> fetchOrders(user.getId()));\n```\n\n\n\n```mermaid\nflowchart LR\n subgraph ThenApply[\"thenApply (Wrong)\"]\n A1[\"Future<User>\"]\n A2[\"Future<Future<Orders>>\"]\n A1 -->|\"thenApply\"| A2\n end\n\n subgraph ThenCompose[\"thenCompose (Right)\"]\n B1[\"Future<User>\"]\n B2[\"Future<Orders>\"]\n B1 -->|\"thenCompose\"| B2\n end\n\n style ThenApply fill:#ff8787,stroke:#000,color:#000\n style ThenCompose fill:#69db7c,stroke:#000,color:#000\n```\n\n\n### allOf: Wait for All\n\nWait for multiple futures to complete.\n\n\n```java\nCompletableFuture f1 = fetchUser(id1);\nCompletableFuture f2 = fetchUser(id2);\nCompletableFuture f3 = fetchUser(id3);\n\nCompletableFuture all = CompletableFuture.allOf(f1, f2, f3);\n\nall.thenRun(() -> {\n // All completed, get results\n User u1 = f1.join();\n User u2 = f2.join();\n User u3 = f3.join();\n});\n```\n\n\n### anyOf: First to Complete\n\nReturns when any future completes.\n\n\n```java\nCompletableFuture

CompletableFuture

Ashish Pratap Singh

Get Premium