Adapter and Facade

Code in:JavaC#PythonJavaScript

In short: Adapter translates a foreign interface into the one your code expects, while Facade hides several subsystems (stock, payment, invoice, email) behind a single method.

Problem

The new provider doesn't fit

The shop pays through its own interface: charge takes the amount in euros and says whether the payment went through. The shop doesn't know who is behind it:

interface PaymentGateway {
    boolean charge(double amount);
}

class Shop {
    private final PaymentGateway gateway;

    public Shop(PaymentGateway gateway) {
        this.gateway = gateway;
    }

    public void pay(String order, double amount) {
        if (gateway.charge(amount)) {
            System.out.println(order + ": paid");
        } else {
            System.out.println(order + ": declined");
        }
    }
}

The company switches its payment provider to FastPay, which charges lower fees. FastPay ships a ready-made library:

// The FastPay library: foreign code you can't change.
class FastPayClient {
    public String makePayment(String currency, long amountInCents, Map<String, String> options) {
        System.out.println("FastPay: " + amountInCents + " " + currency);
        if (amountInCents > 100000) {
            return "DECLINED";
        }
        return "APPROVED";
    }
}

It does the same job, in a different shape. The method is called makePayment, wants a currency, an amount in cents and options, and returns the text "APPROVED" or "DECLINED" instead of yes or no. Handed straight to the shop, it doesn't fit:

Shop shop = new Shop(new FastPayClient());

Error

error: incompatible types: FastPayClient cannot be converted to PaymentGateway

The library is foreign code: you can't add a method to it. Rewriting the shop for FastPay means touching every place that pays, and touching it again with the next provider.

The idea

Two wrappers, two different goals

Both patterns in this lesson wrap foreign code, but they solve different problems.

An Adapter is a class with the shape your code expects, which calls the foreign object inside. It translates the names, the units and the result. Like a travel plug adapter: your charger's plug doesn't fit the socket abroad, the adapter fits both. It adds nothing, it only changes the shape.

A Facade is one simple entry point in front of many classes that have to be used in a certain order. Like a hotel reception: you don't call the cleaners, the kitchen and accounting one by one, you tell the reception.

The difference in short:

• an adapter changes the shape of one interface so it fits another;
• a facade simplifies working with many classes by putting the usual sequence behind one method.

See it

The adapter translates

FastPayAdapter implements PaymentGateway. Inside, it keeps the FastPay client and translates: euros to cents, "EUR" and empty options, the text to yes or no:

class FastPayAdapter implements PaymentGateway {
    private final FastPayClient client;

    public FastPayAdapter(FastPayClient client) {
        this.client = client;
    }

    @Override
    public boolean charge(double amount) {
        long cents = Math.round(amount * 100);
        String status = client.makePayment("EUR", cents, Map.of());
        return status.equals("APPROVED");
    }
}

The shop gets the adapter instead of the client. Nothing in it changes:

Shop shop = new Shop(new FastPayAdapter(new FastPayClient()));
shop.pay("#1042", 19.99);
shop.pay("#1043", 1299);

Output

FastPay: 1999 EUR
#1042: paid
FastPay: 129900 EUR
#1043: declined

The €1299 TV is above FastPay's limit (€1000), so it is declined. The shop learns about it in its own language: false.

The scene shows the adapter, then the facade from the next card:

PaymentGateway payments = new FastPayAdapter(new FastPayClient());
System.out.println(payments.charge(19.99));

CheckoutFacade checkout = new CheckoutFacade(new Stock(), payments, new Invoices(), new Mailer());
checkout.placeOrder("Kettle", 24.90);

Step by step, in words

1. The shop calls charge(amount in euros). FastPayClient only has makePayment(currency, cents, options), so a direct call bounces off.
2. FastPayAdapter steps in between: outside it is PaymentGateway with charge, inside it keeps the FastPay client.
3. charge(19.99): the adapter rounds euros to cents, 1999, and calls makePayment with "EUR".
4. FastPay answers "APPROVED", and the adapter turns it into true: the shop's own language.
5. CheckoutFacade gets the warehouse, the payments (the same adapter), the invoices and the email.
6. placeOrder: first the warehouse reserves the kettle.
7. Then the payment, through the adapter again: €24.90 becomes 2490 cents.
8. It went through, so the facade issues the invoice and sends the email. The caller wrote one line.

More precisely, if you are curious

• The standard library has adapters too. InputStreamReader turns a stream of bytes into a stream of characters (a Reader), and Arrays.asList shows an array as a List.
• The adapter keeps the foreign object in a field (composition). It could inherit from it instead (class FastPayAdapter extends FastPayClient implements PaymentGateway), but then the shop also sees every FastPay method, and one adapter can't wrap a client that already exists.

See it

The facade in front of four classes

The payment is only one step of an order. Before it, the warehouse reserves the item, and after it come the invoice and the email. If the payment is declined, the warehouse releases the item. Each step is a small class:

class Stock {
    public boolean reserve(String item) {
        System.out.println("Warehouse: reserving " + item);
        return true;
    }

    public void release(String item) {
        System.out.println("Warehouse: releasing " + item);
    }
}

class Invoices {
    public void issue(String item, double amount) {
        System.out.printf("Invoice: %s, €%.2f%n", item, amount);
    }
}

class Mailer {
    public void send(String text) {
        System.out.println("Email: " + text);
    }
}

Without a facade, every place that takes an order (the website, the mobile app, phone orders) writes the same thing, in the same order:

if (stock.reserve(item)) {
    if (payments.charge(amount)) {
        invoices.issue(item, amount);
        mailer.send("confirmation for " + item);
    } else {
        stock.release(item);
    }
}

