feat: add Scatter-Gather pattern (#3577)

[ylcn91]

What does this PR do?

Adds the Scatter-Gather pattern as a new scatter-gather module.

• Problem: a client request often needs answers from several independent providers; calling them one after another adds up their latencies, and one slow or failing provider should not block the whole answer.
• Solution: the same request is scattered to every provider concurrently, replies are gathered until each has arrived, failed or exceeded the timeout, and the successful replies are aggregated into one result. Partial results are first class.
• Key components:
  • RateRequest, RateQuote, RateProvider: a travel site asking several hotel rate providers for the same stay.
  • InMemoryRateProvider (fast), DelayedRateProvider (slow, interrupt-safe), FailingRateProvider.
  • ScatterGather: scatter() (one CompletableFuture per provider with orTimeout), gather() (waits for all to settle, keeps successes, logs timeouts and failures), scatterGather() chaining both with an Aggregator; AutoCloseable.
  • Aggregator: functional reduction of the gathered replies, with a cheapestQuote() factory.
  • App: four providers (two fast, one slower than the 300 ms timeout, one failing); logs the scatter, gather and aggregate phases and the best offer.
  • README.md: intent, real-world example, sequence diagram, code walkthrough, applicability, trade-offs, related patterns including an explicit note on how Scatter-Gather differs from the existing Fan-Out/Fan-In module. PlantUML class diagram under etc/.
• Tests: 13 JUnit 5 tests covering all providers replying, a slow provider dropped after the timeout while others are kept, a failing provider dropped, aggregation, empty result when nobody answers, executor shutdown, plus AppTest.
• Module registered in the parent pom.xml. ./mvnw clean verify -pl scatter-gather passes locally on JDK 21 and inside an eclipse-temurin:21 container.

Note: PR #3590 also targets this issue. This implementation was written independently with a different domain and design; it includes the populated, logging App entry point requested in the review of #3590 and treats partial results and timeouts as the core of the pattern. Happy to align with whichever direction the maintainers prefer.

Fixes #3577

[github-actions]

PR Summary

Introduced the Scatter-Gather pattern as a new module. The solution scatters a request to multiple providers concurrently, gathers replies within a bounded timeout, and aggregates the results while tolerating slow or failing providers. Includes fast, slow, and failing provider variants, an Aggregator strategy, an App demonstration, and thorough tests. Updated the parent pom to include the new module and added README/diagrams for guidance.

Changes

File	Summary
pom.xml	Registered the scatter-gather module in the parent pom to enable building and testing the new pattern as part of the multi-module project.
scatter-gather/README.md	Added Scatter-Gather README with pattern overview, Java example, and guidance on when to use; includes sequence diagram and PlantUML notes.
scatter-gather/etc/scatter-gather.urm.png	Added a UML class diagram image illustrating the Scatter-Gather design and relationships.
scatter-gather/etc/scatter-gather.urm.puml	Added PlantUML diagram defining the Scatter-Gather class/package relationships for visualization.
scatter-gather/pom.xml	Added module pom defining dependencies and build settings for the scatter-gather module, including test dependencies.
scatter-gather/src/main/java/com/iluwatar/scattergather/Aggregator.java	Defined Aggregator interface for reducing gathered RateQuote objects; provides cheapestQuote() helper.
scatter-gather/src/main/java/com/iluwatar/scattergather/App.java	Implemented demo App with RateRequest, providers, and end-to-end scatter/gather usage.
scatter-gather/src/main/java/com/iluwatar/scattergather/DelayedRateProvider.java	Added DelayedRateProvider to simulate slow responses and test timeout handling.
scatter-gather/src/main/java/com/iluwatar/scattergather/FailingRateProvider.java	Added FailingRateProvider to simulate unavailable service and verify fallback behavior.
scatter-gather/src/main/java/com/iluwatar/scattergather/InMemoryRateProvider.java	Added InMemoryRateProvider delivering fixed quotes instantly for tests.
scatter-gather/src/main/java/com/iluwatar/scattergather/RateProvider.java	Introduced RateProvider interface with name() and quote() methods.
scatter-gather/src/main/java/com/iluwatar/scattergather/RateQuote.java	Added RateQuote record carrying provider name and total price.
scatter-gather/src/main/java/com/iluwatar/scattergather/RateRequest.java	Added RateRequest record with city, checkIn, nights and validation for positive nights.
scatter-gather/src/main/java/com/iluwatar/scattergather/ScatterGather.java	Implemented ScatterGather coordinator handling scatter, gather, and aggregate phases with cancellation and shutdown behavior.
scatter-gather/src/test/java/com/iluwatar/scattergather/AggregatorTest.java	Added tests validating cheapestQuote aggregation and empty result handling.
scatter-gather/src/test/java/com/iluwatar/scattergather/AppTest.java	Added tests for App main and reporting behavior.
scatter-gather/src/test/java/com/iluwatar/scattergather/RateProviderTest.java	Added unit tests for provisioned providers including InMemory, Delayed, and Failing scenarios.
scatter-gather/src/test/java/com/iluwatar/scattergather/ScatterGatherTest.java	Comprehensive tests for ScatterGather, covering timeout dropping, cancellation, interruption, aggregation, and shutdown semantics.

---

autogenerated by presubmit.ai

[github-actions]

🚨 Pull request needs attention.

Review Summary

Commits Considered (1)

• 31d348c: feat: add Scatter-Gather pattern (#3577)

Files Processed (17)

• pom.xml (1 hunk)
• scatter-gather/README.md (1 hunk)
• scatter-gather/etc/scatter-gather.urm.puml (1 hunk)
• scatter-gather/pom.xml (1 hunk)
• scatter-gather/src/main/java/com/iluwatar/scattergather/Aggregator.java (1 hunk)
• scatter-gather/src/main/java/com/iluwatar/scattergather/App.java (1 hunk)
• scatter-gather/src/main/java/com/iluwatar/scattergather/DelayedRateProvider.java (1 hunk)
• scatter-gather/src/main/java/com/iluwatar/scattergather/FailingRateProvider.java (1 hunk)
• scatter-gather/src/main/java/com/iluwatar/scattergather/InMemoryRateProvider.java (1 hunk)
• scatter-gather/src/main/java/com/iluwatar/scattergather/RateProvider.java (1 hunk)
• scatter-gather/src/main/java/com/iluwatar/scattergather/RateQuote.java (1 hunk)
• scatter-gather/src/main/java/com/iluwatar/scattergather/RateRequest.java (1 hunk)
• scatter-gather/src/main/java/com/iluwatar/scattergather/ScatterGather.java (1 hunk)
• scatter-gather/src/test/java/com/iluwatar/scattergather/AggregatorTest.java (1 hunk)
• scatter-gather/src/test/java/com/iluwatar/scattergather/AppTest.java (1 hunk)
• scatter-gather/src/test/java/com/iluwatar/scattergather/RateProviderTest.java (1 hunk)
• scatter-gather/src/test/java/com/iluwatar/scattergather/ScatterGatherTest.java (1 hunk)

Actionable Comments (6)

• scatter-gather/src/main/java/com/iluwatar/scattergather/App.java [66-66]

  bug: "Logger instance naming mismatch with Lombok"

• scatter-gather/src/main/java/com/iluwatar/scattergather/App.java [69-69]

  bug: "Logger usage mismatch in gather log line"

• scatter-gather/src/main/java/com/iluwatar/scattergather/App.java [72-72]

  bug: "Logger usage mismatch in aggregate log line"

• scatter-gather/src/main/java/com/iluwatar/scattergather/DelayedRateProvider.java [60-60]

  bug: "Incorrect duration handling in Delay provider"

• scatter-gather/src/main/java/com/iluwatar/scattergather/InMemoryRateProvider.java [56-56]

  bug: "Logger naming inconsistency in InMemoryRateProvider"

• scatter-gather/src/main/java/com/iluwatar/scattergather/ScatterGather.java [83-87]

  bug: "Logger naming mismatch in ScatterGather.scatter"

Skipped Comments (0)

[ylcn91]

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. Thread.sleep(Duration) is the Java 19+ overload, valid on the project's Java 21 baseline. Local ./mvnw clean verify -pl scatter-gather passes on JDK 21, also inside an eclipse-temurin:21 container.

[codecov]

Codecov Report

❌ Patch coverage is 99.11504% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 83.86%. Comparing base (41625d8) to head (5fab90e).

Files with missing lines	Patch %	Lines
...java/com/iluwatar/scattergather/ScatterGather.java	98.36%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##             master    #3601      +/-   ##
============================================
+ Coverage     83.79%   83.86%   +0.07%     
- Complexity     4277     4311      +34     
============================================
  Files          1121     1129       +8     
  Lines         15144    15257     +113     
  Branches        723      728       +5     
============================================
+ Hits          12690    12796     +106     
- Misses         2159     2163       +4     
- Partials        295      298       +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]

Follow-up on the Codecov note: added two ScatterGatherTest cases for close() (interrupted caller keeps the interrupt flag; a task that ignores interrupts does not block shutdown). 15 tests, ScatterGather fully covered; the remaining uncovered lines are the implicit App constructor and the demo's empty-result lambda. Tests only. ./mvnw clean verify -pl scatter-gather passes locally on JDK 21 and in an eclipse-temurin:21 container.

[ylcn91]

Coverage follow-up: moved the result reporting in App into a package-private reportBestOffer helper so the empty-result branch is covered, 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]

