Adapter Pattern: Making Incompatible Interfaces Work Together

interface PaymentProcessor {
    PaymentResult charge(String customerId, long amountInCents, String currency);
}

// Third-party SDK — cannot be changed, ships as a compiled dependency
class StripeLegacyClient {
    StripeChargeResponse createCharge(StripeChargeRequest request) {
        // makes an HTTP call to Stripe's legacy API, returns their DTO
        return new StripeChargeResponse();
    }
}
 
class StripeChargeRequest {
    String stripeCustomerToken;
    int amountCents;
    String currencyCode;
    // constructor, getters...
}
 
class StripeChargeResponse {
    String chargeId;
    String status; // "succeeded", "failed", "pending"
}

// VIOLATION: checkout logic is now coupled to a specific vendor's SDK types
class CheckoutService {
    private final StripeLegacyClient stripeClient = new StripeLegacyClient();
 
    void checkout(String customerId, long amountInCents) {
        StripeChargeRequest request = new StripeChargeRequest();
        request.stripeCustomerToken = customerId; // wrong semantics, forced to fit
        request.amountCents = (int) amountInCents; // silent narrowing, long -> int
        request.currencyCode = "USD";
 
        StripeChargeResponse response = stripeClient.createCharge(request);
        if (!"succeeded".equals(response.status)) {
            throw new RuntimeException("payment failed");
        }
        // Every call site that wants to charge a card now has to know Stripe's DTOs.
    }
}

// FIXED: adapter translates between PaymentProcessor and StripeLegacyClient.
// CheckoutService never sees a Stripe type.
class StripePaymentAdapter implements PaymentProcessor {
    private final StripeLegacyClient stripeClient; // composition, not inheritance
 
    StripePaymentAdapter(StripeLegacyClient stripeClient) {
        this.stripeClient = stripeClient;
    }
 
    @Override
    public PaymentResult charge(String customerId, long amountInCents, String currency) {
        StripeChargeRequest request = new StripeChargeRequest();
        request.stripeCustomerToken = customerId;
        request.amountCents = Math.toIntExact(amountInCents); // fail loudly instead of silently narrowing
        request.currencyCode = currency;
 
        StripeChargeResponse response = stripeClient.createCharge(request);
 
        return switch (response.status) {
            case "succeeded" -> PaymentResult.success(response.chargeId);
            case "pending" -> PaymentResult.pending(response.chargeId);
            default -> PaymentResult.failure("stripe charge failed: " + response.status);
        };
    }
}
 
// CheckoutService depends only on the abstraction — completely vendor-agnostic
class CheckoutService {
    private final PaymentProcessor paymentProcessor; // injected
 
    CheckoutService(PaymentProcessor paymentProcessor) {
        this.paymentProcessor = paymentProcessor;
    }
 
    void checkout(String customerId, long amountInCents) {
        PaymentResult result = paymentProcessor.charge(customerId, amountInCents, "USD");
        if (!result.isSuccessful()) {
            throw new PaymentFailedException(result.getMessage());
        }
    }
}

// Class adapter: extends the adaptee, implements the target interface
class StripeClassAdapter extends StripeLegacyClient implements PaymentProcessor {
    @Override
    public PaymentResult charge(String customerId, long amountInCents, String currency) {
        StripeChargeRequest request = new StripeChargeRequest();
        request.stripeCustomerToken = customerId;
        request.amountCents = Math.toIntExact(amountInCents);
        request.currencyCode = currency;
 
        StripeChargeResponse response = createCharge(request); // inherited method, called directly
        return "succeeded".equals(response.status)
            ? PaymentResult.success(response.chargeId)
            : PaymentResult.failure(response.status);
    }
}

interface LegacyNotifier {
    void notifyUser(int userId, String msg);
}
 
interface ModernNotifier {
    void send(NotificationRequest request);
}
 
// Implements BOTH interfaces — can be handed to old callers and new callers alike
class NotifierTwoWayAdapter implements LegacyNotifier, ModernNotifier {
    private final ModernNotifier modernDelegate;
    private final LegacyNotifier legacyDelegate;
 
    NotifierTwoWayAdapter(ModernNotifier modernDelegate, LegacyNotifier legacyDelegate) {
        this.modernDelegate = modernDelegate;
        this.legacyDelegate = legacyDelegate;
    }
 
    @Override
    public void notifyUser(int userId, String msg) {
        // Old caller invokes the legacy method — translate forward to modern
        modernDelegate.send(new NotificationRequest(String.valueOf(userId), msg));
    }
 
    @Override
    public void send(NotificationRequest request) {
        // New caller invokes the modern method — translate backward to legacy
        legacyDelegate.notifyUser(Integer.parseInt(request.getUserId()), request.getMessage());
    }
}

class InMemoryPaymentProcessor implements PaymentProcessor {
    private final Map<String, PaymentResult> scriptedResults = new HashMap<>();
    List<String> chargedCustomers = new ArrayList<>();
 
    void scriptResultFor(String customerId, PaymentResult result) {
        scriptedResults.put(customerId, result);
    }
 
    @Override
    public PaymentResult charge(String customerId, long amountInCents, String currency) {
        chargedCustomers.add(customerId);
        return scriptedResults.getOrDefault(customerId, PaymentResult.success("test-txn"));
    }
}
 
class CheckoutServiceTest {
    @Test
    void checkoutThrowsWhenPaymentFails() {
        InMemoryPaymentProcessor fakeProcessor = new InMemoryPaymentProcessor();
        fakeProcessor.scriptResultFor("cust-1", PaymentResult.failure("card declined"));
        CheckoutService service = new CheckoutService(fakeProcessor);
 
        assertThrows(PaymentFailedException.class, () -> service.checkout("cust-1", 1_000));
    }
}

class StripePaymentAdapterTest {
    @Test
    void mapsStripeSucceededStatusToPaymentSuccess() {
        StripeLegacyClient fakeStripe = new FakeStripeLegacyClient(); // test double for the adaptee
        StripePaymentAdapter adapter = new StripePaymentAdapter(fakeStripe);
 
        PaymentResult result = adapter.charge("cust-1", 500, "USD");
 
        assertTrue(result.isSuccessful());
    }
 
    @Test
    void amountThatOverflowsIntThrowsRatherThanSilentlyTruncating() {
        StripeLegacyClient fakeStripe = new FakeStripeLegacyClient();
        StripePaymentAdapter adapter = new StripePaymentAdapter(fakeStripe);
 
        assertThrows(ArithmeticException.class,
            () -> adapter.charge("cust-1", Long.MAX_VALUE, "USD")); // Math.toIntExact catches this
    }
}

// MISTAKE: every possible failure looks identical to the caller
try {
    StripeChargeResponse response = stripeClient.createCharge(request);
    return toPaymentResult(response);
} catch (Exception e) {
    return PaymentResult.failure("payment error"); // caller can't distinguish retryable vs not
}

// BETTER: translate exception types too, not just the happy-path response
try {
    StripeChargeResponse response = stripeClient.createCharge(request);
    return toPaymentResult(response);
} catch (StripeNetworkException e) {
    throw new PaymentGatewayUnavailableException(e); // caller can retry
} catch (StripeAuthException e) {
    throw new PaymentConfigurationException(e); // caller should page someone, not retry
}