A common mistake is using the general gatherer factory with a combiner that can never be called, often because the operation is sequential only. That creates misleading code and suggests parallel support that does not exist. The cleaner approach is to use the sequential factory, which makes the processing model explicit and removes dummy combiner logic.
Why the factory choice matters more than the combiner
Sequential gatherers are easy to overcomplicate when the code is written as if it might be parallel later. The real issue is not just style, it is whether the API communicates the actual execution model. If the gatherer will never combine partial results, a general factory with an unused combiner adds noise and can mislead readers about concurrency support.
That mismatch matters because Java APIs tend to signal intent through the factory you choose. A sequential factory makes the contract explicit: one stream, one pass, one accumulation path. That is cleaner for maintenance, and it avoids suggesting a parallel shape where none exists.
What teams usually misunderstand about sequential-only processing
The common mistake is treating “general” as automatically better. In practice, a general gatherer factory is appropriate when the implementation genuinely needs both accumulation and combination semantics. If the operation is inherently sequential, the combiner becomes dead code, and dead code in an API contract is a documentation bug as much as a technical one.
Teams also sometimes assume that leaving the combiner in place is harmless because it is never invoked. That is only partly true. It can still confuse reviewers, complicate testing, and encourage future changes that assume parallel safety where the design never supported it.
Using the sequential factory is the clearer expression of intent because it ties the implementation to the processing model the code actually uses. For API design, that explicitness is valuable even when the logic itself is simple.
How to write the gatherer so the code says what it does
Start by deciding whether the operation truly has a parallel-friendly merge step. If it does not, model it as sequential from the outset and avoid a placeholder combiner. That keeps the implementation aligned with the runtime behaviour and reduces the chance of accidental overgeneralisation.
When reviewing this code, look for two signals: whether the combiner contains real logic, and whether anyone reading the code could reasonably believe the gatherer supports parallel execution. If the answer to the second question is yes, the abstraction is probably too broad for the problem at hand.
The best version is usually the one that makes future misuse harder. A sequential factory does that by narrowing the surface area to the only execution pattern that is actually valid.
Risk and Threat Considerations
Misstating the execution model is a maintainability risk because it creates a gap between what the code appears to support and what it can really do. In larger codebases, that gap can lead to incorrect reuse, flawed assumptions during refactoring, and wasted effort testing a path that is never exercised.
Failure mechanism: A general factory with an inert combiner encourages developers to read the gatherer as parallel-capable, even when the implementation is sequential only. That mismatch can hide design intent and make later changes more fragile.
Impact: The result is misleading code, weaker review quality, and a higher chance that someone will extend the gatherer in a way that breaks the intended processing model.
Standards & Framework Alignment
This section maps relevant standards and security frameworks to the operational risks and controls described in this guidance.
OWASP SAMM and NIST SP 800-53 Rev 5 set the technical controls, while ISO/IEC 27001:2022 defines the regulatory obligations.
| Framework | Control / Reference | Relevance |
|---|---|---|
| OWASP SAMM | Software Assurance Maturity Model | Sequential gatherer design reflects software construction clarity and maintainability. |
| Recommendation — Use SAMM to keep implementation patterns aligned with intended behavior and reduce misleading abstractions. | ||
| NIST SP 800-53 Rev 5 | CM-2 — Baseline Configuration | Selecting the correct factory preserves explicit configuration and avoids ambiguous implementation intent. |
| Recommendation — Document the intended execution model so code review and change control preserve it. | ||
| ISO/IEC 27001:2022 | A.8.25 — Secure development life cycle | The issue is an implementation clarity problem in software design and review. |
| Recommendation — Embed design intent checks into development reviews to prevent misleading API usage. | ||
Practitioner Guidance
What to verify: Check whether the gatherer has a genuine merge path before choosing the general factory. If no second-phase combination can ever happen, the sequential factory is the more accurate choice.
Common mistake: Treating API generality as a virtue even when it only adds a fake capability. In this case, the cleaner design is the narrower one because it prevents the reader from inferring parallel support that does not exist.
Practitioner takeaway: Pick the factory that matches the real execution model, not the one that looks more flexible on paper.
Related resources from NHI Mgmt Group
- What do teams get wrong about session management when they build on OAuth2 and OpenID Connect?
- What do teams get wrong when they build detections for multi-step cloud threats?
- What do teams get wrong when they build SOC playbooks for modern security operations?
- What do teams get wrong when they build a central data repository without a governance framework?