🚨 Pull request needs attention.

Review Summary

Commits Considered (4)

• bc38fb3: docs: embed the rendered class diagram in the scatter-gather README

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

• ff263fb: refactor: simplify aggregator generics and make shutdown grace configurable

Aggregator only ever reduced lists of RateQuote, so the reply type parameter carried no information. Drop it and let the interface be Aggregator over List; update ScatterGather, the README snippets and the PUML diagram to match.

Also lift the hard-coded one second awaitTermination in close() into a field. The public constructor keeps the one second default; a package-private overload takes an explicit grace period so the test that closes a coordinator whose task ignores interrupts no longer pays a full second.

• ea26143: fix: handle cancelled replies and correct timeout docs in scatter-gather

• gather() now catches CancellationException so a cancelled pending reply is
  dropped like a failed one instead of escaping to the caller, with a test
  that cancels one reply and asserts the remaining quotes are still gathered

• class javadoc states that a timed-out provider's task keeps running on its
  pool thread until it finishes or the coordinator is closed

• timeout parameter documented as starting at scatter time, in the javadoc and
  in the README

• class diagram: ScatterGather depends on RateProvider instead of holding a
  collection of them, and PendingReply is shown as a nested type

• README embeds the class diagram as mermaid instead of linking the PlantUML file

