refactor: simplify the timeout demo and address review findings

The metrics snapshot stays sorted, a rejected submission surfaces as ServiceCallException, TimeoutRegistry is dropped and the two demo services merge into DownstreamService. The class diagram is a rendered PNG.

Author: ylcn91

timeout/README.md

@@ -59,6 +59,8 @@ sequenceDiagram
     end
 ```
 
+![Timeout class diagram](./etc/timeout.urm.png)
+
 ## Programmatic Example of Timeout Pattern in Java
 
 The example models an online shop that calls two downstream services. The product catalog is fast; the recommendation engine is slow. Each gets its own time limit.
@@ -87,34 +89,9 @@ public record TimeoutPolicy(String serviceName, Duration timeout) {
 }
 ```
 
-2. **Keep the limits configurable in one place**
+2. **Enforce the limit**
 
-   A `TimeoutRegistry` stores the policies and hands out a default for services nobody configured explicitly.
-
-```java
-public class TimeoutRegistry {
-
-  private final Map<String, TimeoutPolicy> policies = new ConcurrentHashMap<>();
-  private final Duration defaultTimeout;
-
-  public TimeoutRegistry(Duration defaultTimeout) {
-    this.defaultTimeout = Objects.requireNonNull(defaultTimeout, "defaultTimeout");
-  }
-
-  public TimeoutRegistry register(TimeoutPolicy policy) {
-    policies.put(policy.serviceName(), policy);
-    return this;
-  }
-
-  public TimeoutPolicy policyFor(String serviceName) {
-    return policies.getOrDefault(serviceName, new TimeoutPolicy(serviceName, defaultTimeout));
-  }
-}
-```
-
-3. **Enforce the limit**
-
-   `TimeoutExecutor` runs the call on a worker thread and waits for at most the configured duration. On a timeout it cancels the worker with an interrupt, logs the event, counts it in `TimeoutMetrics`, and returns the fallback. A failure raised by the service is not a timeout and is rethrown as `ServiceCallException`.
+   `TimeoutExecutor` runs the call on a worker thread and waits for at most the configured duration. On a timeout it cancels the worker with an interrupt, logs the event, counts it in `TimeoutMetrics`, and returns the fallback. A failure raised by the service, or a call the pool refuses to accept, is not a timeout and is rethrown as `ServiceCallException`.
 
 ```java
 @Slf4j
@@ -130,8 +107,9 @@ public class TimeoutExecutor implements AutoCloseable {
   public <T> T execute(TimeoutPolicy policy, Callable<T> call, Supplier<T> fallback) {
     var serviceName = policy.serviceName();
     var limitMillis = policy.timeout().toMillis();
-    var future = executor.submit(call);
+    Future<T> future = null;
     try {
+      future = executor.submit(call);
       var result = future.get(limitMillis, TimeUnit.MILLISECONDS);
       LOGGER.info("{} responded within its {} ms limit", serviceName, limitMillis);
       return result;
@@ -147,6 +125,8 @@ public class TimeoutExecutor implements AutoCloseable {
       future.cancel(true);
       Thread.currentThread().interrupt();
       throw new ServiceCallException(serviceName, e);
+    } catch (RejectedExecutionException e) {
+      throw new ServiceCallException(serviceName, e);
     }
   }
 
@@ -157,64 +137,52 @@ public class TimeoutExecutor implements AutoCloseable {
 }
 ```
 
-4. **Make the slow service cooperate with cancellation**
+3. **Make the service cooperate with cancellation**
 
-   The simulated `RecommendationService` sleeps interruptibly, so the interrupt sent by the executor actually stops the work instead of leaving it running in the background.
+   The simulated `DownstreamService` sleeps interruptibly, so the interrupt sent by the executor actually stops the work instead of leaving it running in the background. Its name, latency and payload are constructor arguments, so the same class plays both the fast catalog and the slow recommendation engine.
 
 ```java
-public List<String> recommendationsFor(String customer) throws InterruptedException {
-  LOGGER.info(
-      "{}: computing recommendations for {}, expected latency {} ms",
-      NAME,
-      customer,
-      latency.toMillis());
+public List<String> fetch() throws InterruptedException {
+  LOGGER.info("{}: responding, expected latency {} ms", name, latency.toMillis());
   try {
     Thread.sleep(latency);
   } catch (InterruptedException e) {
-    LOGGER.info("{}: interrupted, abandoning the computation for {}", NAME, customer);
+    LOGGER.info("{}: interrupted, abandoning the call", name);
     throw e;
   }
-  return List.of("Mechanical keyboard", "USB-C dock");
+  return items;
 }
 ```
 