If one place forgets stock.release, the item stays reserved for an order that was never paid. CheckoutFacade writes the order once:

class CheckoutFacade {
    private final Stock stock;
    private final PaymentGateway payments;
    private final Invoices invoices;
    private final Mailer mailer;

    public CheckoutFacade(Stock stock, PaymentGateway payments, Invoices invoices, Mailer mailer) {
        this.stock = stock;
        this.payments = payments;
        this.invoices = invoices;
        this.mailer = mailer;
    }

    public boolean placeOrder(String item, double amount) {
        if (!stock.reserve(item)) {
            return false;
        }
        if (!payments.charge(amount)) {
            stock.release(item);
            return false;
        }
        invoices.issue(item, amount);
        mailer.send("confirmation for " + item);
        return true;
    }
}

The payments in the facade are a PaymentGateway, handed in from outside (dependency injection from the lesson "Singleton and Dependency Injection"). Here it is the adapter from the previous card. The two patterns work together:

PaymentGateway payments = new FastPayAdapter(new FastPayClient());
CheckoutFacade checkout = new CheckoutFacade(new Stock(), payments, new Invoices(), new Mailer());
checkout.placeOrder("Kettle", 24.90);

Output

Warehouse: reserving Kettle
FastPay: 2490 EUR
Invoice: Kettle, €24.90
Email: confirmation for Kettle

A facade isn't a wall. The classes behind it can still be used directly when you need something off the usual path. Accounting issues the invoice again:

Invoices invoices = new Invoices();
invoices.issue("Kettle", 24.90);

Output

Invoice: Kettle, €24.90

Try it

Predict the output

The classes are from the cards "The adapter translates" and "The facade in front of four classes". What does the program print?

PaymentGateway payments = new FastPayAdapter(new FastPayClient());
CheckoutFacade checkout = new CheckoutFacade(new Stock(), payments, new Invoices(), new Mailer());
checkout.placeOrder("TV", 1299);

Answer

Warehouse: reserving TV
FastPay: 129900 EUR

Warehouse: reserving TV
FastPay: 129900 EUR
Warehouse: releasing TV

Warehouse: reserving TV
FastPay: 129900 EUR
Invoice: TV, €1299.00
Email: confirmation for TV

Check

Try it

Find the bug

A colleague "simplified" the adapter: cents are a whole number anyway. A customer pays order #1042 for €19.99:

Shop shop = new Shop(new FastPayAdapter(new FastPayClient()));
shop.pay("#1042", 19.99);

Output

FastPay: 1998 EUR
#1042: paid

FastPay took 1998 cents, one short. On which line of the adapter is the bug?

Pick the line with the bug.

1class FastPayAdapter implements PaymentGateway {2 private final FastPayClient client;34 public FastPayAdapter(FastPayClient client) {5 this.client = client;6 }78 @Override9 public boolean charge(double amount) {10 long cents = (long) (amount * 100);11 String status = client.makePayment("EUR", cents, Map.of());12 return status.equals("APPROVED");13 }14}

Check

More precisely, if you are curious

Try it yourself:

System.out.println(19.99 * 100);

Output

1998.9999999999998

For money without rounding along the way there is BigDecimal: new BigDecimal("19.99") is exactly 19.99. That is why large systems keep amounts in BigDecimal or straight in cents (long), and use double only for display.

The idea

When you don't need them

You don't need an adapter when both sides are your own code. Then change one side to fit the other instead of putting a translator between them. An adapter is for code you can't touch: a foreign library, an old system, another team's service.

You don't need a facade when the sequence is used in one place. A single function there is enough. A facade also has a trap: it easily becomes the class everything goes through, with a method for every need of every screen. Keep only the usual paths in it, and call the classes directly for the rest.

Both patterns are thin. An adapter that starts deciding business rules (discounts, limits) isn't an adapter anymore. Neither is a facade that computes amounts itself instead of calling the classes that do.

Exercise

A second provider

Solve it in your own editor.

PayNow. The company adds a second provider, PayNow. Its library wants the cents first and the currency second, and returns a number: 0 means success, anything else is a decline.

class PayNowApi {
    public int send(int cents, String currency) {
        System.out.println("PayNow: " + currency + " " + cents);
        return 0;
    }
}

Write PayNowAdapter so the shop pays through PayNow without changes:

Shop shop = new Shop(new PayNowAdapter(new PayNowApi()));
shop.pay("#1042", 19.99);

Output

PayNow: EUR 1999
#1042: paid

More tasks

• Cancelling an order. Add cancelOrder(item) to the facade: the warehouse releases the item, and the customer gets an email "order cancelled for …".
• A test provider. Write FakeGateway implements PaymentGateway that declines any amount over €50. Hand it to the facade and check that the warehouse releases the item on a decline.
• The invoice fails. Let issuing the invoice throw an exception. The money has already been taken. What should the facade do? Decide and write it: for example, carry on with the email and record the error so the invoice is issued later.

Test

Test yourself

1. The provider's library has a method with a different name, units and result from what your code expects. Which pattern fits?

AdapterObserverFacade

2. The website, the mobile app and phone orders repeat the same four steps in the same order. Which pattern fits?

FacadeAdapterSingleton

3. With a facade in place, can the warehouse and the invoices still be used directly?

No, the facade hides them completelyOnly if the facade is a singletonYes, the facade is a short path, not a wall

4. The adapter turns €19.99 into cents by cutting off the fraction. What does the provider get?

199919982000

Check

Start the lesson over

Related lessons

• Builds on: HashMap and HashSet · Design patterns · Strategy · Singleton and Dependency Injection
• Continues in: The shop: which pattern where · Hexagonal and clean architecture · Integrating old and foreign systems
• Tasks on this topic: Design patterns