feat(completablefuture): add demo for async tasks with timeout and exception handling

What
- Introduced `CompletableFutureDemo` to demonstrate advanced usage of Java’s `CompletableFuture`.
- Implemented:
  - Parallel execution of two async tasks:
    - `fetchUserDetails()` → simulates network call for user profile.
    - `fetchOrderHistory()` → simulates network call for user orders (with random failure).
  - Combination of results using `thenCombine()` to merge outputs when both tasks finish.
  - Timeout handling with `applyToEither()` and a helper `timeoutAfter()` future.
  - Exception handling with `exceptionally()` to provide a safe fallback message.
- Final result is printed to console with either combined data, timeout message, or error details.

Why
- Showcases **asynchronous programming** in Java without blocking threads.
- Demonstrates:
  - Running multiple tasks concurrently (`supplyAsync`).
  - Combining dependent async results (`thenCombine`).
  - Handling unpredictable delays (`timeoutAfter`).
  - Managing failures gracefully (`exceptionally`).
- Provides a practical pattern for resilient, fault-tolerant microservice or API calls.

Logic
1. **Task Creation**
   - `CompletableFuture.supplyAsync()` runs tasks in ForkJoinPool common pool threads.
   - Two tasks:
     - `fetchUserDetails()` → sleeps 1s, returns user string.
     - `fetchOrderHistory()` → sleeps 1.5s, randomly fails 30% of the time.

2. **Result Combination**
   - `thenCombine(userFuture, orderFuture, ...)` merges results once both complete.
   - Produces a formatted output containing both user and order data.

3. **Timeout Handling**
   - `timeoutAfter(2)` starts another async future that waits 2s before returning `"Request timed out!"`.
   - `applyToEither(combinedFuture, timeoutFuture)` ensures whichever completes first is used.
   - Prevents hanging if services are too slow.

4. **Exception Handling**
   - `exceptionally(ex -> "Error fetching data: ...")` ensures program never crashes.
   - Converts runtime exceptions (like service failure) into safe user-facing messages.

5. **Final Execution**
   - `join()` waits for result, returning either:
     - Successful combined data,
     - Timeout message,
     - Or error fallback.

Real-life applications
- Microservices orchestration: Fetching data from multiple APIs in parallel with timeouts.
- E-commerce systems: Get user profile + order/cart details concurrently.
- Mobile/Frontend backends: Aggregate slow services without blocking UI.
- Fault-tolerant distributed systems: Ensure safe defaults when some services fail.

Notes
- Default async execution uses ForkJoinPool’s common pool; can supply custom executors for better scaling.
- `applyToEither()` races futures → useful for fallback/timeout patterns.
- Always handle exceptions (`exceptionally` or `handle`) in production-grade async flows.
- Random failure in `fetchOrderHistory()` mimics real-world flaky services.

Signed-off-by: https://github.com/Someshdiwan <[email protected]>

Author: Someshdiwan

JAVA8/CompletableFuture/src/CompletableFutureAdvancedExample.java renamed to Java 8 Crash Course/Completable Future/src/CompletableFutureDemo.java

@@ -1,6 +1,6 @@
 import java.util.concurrent.*;
 
-public class CompletableFutureAdvancedExample {
+public class CompletableFutureDemo {
     public static void main(String[] args) {
         // Start both tasks in parallel
         CompletableFuture<String> userFuture = CompletableFuture.supplyAsync(() -> fetchUserDetails());
@@ -23,7 +23,7 @@ public static void main(String[] args) {
         System.out.println(result);
     }
 
-    // Simulates fetching user details (may be slow)
+    // Simulates fetching user details (maybe slow)
     private static String fetchUserDetails() {
         sleep(1000); // Simulate network delay
         return "John Doe, Age 30";
@@ -50,37 +50,38 @@ private static CompletableFuture<String> timeoutAfter(int seconds) {
     }
 }
 
+/*
+Complex Example: Making Parallel API Calls with Timeout & Error Handling
 
-//### **🔥 Complex Example: Making Parallel API Calls with Timeout & Error Handling**
-//#### **Scenario:**
-//We need to fetch user details and their order history **simultaneously** from two different services.
-//- **User Service** → Returns user details
-//- **Order Service** → Returns the user's past orders
-//- Both should run **in parallel**.
-//- If either fails, we should **handle errors gracefully**.
-//- If the response takes too long, we should **timeout** the request.
-//
-//### **🔍 Step-by-Step Explanation**
-//1. **Parallel Execution**:
-//   - `CompletableFuture.supplyAsync(fetchUserDetails())` runs **user service** in a separate thread.
-//   - `CompletableFuture.supplyAsync(fetchOrderHistory())` runs **order service** in parallel.
-//
-//2. **Combining Results (`thenCombine()`)**
-//   - When both futures are done, we combine the responses:
-//     - `"User: John Doe\nOrders: Laptop, Phone"`
-//
-//3. **Timeout Handling (`applyToEither()`)**
-//   - If the API call takes longer than **2 seconds**, it returns `"Request timed out!"`.
-//
-//4. **Error Handling (`exceptionally()`)**
-//   - If any API fails, it catches the exception and returns `"Error fetching data"`.
-//
-//### **📌 Why is this "Hard"?**
-//- **Runs tasks in parallel** to improve performance.
-//- **Handles failures** without crashing the app.
-//- **Implements a timeout** mechanism using `applyToEither()`.
-//- **Combines API results dynamically**.
-//
-//This is a real-world pattern used in **microservices, web applications, and high-performance systems**. 🚀
-//
-//Would you like a breakdown of any part? 😊
+Scenario:
+We need to fetch user details and their order history simultaneously from two different services.
+- User Service → returns user details.
+- Order Service → returns the user's past orders.
+- Both should run in parallel.
+- If either fails, we should handle errors gracefully.
+- If the response takes too long, we should timeout the request.
+
+Step-by-Step Explanation:
+
+1. Parallel Execution:
+   - CompletableFuture.supplyAsync(fetchUserDetails()) runs the user service in a separate thread.
+   - CompletableFuture.supplyAsync(fetchOrderHistory()) runs the order service in parallel.
+
+2. Combining Results (thenCombine):
+   - When both futures are completed, we combine the responses into a single result,
+     for example: "User: John Doe\nOrders: Laptop, Phone".
+
+3. Timeout Handling (applyToEither):
+   - If an API call takes longer than 2 seconds, it returns a default response such as "Request timed out!".
+
+4. Error Handling (exceptionally):
+   - If any API fails, the exception is caught, and a safe fallback like "Error fetching data" is returned.
+
+Why is this considered a "hard" example?
+- Tasks run in parallel, improving performance.
+- Failures are handled without crashing the application.
+- A timeout mechanism is implemented with applyToEither().
+- Results from multiple APIs are combined dynamically.
+
+This pattern is commonly used in microservices, web applications, and high-performance systems.
+*/