• c4563e9: feat: add Scatter-Gather pattern (#3577)

Files Processed (18)

• pom.xml (1 hunk)
• scatter-gather/README.md (1 hunk)
• scatter-gather/etc/scatter-gather.urm.png (0 hunks)
• scatter-gather/etc/scatter-gather.urm.puml (1 hunk)
• scatter-gather/pom.xml (1 hunk)
• scatter-gather/src/main/java/com/iluwatar/scattergather/Aggregator.java (1 hunk)
• scatter-gather/src/main/java/com/iluwatar/scattergather/App.java (1 hunk)
• scatter-gather/src/main/java/com/iluwatar/scattergather/DelayedRateProvider.java (1 hunk)
• scatter-gather/src/main/java/com/iluwatar/scattergather/FailingRateProvider.java (1 hunk)
• scatter-gather/src/main/java/com/iluwatar/scattergather/InMemoryRateProvider.java (1 hunk)
• scatter-gather/src/main/java/com/iluwatar/scattergather/RateProvider.java (1 hunk)
• scatter-gather/src/main/java/com/iluwatar/scattergather/RateQuote.java (1 hunk)
• scatter-gather/src/main/java/com/iluwatar/scattergather/RateRequest.java (1 hunk)
• scatter-gather/src/main/java/com/iluwatar/scattergather/ScatterGather.java (1 hunk)
• scatter-gather/src/test/java/com/iluwatar/scattergather/AggregatorTest.java (1 hunk)
• scatter-gather/src/test/java/com/iluwatar/scattergather/AppTest.java (1 hunk)
• scatter-gather/src/test/java/com/iluwatar/scattergather/RateProviderTest.java (1 hunk)
• scatter-gather/src/test/java/com/iluwatar/scattergather/ScatterGatherTest.java (1 hunk)

Actionable Comments (5)

• scatter-gather/src/main/java/com/iluwatar/scattergather/App.java [67-75]

  maintainability: "Logger name mismatch with Lombok @slf4j"

• scatter-gather/src/main/java/com/iluwatar/scattergather/InMemoryRateProvider.java [56-56]

  maintainability: "Logger usage with Lombok"

• scatter-gather/src/main/java/com/iluwatar/scattergather/DelayedRateProvider.java [58-58]

  maintainability: "Logger usage with Lombok"

• scatter-gather/src/main/java/com/iluwatar/scattergather/DelayedRateProvider.java [60-60]

  possible bug: "Thread.sleep with Duration"

• scatter-gather/src/main/java/com/iluwatar/scattergather/ScatterGather.java [103-107]

  maintainability: "Logger usage with Lombok"

Skipped Comments (0)

[github-actions]

🚨 Pull request needs attention.

Review Summary

Commits Considered (1)

• 5fab90e: fix: cancel timed-out provider calls and simplify the aggregator

A reply that times out or is cancelled cancels its task, gather tolerates cancelled replies, Aggregator loses its unused type parameter and the shutdown grace is configurable for tests. The class diagram is a rendered PNG.

Files Processed (6)

• scatter-gather/README.md (1 hunk)
• scatter-gather/etc/scatter-gather.urm.png (0 hunks)
• scatter-gather/etc/scatter-gather.urm.puml (1 hunk)
• scatter-gather/src/main/java/com/iluwatar/scattergather/Aggregator.java (1 hunk)
• scatter-gather/src/main/java/com/iluwatar/scattergather/ScatterGather.java (1 hunk)
• scatter-gather/src/test/java/com/iluwatar/scattergather/ScatterGatherTest.java (1 hunk)

Actionable Comments (5)

• scatter-gather/src/main/java/com/iluwatar/scattergather/ScatterGather.java [103-107]

  best_practice: "Logger field name mismatch with Lombok"

• scatter-gather/src/main/java/com/iluwatar/scattergather/ScatterGather.java [150-150]

  best_practice: "Use Lombok-provided logger"

• scatter-gather/src/main/java/com/iluwatar/scattergather/ScatterGather.java [154-156]

  best_practice: "Logger usage fix for timeout drop warning"

• scatter-gather/src/main/java/com/iluwatar/scattergather/ScatterGather.java [160-160]

  best_practice: "Logger usage fix for cancellation path"

• scatter-gather/src/main/java/com/iluwatar/scattergather/ScatterGather.java [163-163]

  best_practice: "Logger usage fix for gather summary"

Skipped Comments (0)