Add Timeout pattern implementation - Fixes #2845

Author: dyrpsf

timeout/README.md

@@ -0,0 +1,101 @@
+# Timeout Pattern
+
+## Intent
+Prevent operations from blocking indefinitely by setting a maximum time limit for their completion. If the operation doesn't complete within the specified timeout period, it is cancelled and control is returned to the caller with an error.
+
+## Explanation
+
+Real-world example
+
+> Consider a restaurant where customers place orders. The kitchen has a policy that if a dish cannot be prepared within 30 minutes, the order is cancelled and the customer is notified. This prevents customers from waiting indefinitely and allows them to make alternative arrangements.
+
+In plain words
+
+> The Timeout pattern ensures that operations complete within a specified time limit, preventing indefinite blocking and improving system responsiveness.
+
+**Programmatic Example**
+
+The Timeout pattern is implemented using the `TimeoutHandler` class which wraps operations and enforces time constraints:
+
+```java
+TimeoutHandler handler = new TimeoutHandler();
+
+// Execute a task with 3 second timeout
+try {
+    String result = handler.execute(() -> {
+        // Simulate some processing
+        Thread.sleep(1000);
+        return "Operation completed";
+    }, 3, TimeUnit.SECONDS);
+    
+    System.out.println(result);
+} catch (TimeoutException e) {
+    System.err.println("Operation timed out: " + e.getMessage());
+}
+```
+
+The `TimeoutHandler` uses an `ExecutorService` to run tasks asynchronously and monitors their completion:
+
+```java
+public <T> T execute(Callable<T> task, long timeout, TimeUnit unit) 
+    throws TimeoutException {
+    Future<T> future = executor.submit(task);
+    
+    try {
+        return future.get(timeout, unit);
+    } catch (java.util.concurrent.TimeoutException e) {
+        future.cancel(true);
+        throw new TimeoutException("Operation timed out", e);
+    }
+}
+```
+
+## Class diagram
+
+![Timeout Pattern UML](./etc/timeout.urm.png)
+
+## Applicability
+
+Use the Timeout pattern when:
+
+- Operations might block indefinitely due to network issues, slow services, or resource contention
+- You need to maintain system responsiveness even when dependencies are slow
+- Cascading failures need to be prevented in distributed systems
+- SLA requirements mandate maximum response times
+- You want to implement circuit breaker or retry patterns
+
+## Known Uses
+
+- HTTP client libraries (setting connection and read timeouts)
+- Database connection pools (query timeouts)
+- Microservices communication (service-to-service call timeouts)
+- Message queue consumers (message processing timeouts)
+- RPC frameworks (remote procedure call timeouts)
+
+## Consequences
+
+Benefits:
+- Prevents indefinite blocking and resource exhaustion
+- Improves system responsiveness and user experience
+- Enables better error handling and recovery strategies
+- Helps maintain SLA commitments
+- Prevents cascading failures in distributed systems
+
+Trade-offs:
+- Requires careful tuning of timeout values
+- May need retry logic for transient failures
+- Can increase system complexity
+- Might cancel operations that would have eventually succeeded
+
+## Related Patterns
+
+- Circuit Breaker: Often used together; circuit breaker opens after multiple timeout failures
+- Retry: Used to handle timeout exceptions by retrying the operation
+- Bulkhead: Isolates resources to prevent timeout cascades
+- Async Method Invocation: Provides non-blocking execution with timeout support
+
+## Credits
+
+- [Microsoft Azure - Timeout Pattern](https://docs.microsoft.com/en-us/azure/architecture/patterns/timeout)
+- [Release It!: Design and Deploy Production-Ready Software](https://www.amazon.com/Release-Design-Deploy-Production-Ready-Software/dp/1680502395)
+- [Building Microservices: Designing Fine-Grained Systems](https://www.amazon.com/Building-Microservices-Designing-Fine-Grained-Systems/dp/1491950358)

timeout/etc/timeout.urm.png.png

@@ -0,0 +1,37 @@
+@startuml
+package com.iluwatar.timeout {
+  
+  class TimeoutException {
+    + TimeoutException(message: String)
+    + TimeoutException(message: String, cause: Throwable)
+  }
+  
+  class TimeoutHandler {
+    - executor: ExecutorService
+    + TimeoutHandler()
+    + execute(task: Callable<T>, timeout: long, unit: TimeUnit): T
+    + shutdown(): void
+  }
+  
+  class App {
+    + {static} main(args: String[]): void
+  }
+  
+  TimeoutHandler ..> TimeoutException : throws
+  App ..> TimeoutHandler : uses
+  App ..> TimeoutException : catches
+}
+
+note right of TimeoutHandler
+  Executes tasks with timeout constraints.
+  Uses ExecutorService to run tasks
+  asynchronously and enforce time limits.
+end note
+
+note right of TimeoutException
+  Custom exception thrown when
+  an operation exceeds its
+  timeout duration.
+end note
+
+@enduml

timeout/etc/timeout.urm.puml

@@ -0,0 +1,32 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+  
+  <parent>
+    <groupId>com.iluwatar</groupId>
+    <artifactId>java-design-patterns</artifactId>
+    <version>1.26.0-SNAPSHOT</version>
+  </parent>
+  
+  <artifactId>timeout</artifactId>
+  <packaging>jar</packaging>
+  
+  <dependencies>
+    <dependency>
+      <groupId>org.projectlombok</groupId>
+      <artifactId>lombok</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>ch.qos.logback</groupId>
+      <artifactId>logback-classic</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.junit.jupiter</groupId>
+      <artifactId>junit-jupiter-engine</artifactId>
+      <scope>test</scope>
+    </dependency>
+  </dependencies>
+  
+</project>