-5. **Wire it together**
+4. **Wire it together**
 
-   `App` registers a 500 ms limit for the catalog and a 100 ms limit for recommendations. Each call lives in a small helper that pairs the policy with the call and its fallback; `main` runs both. The catalog answers in time; the recommendation engine needs 400 ms, so the customer sees popular items instead and the timeout counter shows one event.
+   `App` gives the catalog a 500 ms limit and recommendations a 100 ms one, then runs both calls through a small helper that pairs the policy with the call and its fallback. The catalog answers in time; the recommendation engine needs 400 ms, so the customer sees popular items instead and the timeout counter shows one event.
 
 ```java
-static List<String> loadProducts(
-    TimeoutExecutor executor, TimeoutRegistry registry, ProductCatalogService catalog) {
-  return executor.execute(
-      registry.policyFor(ProductCatalogService.NAME), catalog::fetchProducts, List::of);
-}
-
-static List<String> loadRecommendations(
+static List<String> call(
     TimeoutExecutor executor,
-    TimeoutRegistry registry,
-    RecommendationService recommendations,
-    String customer) {
-  return executor.execute(
-      registry.policyFor(RecommendationService.NAME),
-      () -> recommendations.recommendationsFor(customer),
-      () -> POPULAR_ITEMS);
+    TimeoutPolicy policy,
+    DownstreamService service,
+    List<String> fallback) {
+  return executor.execute(policy, service::fetch, () -> fallback);
 }
 ```
 
 ```java
-var registry =
-    new TimeoutRegistry(Duration.ofMillis(300))
-        .register(TimeoutPolicy.of(ProductCatalogService.NAME, 500))
-        .register(TimeoutPolicy.of(RecommendationService.NAME, 100));
-
-var catalog = new ProductCatalogService(Duration.ofMillis(50));
-var recommendations = new RecommendationService(Duration.ofMillis(400));
+var catalog =
+    new DownstreamService(
+        "product-catalog", Duration.ofMillis(50), List.of("Laptop", "Headphones", "Monitor"));
+var recommendations =
+    new DownstreamService(
+        "recommendations", Duration.ofMillis(400), List.of("Mechanical keyboard", "USB-C dock"));
+var catalogPolicy = TimeoutPolicy.of(catalog.name(), 500);
+var recommendationPolicy = TimeoutPolicy.of(recommendations.name(), 100);
 
 try (var executor = new TimeoutExecutor()) {
-  var products = loadProducts(executor, registry, catalog);
+  var products = call(executor, catalogPolicy, catalog, List.of());
   LOGGER.info("Products: {}", products);
 
-  var suggested = loadRecommendations(executor, registry, recommendations, "alice");
+  var suggested = call(executor, recommendationPolicy, recommendations, POPULAR_ITEMS);
   LOGGER.info("Recommendations shown to alice: {}", suggested);
 
   LOGGER.info("Timeouts per service: {}", executor.metrics().snapshot());
@@ -226,20 +194,18 @@ Running the application produces output along these lines:
 ```
 Configured per-service limits: catalog 500 ms, recommendations 100 ms
 Calling product-catalog
-product-catalog: fetching products, expected latency 50 ms
+product-catalog: responding, expected latency 50 ms
 product-catalog responded within its 500 ms limit
 Products: [Laptop, Headphones, Monitor]
 Calling recommendations
-recommendations: computing recommendations for alice, expected latency 400 ms
+recommendations: responding, expected latency 400 ms
+recommendations: interrupted, abandoning the call
 recommendations exceeded its 100 ms limit; call cancelled, using fallback
