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:

class Shop:
    def __init__(self, gateway):
        self.gateway = gateway

    def pay(self, order, amount):
        if self.gateway.charge(amount):
            print(order + ": paid")
        else:
            print(order + ": declined")

Python has no interfaces: the shop takes any object that has a charge method.

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:
    def make_payment(self, currency, amount_in_cents, options):
        print(f"FastPay: {amount_in_cents} {currency}")
        if amount_in_cents > 100000:
            return "DECLINED"
        return "APPROVED"

It does the same job, in a different shape. The method is called make_payment, 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(FastPayClient())
shop.pay("#1042", 19.99)

Error

AttributeError: 'FastPayClient' object has no attribute 'charge'

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 has a charge method, exactly what the shop expects. Inside, it keeps the FastPay client and translates: euros to cents, "EUR" and empty options, the text to yes or no:

class FastPayAdapter:
    def __init__(self, client):
        self.client = client

    def charge(self, amount):
        cents = round(amount * 100)
        status = self.client.make_payment("EUR", cents, {})
        return status == "APPROVED"

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

shop = Shop(FastPayAdapter(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:

payments = FastPayAdapter(FastPayClient())
print(payments.charge(19.99))

checkout = CheckoutFacade(Stock(), payments, Invoices(), Mailer())
checkout.place_order("Kettle", 24.90)

Step by step, in words

1. The shop calls charge(amount in euros). FastPayClient only has make_payment(currency, cents, options), so a direct call bounces off.
2. FastPayAdapter steps in between: outside it has charge, just as the shop expects, inside it keeps the FastPay client.
3. charge(19.99): the adapter rounds euros to cents, 1999, and calls make_payment 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. place_order: 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

• Python doesn't check types: the shop calls charge on whatever you give it. The adapter only needs a charge method with the right parameters and result. With a foreign object, the error comes only at payment time (AttributeError), not at startup, so a test matters.
• If you want the shape written down, typing.Protocol describes "an object with a charge(amount) -> bool method", and a type checker (mypy) checks it before the program runs.

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:
    def reserve(self, item):
        print("Warehouse: reserving " + item)
        return True

    def release(self, item):
        print("Warehouse: releasing " + item)


class Invoices:
    def issue(self, item, amount):
        print(f"Invoice: {item}, €{amount:.2f}")


class Mailer:
    def send(self, text):
        print("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:
    def __init__(self, stock, payments, invoices, mailer):
        self.stock = stock
        self.payments = payments
        self.invoices = invoices
        self.mailer = mailer

    def place_order(self, item, amount):
        if not self.stock.reserve(item):
            return False
        if not self.payments.charge(amount):
            self.stock.release(item)
            return False
        self.invoices.issue(item, amount)
        self.mailer.send("confirmation for " + item)
        return True

The payments in the facade are an object with charge, 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:

payments = FastPayAdapter(FastPayClient())
checkout = CheckoutFacade(Stock(), payments, Invoices(), Mailer())
checkout.place_order("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()
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?

payments = FastPayAdapter(FastPayClient())
checkout = CheckoutFacade(Stock(), payments, Invoices(), Mailer())
checkout.place_order("TV", 1299)

Answer

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

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

Warehouse: reserving TV
FastPay: 129900 EUR

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(FastPayAdapter(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:2 def __init__(self, client):3 self.client = client45 def charge(self, amount):6 cents = int(amount * 100)7 status = self.client.make_payment("EUR", cents, {})8 return status == "APPROVED"

Check

More precisely, if you are curious

Try it yourself:

print(19.99 * 100)

Output

1998.9999999999998

Python's round rounds halves to even: round(2.5) is 2. For money, where the half goes up, there is Decimal, which keeps the amount exact:

print(round(2.5), round(3.5))

from decimal import Decimal, ROUND_HALF_UP

print((Decimal("0.125") * 100).quantize(Decimal("1"), rounding=ROUND_HALF_UP))

Output

2 4
13

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:
    def send(self, cents, currency):
        print(f"PayNow: {currency} {cents}")
        return 0

Write PayNowAdapter so the shop pays through PayNow without changes:

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

Output

PayNow: EUR 1999
#1042: paid

More tasks

• Cancelling an order. Add cancel_order(item) to the facade: the warehouse releases the item, and the customer gets an email "order cancelled for …".
• A test provider. Write a FakeGateway with a charge method 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: dict and set · 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