Adapter

Real-world analogy

When traveling from North America to the United Kingdom, your laptop charger plug has two flat pins designed for 120 V outlets, while the wall socket expects three rectangular pins at 230 V. You do not rewire the hotel wall or solder new prongs onto your charger; instead, you plug your charger into a travel adapter that translates the physical prongs and electrical characteristics.

The problem

You are building an e-commerce checkout pipeline. Your core domain defines an internal payment abstraction, PaymentProcessor, which accepts a customer identifier and a charge amount in whole dollars. You decide to integrate a third-party vendor SDK (StripeGateway). However, the vendor library exposes incompatible method names, requires amounts in integer cents, and expects an opaque card token rather than your internal customer ID.

1 // Naive approach: Direct coupling to vendor SDK in business logic
2 class OrderService {
3   #stripe;
4   constructor(stripe) {
5     this.#stripe = stripe; // Tight coupling to external vendor signature
6   }
7 
8   checkout(customerId, amountDollars) {
9     const cents = Math.round(amountDollars * 100);
10     const token = `tok_${customerId}`;
11     // Directly invoking vendor API scatters vendor types throughout domain
12     return this.#stripe.executeCharge(cents, { cardToken: token });
13   }
14 }

1 public class Example {
2     static class StripeGateway {
3         public String executeCharge(int amountInCents, String cardToken) {
4             return "stripe_ch_" + amountInCents;
5         }
6     }
7 
8     static class OrderService {
9         private final StripeGateway stripe;
10 
11

This naive approach leaks external vendor details across the business domain. If you add PayPal, switch payment processors, or write unit tests, every caller must be refactored.

The solution

The Adapter pattern converts the interface of an existing class (Adaptee) into another interface (Target) that clients expect, allowing classes with incompatible contracts to collaborate seamlessly.

• Target (PaymentProcessor): Defines the domain-specific interface that client code depends on.
• Client (OrderService): Collaborates with objects conforming to the Target interface.
• Adaptee (StripeGateway): The existing or third-party class that has the needed functionality but an incompatible interface.
• Adapter (StripePaymentAdapter): Implements the Target interface and holds an instance of the Adaptee, translating calls and data representations.

Step-by-step implementation

Step 1: Define the target domain contract

Establish the interface your application expects. Callers depend exclusively on this abstraction.

1 class PaymentProcessor {
2   processPayment(customerId, amountDollars) {
3     throw new Error("processPayment() must be implemented");
4   }
5 }

1 public class Example {
2     interface PaymentProcessor {
3         PaymentResult processPayment(String customerId, double amountDollars);
4     }

Step 2: Implement the adapter wrapping the adaptee

Create an adapter that implements the target interface and delegates to the encapsulated vendor SDK instance.

Step 3: Connect client to the adapter

The client relies only on PaymentProcessor. Injecting the adapter satisfies the contract without polluting business rules.

1 class OrderService {
2   #processor;
3   constructor(processor) {
4     this.#processor = processor;
5   }
6 
7   completeOrder(customerId, total) {
8     return this.#processor.processPayment(customerId, total);
9   }
10 }

The complete example

Here is the complete, runnable implementation showing the target interface, vendor adaptee, adapter, and client execution.

1 Order ORD-101: Paid via ch_stripe_4995_tok_usr_99
2 Order ORD-102: Paid via pp_usr_88@customer.internal_12.50

Variations

Object adapter vs class adapter

There are two primary flavors of the Adapter pattern:

1. Object Adapter (Composition): The adapter implements the target interface and holds a reference to an instance of the adaptee. Because it relies on composition, it works in virtually all object-oriented languages (including Java and JavaScript) and can adapt the adaptee as well as any of its subclasses.
2. Class Adapter (Inheritance): The adapter inherits from both the target interface (or class) and the adaptee class simultaneously. This allows the adapter to override adaptee behavior directly without delegating through an internal instance. However, it requires multiple inheritance of classes (supported in C++, but not supported in Java or JavaScript).

Two-way adapters

A Two-Way Adapter implements both the Target interface and the Adaptee interface simultaneously. It provides transparent interoperability in bidirectional environments where Legacy System A needs to invoke Modern System B, and Modern System B simultaneously needs to invoke Legacy System A as if it were a native component.

Where you've already used it

• java.io.InputStreamReader: Adapts a byte stream (InputStream) into a character stream (Reader), handling character encoding conversion internally.
• java.util.Arrays.asList(T...): Adapts a contiguous native array into a fixed-size List<T> contract.
• Node.js util.promisify: Adapts standard error-first callback functions into Promise-returning async functions.
• Spring HandlerAdapter: Adapts arbitrary controller handler methods (annotated methods, functional handlers) to the standard DispatcherServlet request workflow.
• React wrappers: Wrapping an imperative jQuery or Canvas widget inside a declarative React functional component with props and useEffect.

Pros and cons

When not to use it

Do not introduce an Adapter when you own both interfaces and can refactor them directly to agree on a common signature. Introducing an adapter between two internal classes that you can easily edit adds unnecessary boilerplate and indirection.

Related patterns

Interview questions

How does Adapter differ from Facade? Adapter bridges two existing incompatible interfaces, mapping one exact signature to another. Facade defines a new, simplified high-level interface over an entire subsystem without conforming to an existing legacy contract.

Can an Object Adapter adapt subclasses of the Adaptee? Yes. Because an Object Adapter holds a reference to the Adaptee by type composition, polymorphism allows any subclass of the Adaptee to be passed into the Adapter.

What is the Class Adapter pattern and why is it rare in Java and JavaScript? Class Adapter inherits from both the target and the adaptee. Because Java and JavaScript support single class inheritance only, Class Adapter cannot be implemented if both target and adaptee are concrete classes.

What should an adapter do if the target interface expects a capability the adaptee cannot provide? The adapter can provide a sensible default, synthesize the value through auxiliary calls, or throw an explicit UnsupportedOperationException. Documenting this impedance mismatch is critical.