gof-adapter · diff
git:20260903.f199530 to git:20260906.e6ad4bd
28 added, 20 removed. Audit A to A.
---
name: gof-adapter
description: >
Adapter in modern Java: making an existing type usable through an interface it was not
written for, and keeping a foreign model, vocabulary and failure mode from leaking inward.
Covers object versus class adapters, why a lambda already adapts a single-method
interface, the error-translation duty most adapters omit, when an adapter has quietly
become a translator with business rules in it, and when a passthrough should be deleted.
Use when integrating a vendor SDK or legacy type behind your own port, when two libraries
must interoperate, when an adapter is proposed between types you own, when foreign
exceptions or DTOs appear in domain code, or when reviewing a wrapper that renames methods
and does nothing else. Does not cover the Kubernetes telemetry sidecar
(adapter-sidecar-pattern), simplifying a subsystem you own (gof-facade), adding behaviour
to the same interface (gof-decorator), controlling access to an object (gof-proxy), or
layering rules in general (layering-and-boundaries).
---
# Adapter
## Purpose
Let code depend on an interface it chose, while the object doing the work has a different one.
The adapter absorbs the mismatch — signature, model, vocabulary, error style — so that neither
side has to change and neither side learns about the other.
The measure of a boundary adapter is the coupling it intentionally contains. Domain-facing ports
usually should not expose vendor DTOs or exceptions; a thin interoperability adapter between two
libraries may deliberately retain shared standard types. State the boundary goal instead of
assuming every adapter is an anti-corruption layer.
## When it is the answer
```text
A third-party or legacy type does the work and its interface is not
yours to change
→ Adapter. This is the default and by far the commonest case.
Two libraries must interoperate and neither knows the other
→ Adapter, owned by the code that composes them, not by either.
Your own port defines what the application needs; several
implementations exist behind it
→ Adapter per implementation (this is ports-and-adapters;
the GoF pattern is the per-implementation half).
A test needs a fake implementation of an external dependency
→ the port exists for this too; the fake is not an adapter but
it is enabled by the same seam.
```
## When it is not
- **You own both sides and can change them atomically.** Direct refactoring may be cheaper. An
adapter can still be correct across independently released modules, during migration, or where
two intentionally distinct models must remain separate.
- **The mapping is one-to-one with no translation or boundary policy.** A passthrough may be
removable, but can still own version isolation, telemetry, authorization or replacement
authority. Name and test that reason; otherwise delete it.
- **It contains business rules.** Deciding, defaulting, validating against domain policy — that
is domain logic in the boundary layer. Move it inward and leave translation behind.
- - **It aggregates several collaborators into one coarse call.** That is a Facade
- (`gof-facade`), and the distinction matters because a Facade may sit above adapters but is
- not one.
+ - **Its purpose is simplifying a subsystem behind a coarse call.** Consider Facade
+ (`gof-facade`); collaborator count alone does not classify a wrapper or exclude adaptation.
- **It adds behaviour while keeping the same interface.** That is a Decorator
(`gof-decorator`).
## Modern Java expression
+ Examples use Java 17 language features; inspect target compiler/runtime, actual SDK/API versions
+ and compatibility obligations before implementation. No pattern choice authorizes an upgrade.
+
```text
Single-method interface mismatch a lambda or method reference:
Runnable r = task::execute;
Comparator<Order> c = comparing(Order::total);
Interface gained a method a legacy a default method on the interface,
implementor cannot supply implemented in terms of the others
Data model mismatch a record per boundary type, plus a
mapper — never the vendor's type in
the domain (remote-facade-and-dto)
Foreign exception hierarchy translate at the adapter into your
own, preserving the cause
(java-exception-design)
Whole-implementation mismatch an object adapter: a final class
holding the adaptee in a field
```
Class adapters — `extends Adaptee implements Target` — spend Java's single inheritance slot and
expose inherited public API, so composition is usually easier to isolate and replace. Inheritance
remains useful when a framework requires subclass hooks or the adaptee cannot be delegated
without losing protected extension behavior. Treat that as tighter coupling, not as impossible.
+ An interface default is suitable only when existing operations can satisfy the new method's
+ contract for all affected implementations; inspect inherited-default conflicts and behavioral
+ compatibility rather than inventing a no-op to make compilation pass.
## Decision rules
```text
IF a vendor type, exception or enum appears above a domain-facing adapter
THEN decide whether consumers now depend on vendor semantics. Translate when the
port is meant to protect that boundary; shared standards or deliberately thin
interoperability layers may preserve types explicitly.
- IF the adapter throws the adaptee's exception type
- THEN callers must catch a foreign type, and swapping the adaptee is a
- breaking change. Translate, keeping the original as the cause.
+ IF a domain-facing port promises failure isolation but exposes the adaptee's exception type
+ THEN translate to the promised failure contract while preserving diagnostic cause; consumers
+ must not need vendor-specific catches. Thin interoperability contracts may differ explicitly.
IF the adapter interprets, defaults or decides
- THEN that is domain logic. Move it in; keep the adapter mechanical.
+ THEN distinguish provider-specific protocol interpretation from domain policy. Keep required
+ translation/validation here; move business decisions that remain after provider replacement inward.
- IF the adapter's interface has one method and the adaptee's has one
- method
- THEN a lambda or method reference is the adapter. No class.
+ IF the target is a functional interface and the method signatures/checked failures are compatible
+ THEN a lambda or method reference may suffice, regardless of how many methods the adaptee has.
+ Prefer a named class when lifecycle, state, substantial mapping or diagnostics warrant it.
IF the port has exactly one implementation and no second is planned,
and the implementation is your own code
- THEN the port is speculative indirection (gof-pattern-thinking).
- An external dependency is the exception: the seam has value even
- with one implementation, because it bounds the foreign model.
+ THEN check dependency direction, test isolation, release boundaries and migration needs before
+ calling the port speculative. Implementation count alone is not a deletion criterion.
IF the adaptee is not thread-safe
- THEN the adapter is not either, whatever it looks like. State the
- constraint or synchronise inside it deliberately.
+ THEN wrapping alone adds no guarantee. State confinement, per-call ownership or synchronization
+ covering all accesses, including aliases outside the adapter; otherwise retain the restriction.
IF the adaptee is remote
THEN its contract must expose or document latency and partial failure. Transport
timeouts belong near the client; end-to-end deadlines, retry and fallback policy
may belong to the caller or resilience layer (gof-proxy, timeouts-and-deadlines).
```
## Cross-cutting checks
- - **Concurrency.** An adapter is normally stateless and shareable. It does not confer thread
+ - **Concurrency.** A stateless adapter is shareable only if its dependencies/protocol permit it. It does not confer thread
safety on the adaptee: wrapping a non-thread-safe client in a "service" changes nothing. If
the adapter adds state — a cache, a connection, a cursor — it now owns a concurrency
contract and must document or enforce it.
- **Distribution.** Adapters are where a remote dependency's failure vocabulary is turned into
- yours, and where its schema version is pinned. Two duties are routinely missed: timeouts must
- be set in the adapter, since the port cannot express "may hang forever"; and unknown enum or
+ yours, and where its schema compatibility is checked. Transport timeout ownership may be in
+ injected client configuration; the caller can supply an end-to-end deadline. Unknown enum or
field values from a newer peer must be handled deliberately rather than throwing deep inside
the domain (`rpc-and-api-contracts`).
+ - **Lifecycle.** Define whether the client, response stream or cursor is borrowed or owned, who
+ closes it and how cancellation/interruption propagates. Do not close an injected shared client
+ per call or turn an interrupted wait into an ordinary retryable provider failure.
- **Performance.** Dispatch is often inlined and translation cost ranges from zero-copy views to
full graph allocation. Inspect large collection copies, encoding conversions and eager
traversal; translating a lazily loaded structure can turn one query into many
(`orm-behavioral-patterns`). Measure the boundary rather than counting wrapper calls.
- **Testing.** The port is the seam that lets the application be tested without the dependency;
the adapter itself needs tests against an authoritative implementation or compatible sandbox,
because its content is assumptions about a foreign system. Where that cannot run on every
commit, combine deterministic mapping tests with scheduled/provider contract tests
(`java-test-doubles`, `java-testing-strategy`).
## Review checklist
- [ ] Any foreign type, exception or enum crossing outward is an explicit compatibility choice
- [ ] Adaptee exceptions are translated with the original preserved as the cause
- [ ] The adapter contains no decisions that belong to the domain
- [ ] Composition is preferred; inheritance has a documented framework/extension constraint
- - [ ] A single-method adaptation is a lambda, not a class
+ - [ ] A functional-interface adaptation uses the smallest form that preserves its contract/lifecycle
- [ ] Remote transport timeouts are configured and end-to-end resilience ownership is explicit
- [ ] The adapter is covered by authoritative integration/contract evidence at an appropriate cadence
- - [ ] A one-to-one passthrough is justified by bounding a foreign model, or deleted
+ - [ ] A passthrough has an evidenced boundary, lifecycle or compatibility responsibility, or is removed safely
## References
- [Decision and alternatives](references/decision-and-alternatives.md) — object versus class
adapters, Adapter set against Facade, Decorator, Proxy and the anti-corruption layer, the
error-translation rules, how to tell a translator with business rules from a mechanical
adapter, and how to remove a passthrough safely. Read when classifying or deleting a wrapper.
- [Worked example](references/worked-example.md) — a vendor payment SDK adapted to a domain
port: model translation, exception translation, timeout ownership, unknown-status handling
from a newer API version, and the test split between a fake for the application and a
contract test for the adapter. Read when implementing.