feat: add Timeout pattern (#2845) by ylcn91 · Pull Request #3598 · iluwatar/java-design-patterns

ylcn91 · 2026-09-03T09:21:56Z

What does this PR do?

Adds the Timeout pattern as a new timeout module.

Problem: without a time limit a single slow dependency can hold threads and user requests hostage until the whole system stalls.
Solution: every downstream call runs under a per-service TimeoutPolicy. When the limit is exceeded the call is cancelled with an interrupt, the event is logged and counted, and a fallback answer is returned.
Key components:
- TimeoutPolicy (record) and TimeoutRegistry: per-service configurable limits with a default.
- TimeoutExecutor: enforces the limit (Future.get(timeout)), cancels the overrunning call, records the event in TimeoutMetrics, invokes the fallback. Service failures are surfaced as ServiceCallException, not as timeouts.
- ProductCatalogService (fast) and RecommendationService (slow, interruptible): simulated dependencies.
- App: catalog answers within its 500 ms limit; recommendations exceed their 100 ms limit, get cancelled and replaced by popular items; timeout counters are printed. Logging traces every step.
- README.md: intent, real-world example, sequence diagram, code walkthrough, applicability, trade-offs, related patterns (including how this differs from the existing fallback module, where the time limit is only one of several triggers). PlantUML class diagram under etc/.
Tests: 13 JUnit 5 tests covering result within limit, fallback plus cancellation on overrun (interruption verified), failure propagation, per-service limits and counters, registry and policy validation, plus AppTest.
Module registered in the parent pom.xml. ./mvnw clean verify -pl timeout passes locally on JDK 21 and inside an eclipse-temurin:21 container.

github-actions · 2026-09-03T09:22:09Z

PR Summary

Added the Timeout pattern as a new per-service timeout module. Introduces TimeoutPolicy, TimeoutExecutor, TimeoutMetrics, DownstreamService, and ServiceCallException to bound and cancel slow downstream calls, return fallbacks, and expose timeout metrics. Includes App demo, tests for policy, executor, downstream service, and App, plus documentation and diagrams. Module is wired into the parent POM and builds under JDK 21.

Changes

File	Summary
`pom.xml`	Registered new 'timeout' module in the parent Maven pom, ensuring the Timeout pattern is built as part of the project.
`timeout/pom.xml`	Defines new Maven module 'timeout' with dependencies and build settings.
`timeout/README.md`	Introduces the Timeout pattern with per-service time limits, cancellation, metrics, and fallback; includes usage notes and architecture.
`timeout/etc/timeout.urm.png`	UML diagram image for the Timeout module class relationships.
`timeout/etc/timeout.urm.puml`	PlantUML diagram detailing TimeoutPolicy, TimeoutExecutor, TimeoutMetrics, and related classes.
`timeout/src/main/java/com/iluwatar/timeout/App.java`	Demo app wiring two downstream services with different limits; demonstrates fallback and timeout metrics.
`timeout/src/main/java/com/iluwatar/timeout/DownstreamService.java`	Simulated downstream service with interruptible latency and configurable items.
`timeout/src/main/java/com/iluwatar/timeout/ServiceCallException.java`	Custom exception representing non-timeout service failures.
`timeout/src/main/java/com/iluwatar/timeout/TimeoutExecutor.java`	Executes downstream calls within per-service limits, cancels overruns, logs, updates metrics, and returns fallbacks.
`timeout/src/main/java/com/iluwatar/timeout/TimeoutMetrics.java`	Thread-safe per-service timeout counters with snapshot support.
`timeout/src/main/java/com/iluwatar/timeout/TimeoutPolicy.java`	TimeoutPolicy record with validation and factory method.
`timeout/src/test/java/com/iluwatar/timeout/AppTest.java`	Tests for App main path and timeout integration.
`timeout/src/test/java/com/iluwatar/timeout/DownstreamServiceTest.java`	Tests for DownstreamService behavior and interrupt handling.
`timeout/src/test/java/com/iluwatar/timeout/TimeoutExecutorTest.java`	Extensive tests for TimeoutExecutor including success, timeout, failure propagation, per-service limits, and interruption behavior.
`timeout/src/test/java/com/iluwatar/timeout/TimeoutPolicyTest.java`	Tests for TimeoutPolicy validation and factory.

autogenerated by presubmit.ai

github-actions

🚨 Pull request needs attention.

Review Summary

Commits Considered (1)

857e00a: feat: add Timeout pattern (#2845)

Files Processed (16)

pom.xml (1 hunk)
timeout/README.md (1 hunk)
timeout/etc/timeout.urm.puml (1 hunk)
timeout/pom.xml (1 hunk)
timeout/src/main/java/com/iluwatar/timeout/App.java (1 hunk)
timeout/src/main/java/com/iluwatar/timeout/ProductCatalogService.java (1 hunk)
timeout/src/main/java/com/iluwatar/timeout/RecommendationService.java (1 hunk)
timeout/src/main/java/com/iluwatar/timeout/ServiceCallException.java (1 hunk)
timeout/src/main/java/com/iluwatar/timeout/TimeoutExecutor.java (1 hunk)
timeout/src/main/java/com/iluwatar/timeout/TimeoutMetrics.java (1 hunk)
timeout/src/main/java/com/iluwatar/timeout/TimeoutPolicy.java (1 hunk)
timeout/src/main/java/com/iluwatar/timeout/TimeoutRegistry.java (1 hunk)
timeout/src/test/java/com/iluwatar/timeout/AppTest.java (1 hunk)
timeout/src/test/java/com/iluwatar/timeout/TimeoutExecutorTest.java (1 hunk)
timeout/src/test/java/com/iluwatar/timeout/TimeoutPolicyTest.java (1 hunk)
timeout/src/test/java/com/iluwatar/timeout/TimeoutRegistryTest.java (1 hunk)

Actionable Comments (7)

timeout/src/main/java/com/iluwatar/timeout/App.java [61-61]

possible bug: "Logger name should match Lombok's @slf4j field"
timeout/src/main/java/com/iluwatar/timeout/App.java [67-67]

readability: "Use the Lombok 'log' logger"
timeout/src/main/java/com/iluwatar/timeout/App.java [73-73]

readability: "Use the Lombok 'log' logger"
timeout/src/main/java/com/iluwatar/timeout/App.java [81-81]

readability: "Use the Lombok 'log' logger for final status"
timeout/src/main/java/com/iluwatar/timeout/ProductCatalogService.java [59-59]

possible bug: "Logger field name mismatch in ProductCatalogService"
timeout/src/main/java/com/iluwatar/timeout/RecommendationService.java [60-66]

possible bug: "Logger field name mismatch in RecommendationService"
timeout/src/main/java/com/iluwatar/timeout/TimeoutExecutor.java [82-82]

possible bug: "Logger name mismatch in TimeoutExecutor"

Skipped Comments (1)

timeout/pom.xml [46-50]

enhancement: "Add junit-jupiter-api for tests"

ylcn91 · 2026-09-03T09:26:18Z

Note on the automated review comments: LOGGER is the Lombok logger field name configured for this repository in lombok.config (lombok.log.fieldName = LOGGER), the same name every other module uses, so the code compiles as is. Local ./mvnw clean verify -pl timeout passes on JDK 21, also inside an eclipse-temurin:21 container.

codecov · 2026-09-03T09:38:42Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 84.18%. Comparing base (4cabb20) to head (dcfacf1).

Additional details and impacted files

@@             Coverage Diff              @@
##             master    #3598      +/-   ##
============================================
+ Coverage     84.06%   84.18%   +0.12%     
- Complexity     4353     4382      +29     
============================================
  Files          1133     1139       +6     
  Lines         15400    15486      +86     
  Branches        739      742       +3     
============================================
+ Hits          12946    13037      +91     
+ Misses         2158     2156       -2     
+ Partials        296      293       -3

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

ylcn91 · 2026-09-03T09:52:39Z

Follow-up on the Codecov note: added a test for an interrupted caller in TimeoutExecutorTest and a new RecommendationServiceTest (normal reply and interrupted computation). 16 tests, no uncovered lines outside App. Tests only, no production change. ./mvnw clean verify -pl timeout passes locally on JDK 21 and in an eclipse-temurin:21 container.

github-actions

🚨 Pull request needs attention.

Review Summary

Commits Considered (1)

562cd02: feat: add Timeout pattern (#2845)

Files Processed (17)

pom.xml (1 hunk)
timeout/README.md (1 hunk)
timeout/etc/timeout.urm.puml (1 hunk)
timeout/pom.xml (1 hunk)
timeout/src/main/java/com/iluwatar/timeout/App.java (1 hunk)
timeout/src/main/java/com/iluwatar/timeout/ProductCatalogService.java (1 hunk)
timeout/src/main/java/com/iluwatar/timeout/RecommendationService.java (1 hunk)
timeout/src/main/java/com/iluwatar/timeout/ServiceCallException.java (1 hunk)
timeout/src/main/java/com/iluwatar/timeout/TimeoutExecutor.java (1 hunk)
timeout/src/main/java/com/iluwatar/timeout/TimeoutMetrics.java (1 hunk)
timeout/src/main/java/com/iluwatar/timeout/TimeoutPolicy.java (1 hunk)
timeout/src/main/java/com/iluwatar/timeout/TimeoutRegistry.java (1 hunk)
timeout/src/test/java/com/iluwatar/timeout/AppTest.java (1 hunk)
timeout/src/test/java/com/iluwatar/timeout/RecommendationServiceTest.java (1 hunk)
timeout/src/test/java/com/iluwatar/timeout/TimeoutExecutorTest.java (1 hunk)
timeout/src/test/java/com/iluwatar/timeout/TimeoutPolicyTest.java (1 hunk)
timeout/src/test/java/com/iluwatar/timeout/TimeoutRegistryTest.java (1 hunk)

Actionable Comments (3)

timeout/src/main/java/com/iluwatar/timeout/App.java [61-61]

readability: "Replace Lombok-generated logger usage with 'log'."
timeout/src/main/java/com/iluwatar/timeout/ProductCatalogService.java [59-59]

readability: "Use Lombok 'log' instead of 'LOGGER' in logging."
timeout/src/main/java/com/iluwatar/timeout/RecommendationService.java [60-64]

readability: "Replace Lombok-generated logger usage with 'log' in multi-line logging."

Skipped Comments (0)

ylcn91 · 2026-09-03T11:32:52Z

Coverage follow-up: extracted the two demo calls in App into package-private helpers (loadProducts, loadRecommendations) so both the normal and the fallback paths are exercised by AppTest, and added shouldBeInstantiable. Demo output unchanged. JaCoCo now reports 100% instruction, branch and line coverage. Verified locally on JDK 21 and in an eclipse-temurin:21 container; the packaged jar runs end to end.

github-actions

✅ LGTM!

Review Summary

Commits Considered (1)

1b50cb4: feat: add Timeout pattern (#2845)

Files Processed (17)

pom.xml (1 hunk)
timeout/README.md (1 hunk)
timeout/etc/timeout.urm.puml (1 hunk)
timeout/pom.xml (1 hunk)
timeout/src/main/java/com/iluwatar/timeout/App.java (1 hunk)
timeout/src/main/java/com/iluwatar/timeout/ProductCatalogService.java (1 hunk)
timeout/src/main/java/com/iluwatar/timeout/RecommendationService.java (1 hunk)
timeout/src/main/java/com/iluwatar/timeout/ServiceCallException.java (1 hunk)
timeout/src/main/java/com/iluwatar/timeout/TimeoutExecutor.java (1 hunk)
timeout/src/main/java/com/iluwatar/timeout/TimeoutMetrics.java (1 hunk)
timeout/src/main/java/com/iluwatar/timeout/TimeoutPolicy.java (1 hunk)
timeout/src/main/java/com/iluwatar/timeout/TimeoutRegistry.java (1 hunk)
timeout/src/test/java/com/iluwatar/timeout/AppTest.java (1 hunk)
timeout/src/test/java/com/iluwatar/timeout/RecommendationServiceTest.java (1 hunk)
timeout/src/test/java/com/iluwatar/timeout/TimeoutExecutorTest.java (1 hunk)
timeout/src/test/java/com/iluwatar/timeout/TimeoutPolicyTest.java (1 hunk)
timeout/src/test/java/com/iluwatar/timeout/TimeoutRegistryTest.java (1 hunk)

Actionable Comments (0)

Skipped Comments (8)

timeout/src/main/java/com/iluwatar/timeout/App.java [61-61]

best_practice: "Use Lombok's generated logger"
timeout/src/main/java/com/iluwatar/timeout/App.java [67-67]

best_practice: "Use Lombok's generated logger"
timeout/src/main/java/com/iluwatar/timeout/App.java [73-73]

best_practice: "Use Lombok's generated logger"
timeout/src/main/java/com/iluwatar/timeout/App.java [75-75]

best_practice: "Use Lombok's generated logger"
timeout/src/main/java/com/iluwatar/timeout/ProductCatalogService.java [59-59]

best_practice: "Use Lombok's generated logger"
timeout/src/main/java/com/iluwatar/timeout/RecommendationService.java [60-66]

best_practice: "Use Lombok's generated logger"
timeout/src/main/java/com/iluwatar/timeout/TimeoutExecutor.java [82-82]

best_practice: "Use Lombok's generated logger"
timeout/src/main/java/com/iluwatar/timeout/TimeoutExecutor.java [88-90]

best_practice: "Use Lombok's generated logger"

github-actions

✅ LGTM!

Review Summary

Commits Considered (3)

afd73f2: docs: embed the rendered class diagram in the timeout README

Render etc/timeout.urm.puml to PNG and embed it in the detailed explanation section, matching the other modules, instead of the inline mermaid block.

4d79669: refactor: drop timeout registry and merge the demo services

TimeoutRegistry was configuration scaffolding rather than part of the
pattern, so App now builds its TimeoutPolicy values directly.

ProductCatalogService and RecommendationService only differed in name,
latency and payload, so they collapse into a single parameterised
DownstreamService and App's two near-identical helpers into one call
helper.

README, PlantUML diagram and tests follow; the sample output block is
taken from a real run of the demo.

9124ada: fix: keep metrics snapshot sorted and translate rejected submissions
TimeoutMetrics.snapshot() returns an unmodifiable SortedMap so the sorted view promised by its javadoc survives, covered by a new ordering test
TimeoutExecutor submits inside the try and wraps RejectedExecutionException in ServiceCallException, matching its @throws contract
timeout.urm.puml: mark TimeoutPolicy as a record, drop the synthetic App constructor, show ServiceCallException extending RuntimeException, add the App to TimeoutPolicy and TimeoutMetrics dependencies
README: inline mermaid class diagram instead of the raw .puml link, and note that the timeout warning and the worker interrupt lines may interleave

Files Processed (10)

timeout/README.md (1 hunk)
timeout/etc/timeout.urm.png (0 hunks)
timeout/etc/timeout.urm.puml (1 hunk)
timeout/src/main/java/com/iluwatar/timeout/App.java (1 hunk)
timeout/src/main/java/com/iluwatar/timeout/DownstreamService.java (1 hunk)
timeout/src/main/java/com/iluwatar/timeout/TimeoutExecutor.java (1 hunk)
timeout/src/main/java/com/iluwatar/timeout/TimeoutMetrics.java (1 hunk)
timeout/src/test/java/com/iluwatar/timeout/AppTest.java (1 hunk)
timeout/src/test/java/com/iluwatar/timeout/DownstreamServiceTest.java (1 hunk)
timeout/src/test/java/com/iluwatar/timeout/TimeoutExecutorTest.java (1 hunk)

Actionable Comments (0)

Skipped Comments (10)

timeout/src/main/java/com/iluwatar/timeout/App.java [66-66]

best_practice: "Use Lombok's log field instead of LOGGER"
timeout/src/main/java/com/iluwatar/timeout/App.java [69-69]

best_practice: "Replace LOGGER with log for per-call logging"
timeout/src/main/java/com/iluwatar/timeout/App.java [71-71]

best_practice: "Replace LOGGER with log for products logging"
timeout/src/main/java/com/iluwatar/timeout/App.java [73-73]

best_practice: "Replace LOGGER with log for recommendations logging"
timeout/src/main/java/com/iluwatar/timeout/App.java [75-75]

best_practice: "Replace LOGGER with log for final recommendations payload"
timeout/src/main/java/com/iluwatar/timeout/App.java [77-77]

best_practice: "Replace LOGGER with log for timeout metrics"
timeout/src/main/java/com/iluwatar/timeout/DownstreamService.java [74-74]

best_practice: "Use Lombok's log instead of LOGGER in DownstreamService"
timeout/src/main/java/com/iluwatar/timeout/DownstreamService.java [78-78]

best_practice: "Use Lombok's log in DownstreamService on interruption"
timeout/src/main/java/com/iluwatar/timeout/TimeoutExecutor.java [86-86]

best_practice: "Use Lombok's log for successful completion logging"
timeout/src/main/java/com/iluwatar/timeout/TimeoutExecutor.java [92-92]

best_practice: "Replace timeout warning log with log"

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.

github-actions

✅ LGTM!

Review Summary

Commits Considered (1)

2458cf8: 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.

Files Processed (10)

timeout/README.md (1 hunk)
timeout/etc/timeout.urm.png (0 hunks)
timeout/etc/timeout.urm.puml (1 hunk)
timeout/src/main/java/com/iluwatar/timeout/App.java (1 hunk)
timeout/src/main/java/com/iluwatar/timeout/DownstreamService.java (1 hunk)
timeout/src/main/java/com/iluwatar/timeout/TimeoutExecutor.java (1 hunk)
timeout/src/main/java/com/iluwatar/timeout/TimeoutMetrics.java (1 hunk)
timeout/src/test/java/com/iluwatar/timeout/AppTest.java (1 hunk)
timeout/src/test/java/com/iluwatar/timeout/DownstreamServiceTest.java (1 hunk)
timeout/src/test/java/com/iluwatar/timeout/TimeoutExecutorTest.java (1 hunk)

Actionable Comments (0)

Skipped Comments (3)

timeout/src/main/java/com/iluwatar/timeout/App.java [66-77]

readability: "Use the Lombok-provided logger instead of LOGGER"
timeout/src/main/java/com/iluwatar/timeout/DownstreamService.java [73-82]

readability: "Logger usage mismatch in DownstreamService"
timeout/src/main/java/com/iluwatar/timeout/TimeoutExecutor.java [86-93]

readability: "Logger usage mismatch in TimeoutExecutor"

# Conflicts: # pom.xml

github-actions

✅ LGTM!

Review Summary

Commits Considered (1)

dcfacf1: Merge remote-tracking branch 'origin/master' into feat/timeout

Conflicts:

pom.xml

Files Processed (1)

pom.xml (1 hunk)

Actionable Comments (0)

Skipped Comments (1)

pom.xml [263-263]

enhancement: "Add timeout module to Maven reactor."

ylcn91 mentioned this pull request Sep 3, 2026

Timeout pattern #2845

Open

github-actions Bot reviewed Sep 3, 2026

View reviewed changes

ylcn91 force-pushed the feat/timeout branch from 857e00a to 562cd02 Compare September 3, 2026 09:52

github-actions Bot reviewed Sep 3, 2026

View reviewed changes

Comment thread timeout/src/main/java/com/iluwatar/timeout/App.java

Comment thread timeout/src/main/java/com/iluwatar/timeout/ProductCatalogService.java Outdated

Comment thread timeout/src/main/java/com/iluwatar/timeout/RecommendationService.java Outdated

feat: add Timeout pattern (iluwatar#2845)

1b50cb4

ylcn91 force-pushed the feat/timeout branch from 562cd02 to 1b50cb4 Compare September 3, 2026 11:32

github-actions Bot reviewed Sep 3, 2026

View reviewed changes

github-actions Bot reviewed Sep 7, 2026

View reviewed changes

refactor: simplify the timeout demo and address review findings

2458cf8

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.

ylcn91 force-pushed the feat/timeout branch from afd73f2 to 2458cf8 Compare September 7, 2026 08:04

github-actions Bot reviewed Sep 7, 2026

View reviewed changes

ylcn91 mentioned this pull request Sep 11, 2026

feat: add Scatter-Gather pattern (#3577) #3601

Open

Merge remote-tracking branch 'origin/master' into feat/timeout

dcfacf1

# Conflicts: # pom.xml

github-actions Bot reviewed Oct 2, 2026

View reviewed changes

Uh oh!

Conversation

ylcn91 commented Sep 3, 2026

What does this PR do?

Uh oh!

github-actions Bot commented Sep 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Summary

Changes

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

Review Summary

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ylcn91 commented Sep 3, 2026

Uh oh!

codecov Bot commented Sep 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

ylcn91 commented Sep 3, 2026

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

Review Summary

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ylcn91 commented Sep 3, 2026

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

Review Summary

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

Review Summary

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

Review Summary

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

Review Summary

Conflicts:

pom.xml

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

github-actions Bot commented Sep 3, 2026 •

edited

Loading

codecov Bot commented Sep 3, 2026 •

edited

Loading