Adapter

The Adapter Pattern (also known as the Wrapper Pattern) is a structural design pattern that acts as a translator between two incompatible interfaces. It wraps an existing class with a new interface matching the client's expectations, enabling integration with third-party libraries, legacy codebases, and vendor APIs without modifying their source code.

1. Learning Objectives

• Identify when to apply the Adapter Pattern to link incompatible software components.
• Compare the tradeoffs of the Object Adapter (Composition) and Class Adapter (Multiple Inheritance) patterns.
• Construct adapter wrapper classes mapping different method names and parameter types.
• Analyze compile-time dependencies when wrapping third-party libraries.
• Implement payment integration adapters in Java, Python, and C++.

2. Problem & Naive Solution

Suppose you are building a checkout system. The application defines a standard PaymentProcessor interface that handles transactions using card details and amounts.

To expand globally, you must integrate a third-party gateway, StripeSDK. However, the SDK's payment method is incompatible: it uses tokenized authorization payloads and different parameter orders.

The Naive Solution

A developer might modify the checkout system directly, bypassing the abstraction to call the SDK methods:

This approach has significant flaws:

• Violates Open/Closed Principle: Adding another provider (e.g. PayPal) forces us to rewrite the client service logic.
• Source Code Inaccessibility: We cannot rewrite the third-party StripeSDK class to implement our PaymentProcessor interface because it belongs to an external vendor.
• Untestability: The service is tightly coupled to the external SDK class, preventing the injection of mock objects for unit testing.

3. Issues

Direct integration of external libraries creates tight coupling. Any update to the third-party library's API signatures forces changes across multiple client modules, causing compile-time errors and deployment delays.

4. Pattern Introduction & UML

The Adapter Pattern decouples the client from incompatible classes by introducing a translator object:

• Target (PaymentProcessor): The interface the client expects.
• Adapter (StripeAdapter): Implements the Target interface, holds a reference to the Adaptee, and translates calls.
• Adaptee (StripeSDK): The incompatible legacy or third-party class that provides the required functionality.
• Client (CheckoutService): Interacts with the system purely through the Target interface.

UML: Object Adapter (Composition-based)

5. Participants

• Target (PaymentProcessor): The abstract interface defining the domain contract.
• Adaptee (StripeSDK): The third-party API containing the necessary business operations.
• Adapter (StripeAdapter): The wrapper class that maps target methods to the adaptee API.
• Client (CheckoutService): Uses the target interface to execute transactions.

6. Theory (Object Adapter vs. Class Adapter)

There are two ways to implement the Adapter pattern:

• Object Adapter (Composition): The adapter implements the target interface and holds a private instance of the adaptee (uses composition). It delegates method calls to the adaptee, translating arguments. This is the preferred approach as it works in all languages and supports polymorphic subclass wrapping.
• Class Adapter (Inheritance): The adapter inherits from both the target interface and the concrete adaptee class (uses multiple inheritance). It overrides the target's methods and calls the inherited adaptee methods directly. This approach is limited to languages that support multiple class inheritance (e.g. C++).

7. Syntax Explanation

Implementing the pattern requires wrapping the adaptee reference in the adapter's field variables:

• Java: Uses composition (e.g., private final StripeSDK sdk;) to hold the adaptee instance inside the adapter class.
• Python: Leverages dynamic delegation, allowing the adapter to forward method calls dynamically.
• C++: Uses smart pointers (e.g. std::unique_ptr<StripeSDK>) to wrap the adaptee instance safely, or uses multiple inheritance to implement a Class Adapter.

8. Step-by-Step Implementation

1. Step 1: Define the target domain interface that the client expects (e.g., PaymentProcessor).
2. Step 2: Declare the concrete adapter class implementing the target interface.
3. Step 3: Inject the incompatible adaptee class instance (e.g., StripeSDK) into the adapter constructor, saving it as a private field.
4. Step 4: Inside the adapter methods, translate parameters (e.g., extracting token details) and delegate execution to the private adaptee reference.
5. Step 5: Modify the client class constructor to accept the target interface, shielding it from concrete adapter details.

9. Complete Code (Mini Project)

10. Code Walkthrough

