🟢 Junior Level

orTimeout() — completes a CompletableFuture with a TimeoutException if it hasn’t completed within the specified time.

CompletableFuture<String> cf = fetchDataAsync();

// 5 second timeout
cf.orTimeout(5, TimeUnit.SECONDS)
  .thenAccept(result -> System.out.println(result))
  .exceptionally(ex -> {
      // TimeoutException if not done within 5 seconds
      System.out.println("Timeout!");
      return "fallback";
  });

---

🟡 Middle Level

How it works

cf.orTimeout(5, TimeUnit.SECONDS);

// If cf completed within 5 seconds — OK
// If not — CF completes with TimeoutException

completeOnTimeout — alternative:

// orTimeout — exception on timeout
cf.orTimeout(5, TimeUnit.SECONDS);

// completeOnTimeout — fallback value on timeout
cf.completeOnTimeout("default", 5, TimeUnit.SECONDS);

Typical mistakes

1. Task continues executing: ```java cf.orTimeout(5, TimeUnit.SECONDS);

// CF completes with TimeoutException // But the task in the executor keeps running!

---

## 🔴 Senior Level

### Internal Implementation

```java
public CompletableFuture<T> orTimeout(long timeout, TimeUnit unit) {
    if (result == null)
        whenComplete(timeoutFuture(timeout, unit));
    return this;
}

// Uses ScheduledExecutorService for delayed completion

Performance

orTimeout overhead:
(Java 21, single-threaded benchmark). For comparison: a typical HTTP call
takes 10-100ms, so the timeout overhead (~1μs) is less than 0.01%.

Best Practices

// ✅ orTimeout for Java 9+
cf.orTimeout(5, TimeUnit.SECONDS);

// ✅ completeOnTimeout for fallback
cf.completeOnTimeout(defaultValue, 5, TimeUnit.SECONDS);

// ❌ Expecting the task to be cancelled
// ❌ Timeout without handling TimeoutException

---

🎯 Interview Cheat Sheet

Must know:

• orTimeout(timeout, unit) — completes CF with TimeoutException when time is exceeded
• completeOnTimeout(value, timeout, unit) — alternative with a fallback value
• Uses ScheduledExecutorService internally for delayed completion
• Timeout does NOT cancel the task — it continues working in the executor
• whenComplete(cancel) on normal completion cancels the scheduled task

Common follow-up questions:

• Does orTimeout cancel the task in the executor? — No, CF completes, task continues working
• orTimeout vs completeOnTimeout? — orTimeout throws TimeoutException, completeOnTimeout returns fallback
• orTimeout overhead? — ~1μs, negligible compared to an HTTP call (10-100ms)
• Java 8 alternative? — ScheduledExecutorService + anyOf(cf, timeoutCF)

Red flags (DO NOT say):

• “orTimeout stops the task” — only completes the CF, task keeps running
• “orTimeout is available in Java 8” — only available from Java 9
• “TimeoutException can be ignored” — needs fallback or retry

Related topics:

• [[21. How to implement timeout for CompletableFuture]]
• [[10. What does anyOf() method do and when is it useful]]
• [[27. How to implement retry logic with CompletableFuture]]
• [[16. How to properly execute multiple parallel requests to microservices]]