-recommendations: interrupted, abandoning the computation for alice
 Recommendations shown to alice: [Wireless mouse, Webcam]
 Timeouts per service: {recommendations=1}
 ```
 
-## Class diagram
-
-See [timeout.urm.puml](./etc/timeout.urm.puml) for the PlantUML class diagram.
+The "exceeded its 100 ms limit" line is written by the caller and the "interrupted, abandoning" line by the worker thread, so the two may appear in either order from run to run.
 
 ## When to Use the Timeout Pattern in Java
 

timeout/etc/timeout.urm.png

@@ -1,26 +1,19 @@
 @startuml
 package com.iluwatar.timeout {
-  class TimeoutPolicy {
+  class TimeoutPolicy <<record>> {
     - serviceName : String
     - timeout : Duration
     + TimeoutPolicy(serviceName : String, timeout : Duration)
     + of(serviceName : String, millis : long) : TimeoutPolicy {static}
     + serviceName() : String
     + timeout() : Duration
   }
-  class TimeoutRegistry {
-    - policies : Map<String, TimeoutPolicy>
-    - defaultTimeout : Duration
-    + TimeoutRegistry(defaultTimeout : Duration)
-    + register(policy : TimeoutPolicy) : TimeoutRegistry
-    + policyFor(serviceName : String) : TimeoutPolicy
-  }
   class TimeoutMetrics {
     - timeouts : ConcurrentMap<String, AtomicInteger>
     + TimeoutMetrics()
     + recordTimeout(serviceName : String) : void
     + timeoutCount(serviceName : String) : int
-    + snapshot() : Map<String, Integer>
+    + snapshot() : SortedMap<String, Integer>
   }
   class TimeoutExecutor {
     - executor : ExecutorService
@@ -34,32 +27,26 @@ package com.iluwatar.timeout {
   class ServiceCallException {
     + ServiceCallException(serviceName : String, cause : Throwable)
   }
-  class ProductCatalogService {
-    + NAME : String {static}
-    - latency : Duration
-    + ProductCatalogService(latency : Duration)
-    + fetchProducts() : List<String>
-  }
-  class RecommendationService {
-    + NAME : String {static}
+  class DownstreamService {
+    - name : String
     - latency : Duration
-    + RecommendationService(latency : Duration)
-    + recommendationsFor(customer : String) : List<String>
+    - items : List<String>
+    + DownstreamService(name : String, latency : Duration, items : List<String>)
+    + name() : String
+    + fetch() : List<String>
   }
   class App {
     - POPULAR_ITEMS : List<String> {static}
-    + App()
     + main(args : String[]) : void
-    ~ loadProducts(executor : TimeoutExecutor, registry : TimeoutRegistry, catalog : ProductCatalogService) : List<String> {static}
-    ~ loadRecommendations(executor : TimeoutExecutor, registry : TimeoutRegistry, recommendations : RecommendationService, customer : String) : List<String> {static}
+    ~ call(executor : TimeoutExecutor, policy : TimeoutPolicy, service : DownstreamService, fallback : List<String>) : List<String> {static}
   }
 }
+ServiceCallException --|> RuntimeException
 TimeoutExecutor --> TimeoutMetrics
 TimeoutExecutor ..> TimeoutPolicy
 TimeoutExecutor ..> ServiceCallException
-TimeoutRegistry --> "*" TimeoutPolicy
-App ..> TimeoutRegistry
+App ..> TimeoutPolicy
 App ..> TimeoutExecutor
-App ..> ProductCatalogService
-App ..> RecommendationService
+App ..> TimeoutMetrics
+App ..> DownstreamService
 @enduml

timeout/etc/timeout.urm.puml

@@ -34,9 +34,8 @@
  * system stalls. With a limit the caller abandons the slow call, records the event and continues
  * with a fallback, keeping latency predictable and failures contained.
  *
- * <p>The building blocks are a {@link TimeoutPolicy} per service, a {@link TimeoutRegistry} that
- * makes the limits configurable in one place, and a {@link TimeoutExecutor} that enforces them,
- * cancels calls that overrun, and counts timeouts in {@link TimeoutMetrics}.
+ * <p>The building blocks are a {@link TimeoutPolicy} per service and a {@link TimeoutExecutor} that
+ * enforces them, cancels calls that overrun, and counts timeouts in {@link TimeoutMetrics}.
  *
  * <p>The demo wires two services with different limits. The product catalog answers well within its
  * 500 ms budget and returns real data. The recommendation engine needs 400 ms but is only allowed
@@ -54,60 +53,45 @@ public class App {
    * @param args command line arguments, not used
    */
   public static void main(String[] args) {
-    var registry =
-        new TimeoutRegistry(Duration.ofMillis(300))
-            .register(TimeoutPolicy.of(ProductCatalogService.NAME, 500))
-            .register(TimeoutPolicy.of(RecommendationService.NAME, 100));
+    var catalog =
+        new DownstreamService(
+            "product-catalog", Duration.ofMillis(50), List.of("Laptop", "Headphones", "Monitor"));
+    var recommendations =
+        new DownstreamService(
+            "recommendations",
+            Duration.ofMillis(400),
+            List.of("Mechanical keyboard", "USB-C dock"));
+    var catalogPolicy = TimeoutPolicy.of(catalog.name(), 500);
+    var recommendationPolicy = TimeoutPolicy.of(recommendations.name(), 100);
     LOGGER.info("Configured per-service limits: catalog 500 ms, recommendations 100 ms");
 
-    var catalog = new ProductCatalogService(Duration.ofMillis(50));
-    var recommendations = new RecommendationService(Duration.ofMillis(400));
-
     try (var executor = new TimeoutExecutor()) {
-      LOGGER.info("Calling {}", ProductCatalogService.NAME);
-      var products = loadProducts(executor, registry, catalog);
+      LOGGER.info("Calling {}", catalog.name());
+      var products = call(executor, catalogPolicy, catalog, List.of());
       LOGGER.info("Products: {}", products);
 
-      LOGGER.info("Calling {}", RecommendationService.NAME);
-      var suggested = loadRecommendations(executor, registry, recommendations, "alice");
+      LOGGER.info("Calling {}", recommendations.name());
+      var suggested = call(executor, recommendationPolicy, recommendations, POPULAR_ITEMS);
       LOGGER.info("Recommendations shown to alice: {}", suggested);
 
       LOGGER.info("Timeouts per service: {}", executor.metrics().snapshot());
     }
   }
 
   /**
-   * Loads the catalog under its time limit, showing an empty catalog if the limit is exceeded.
-   *
-   * @param executor executor enforcing the limit
-   * @param registry registry holding the catalog's policy
-   * @param catalog the downstream catalog service
-   * @return the products, or an empty list on timeout
-   */
-  static List<String> loadProducts(
-      TimeoutExecutor executor, TimeoutRegistry registry, ProductCatalogService catalog) {
-    return executor.execute(
-        registry.policyFor(ProductCatalogService.NAME), catalog::fetchProducts, List::of);
-  }
-
-  /**
-   * Loads personalised recommendations under their time limit, showing popular items instead if the
-   * limit is exceeded.
+   * Calls a service under its time limit, answering with the fallback if the limit is exceeded.
    *
    * @param executor executor enforcing the limit
-   * @param registry registry holding the recommendation service's policy
-   * @param recommendations the downstream recommendation service
-   * @param customer customer to personalise for
-   * @return the recommendations, or the popular items on timeout
+   * @param policy limit that applies to the service
+   * @param service the downstream service to call
+   * @param fallback answer to use when the limit is exceeded
+   * @return the response of the service, or the fallback on timeout
    */
-  static List<String> loadRecommendations(
+  static List<String> call(
       TimeoutExecutor executor,
-      TimeoutRegistry registry,
-      RecommendationService recommendations,
-      String customer) {
-    return executor.execute(
-        registry.policyFor(RecommendationService.NAME),
-        () -> recommendations.recommendationsFor(customer),
-        () -> POPULAR_ITEMS);
+      TimeoutPolicy policy,
+      DownstreamService service,
+      List<String> fallback) {
+    return executor.execute(policy, service::fetch, () -> fallback);
   }
 }