Let's review the integration logic:

• The client class CheckoutService depends strictly on the target interface PaymentProcessor. It has no compiled dependency or knowledge of Stripe or PayPal classes.
• The StripeAdapter implements the PaymentProcessor interface. It serves as the middleman, wrapping the concrete StripeSDK.
• When the client calls processPayment(), the adapter translates parameters (creating transaction tokens from emails) and delegates execution by calling chargeTokenized() on the wrapped SDK.

11. Execution Flow

1. Initialization: The application instantiates the third-party StripeSDK. It then instantiates StripeAdapter, injecting the SDK reference.
2. Client Trigger: The client triggers the checkout process (checkout.purchaseCart(...)).
3. Translation: The client calls processPayment() on the adapter. The adapter intercepts the call, generates the required tokens, and aligns parameters.
4. Delegation: The adapter calls chargeTokenized() on the wrapped SDK instance, executing the payment.

12. Internal Working (Call Delegation Stack)

Method translation and forwarding add a small execution stack overhead:

• Stack Frame Allocation: When the client calls processPayment(), a stack frame is allocated. The adapter then calls chargeTokenized(), pushing another stack frame.
• Garbage Collection: Temporary objects created during parameter translation (like temporary token strings) are allocated on the heap and GC-collected after the method returns, adding minor memory overhead.

13. Complexity Analysis

• Time Complexity: $O(1)$ constant time overhead for translating parameters and delegating method calls.
• Space Complexity: $O(1)$ constant space. Wrapping requires storing a single reference to the adaptee on the heap.

14. Best Practices

• Prefer Object Adapter (Composition): Favor composition over inheritance. Wrapping the adaptee instance is cleaner, works in single-inheritance languages, and allows the adapter to wrap any adaptee subclass.
• Keep Adapters Cohesive: Keep translation logic simple. Avoid adding unrelated business logic or validation checks inside the adapter class.
• Program to Interfaces: Ensure the client depends only on the target interface, keeping it decoupled from concrete adapter implementations.

15. Common Mistakes

• Forgetting to translate exceptions: Allowing the third-party adaptee's database or network exceptions to propagate raw to the client. The adapter should catch and wrap these in domain-specific exceptions.
• Confusing Adapter with Facade: Using an adapter to simplify a complex subsystem interface. An adapter changes an interface to make it compatible; a Facade simplifies an interface without changing its protocol.
• Over-adapting: Wrapping classes when simple method signature updates or refactoring would resolve the incompatibility.

16. Framework Usage

• Java's Arrays.asList(): Adapts a standard array into a List collection (e.g. List<String> list = Arrays.asList(array);).
• Spring MVC's HandlerAdapter: Spring MVC uses handler adapters to support different controller execution strategies (e.g. SimpleController, AnnotationController) without modifying the dispatcher servlet.

17. Interview Discussion

18. Practice Exercises

• Easy: Write an adapter in Python to make a ThirdPartyTemperatureSensor (exposing temperature in Fahrenheit) work with a system expecting Celsius.
• Medium: Create a C++ LoggerAdapter that wraps a legacy log utility (which uses printf signatures) to match a modern structured logger interface.
• Hard: Design an adapter system in Java that wraps a third-party XML parser library to implement a standard JSONConfigurationParser interface, including parsing translations.

19. Challenge Problem

Design an Analytics Dashboard Integrator. The application imports client logs containing user events in JSON format. You must integrate a legacy enterprise system that exports events in XML format, and a third-party tracking tool that exposes events via CSV format. Design an adapter-based architecture so the central dashboard can ingest events from all three sources using a unified interface. Write the implementation code in Java, Python, or C++ and verify that the dashboard can process events polymorphically.

20. Summary & Cheat Sheet

• The Adapter pattern translates incompatible interfaces to allow classes to work together.
• Object Adapter uses composition (preferred); Class Adapter uses inheritance.
• Adapters should only handle interface translation and parameter alignment, not business logic.
• Target interfaces shield clients from concrete adapter details.

21. Quiz

22. Next Lesson Preview

In the next lesson, we will cover the Facade Pattern. We will learn how to provide a simplified, unified interface to a complex subsystem of classes!