Adapter: making interfaces fit
- Lesson 11 of 32
- 10 min
- Beginner
- 12 steps
Two business classes call a payments SDK using its own names. You will hide it behind an interface of your own and see what you gain and what you pay.
- Classes that know the SDK
- 1
- request
- response
Step 1 of 12
Problem
Your code speaks the vendor's language
A shop takes payments with a payment vendor's SDK, VendorSdk. Orders and Subscriptions call it directly: they build the { amount, currency, customer } object and read status from the response.
It works. The problem is that the SDK's shape (its names, its fields, its types) is now spread across your business code. Your classes know things that are not theirs.
Step 2 of 12
Problem
Another vendor, another shape
The business wants to try another vendor, OtherSdk (also made up). It does the same job, taking payments, but with other names and other fields.
Since Orders and Subscriptions know VendorSdk by name, you have to open both and rewrite every call. Here it is 2 classes; in a real project it can be dozens of files.
The same happens when the vendor ships a version that changes its API: the change reaches deep into your code.
What changed
- OtherSdk
- Orders and Subscriptions
Step 3 of 12
Concept
First, the shape your code wants
Before touching the SDK, write the interface that suits you: Payments, with a charge(cents, customerId) method that returns { ok, id }.
It names no vendor. Orders and Subscriptions now depend on Payments, a contract you own that changes only when your business asks for it.
For now nothing implements Payments: the piece that connects it to the SDK is missing.
What changed
- interface Payments
Step 4 of 12
Solution
A class that translates: the adapter
VendorAdapter implements Payments and keeps a VendorSdk inside. When someone calls charge, it translates the call into createCharge and delegates to the SDK.
That is the Adapter pattern: your code expects interface A, the library offers interface B, and a class in between implements A by translating to B. The rest of your code never sees B.
Orders receives a Payments in its constructor, as in the dependency injection lesson, and does not know there is an adapter behind it.
What changed
- VendorAdapter
- createCharge in Orders and Subscriptions
Step 5 of 12
Technique
Out: your names to the SDK's
Follow the packet: Orders calls charge(1999, "c1") and the adapter turns it into createCharge({ amount: 1999, currency: "usd", customer: "c1" }).
The table shows the translation field by field. Look at the field your interface does not have: currency. The adapter fills it in with a fixed value, because in this example the shop only charges in dollars.
Names are not the only thing that changes: units, parameter order or date formats are translated here too, in one place.
Step 6 of 12
Technique
Back: the SDK's reply in your shape
The SDK replies { status: "succeeded", chargeId: "ch_c1_1999" }. That shape must not reach Orders either.
toPayment turns it into what Payments promises: ok is true only when status is "succeeded", and id copies chargeId. Orders receives { ok: true, id: "ch_c1_1999" }.
Translating both ways is what locks the SDK in: neither its parameters nor its responses leave the adapter.
Step 7 of 12
Solution
New vendor: one new class and one line
Back to the vendor change. You write OtherAdapter, which also implements Payments and translates to OtherSdk.
Orders and Subscriptions do not change: they still ask for a Payments. Where the app is wired (main.ts) you change one line: which adapter gets created.
Before, 2 business classes had to be edited; now 0 are edited and 1 new class is added.
What changed
- OtherAdapter
- main.ts (one line)
Step 8 of 12
Technique
In tests, a pretend Payments
Since Orders depends on Payments and not on the SDK, a test passes it a fake object that meets the interface: no network, no vendor account, no real charges.
You also choose the reply: with ok: false you test what Orders does when a payment fails, without relying on the vendor's test data.
The fake is easy because the interface is yours and small. If Orders talked to the SDK, you would have to imitate the whole SDK.
What changed
- fake: Payments
Step 9 of 12
Concept
Adapters you already use
Java: according to its documentation, InputStreamReader is a bridge from byte streams to character streams: it reads bytes and decodes them with a charset. Whoever uses a Reader gets characters and never sees the bytes.
Here the solid arrow with a hollow triangle means «extends»: InputStreamReader is a subclass of Reader. Oracle recommends wrapping it in a BufferedReader for efficient reading; that wrapper is another pattern, Decorator.
SLF4J: your code logs against one API, and at deployment you choose whether Logback, Log4j or java.util.logging sits behind it. Your code is not tied to one logging library.
Step 10 of 12
Trade-off
Adapter changes the shape, it adds no behaviour
A common mistake is calling any wrapper an adapter. The Adapter changes the interface: charge goes in, createCharge comes out. It adds no business rules.
If the wrapper has the same interface as what it wraps and adds something (logs, caching, retries), it is a Decorator.
Another mistake is thinking every library needs an adapter. It only pays off for the ones you do not want leaking into your code or might replace.
Step 11 of 12
Trade-off
When it is too much and when it leaks
Do not use it when the library's API already has the shape you want and you do not plan to replace it. An adapter that copies the SDK 1 to 1, with the same names, only adds a layer.
And watch out for the adapter that leaks: if Payments returns VendorCharge, the vendor's type, Orders and Subscriptions know status and chargeId again. That is 3 classes tied to the SDK: you pay for the extra layer and gain nothing.
Rule of thumb: only your own types appear in the adapter's interface.
Step 12 of 12
Summary
An interface of your own and a class that translates
When an external library's shape spreads across your code, write an interface of your own and an adapter that implements it by translating calls and responses.
Swapping vendors or testing with a fake touches one place, not the business classes. Skip it when the API already suits you, and do not let the vendor's types leave the adapter.
← → step · R replay · Space pause
You will learn
- Recognise the problem: an external library's shape spread across your code. (covered)
- Write the interface your code wants first, without naming the vendor. (covered)
- Translate calls and responses in an adapter class. (covered)
- Swap vendors and test with a fake without touching the business classes. (covered)
- Recognise real adapters such as `InputStreamReader` and SLF4J. (covered)
- Tell it apart from a Decorator and know when it is too much or leaks. (covered)