Decorator Pattern

Description

Decorator is the structural pattern for adding behavior to an object without changing its class: you wrap it in another object with the same interface, which does its extra work and passes the call along. Because each wrapper is still a valid object of that interface, wrappers stack - which is how java.io streams, Python's file layers and web middleware are built. This skill covers the pattern, how stacking works, and why the order of the layers matters.

A coffee shop sells espresso with optional milk, sugar and caramel. Model each combination as a subclass and you get EspressoWithMilk, EspressoWithMilkAndSugar, EspressoWithSugarAndCaramel... Three add-ons already mean eight classes, and every new add-on doubles the count.

The other obvious fix - boolean flags on one big class - means every new add-on edits that class, and the pricing method turns into a pile of if statements.

We'll go from simple to more technical:

1. The pattern: component, concrete component and decorator - and how it differs from Python's @ syntax.
2. How a stack of decorators handles a call, step by step.
3. Where you'll see decorators in the standard libraries and frameworks.
4. Order, identity and the other ways stacks surprise people.

The pattern

A Decorator wraps an object that has the same interface and adds one piece of behavior before or after passing the call along. Because the wrapper is itself a valid object of that interface, wrappers can be stacked.

Not Python's @ syntax. A Python decorator (@functools.cache, @app.get("/")) is a function that wraps another function once, when it is defined. The idea is the same - wrap, forward, add one thing - but this pattern wraps objects, at run time, and each object can get a different stack.

• Component - the shared interface (Coffee).
• Concrete component - the plain object (Espresso).
• Decorator - implements Coffee and holds another Coffee.

interface Coffee {
    double cost();
    String description();
}

class Espresso implements Coffee {
    public double cost() { return 2.00; }
    public String description() { return "Espresso"; }
}

abstract class CoffeeDecorator implements Coffee {
    protected final Coffee inner;
    CoffeeDecorator(Coffee inner) { this.inner = inner; }
}

class Milk extends CoffeeDecorator {
    Milk(Coffee inner) { super(inner); }
    public double cost() { return inner.cost() + 0.50; }
    public String description() { return inner.description() + ", milk"; }
}

Coffee order = new Sugar(new Milk(new Espresso()));   // any combination, built at runtime

from abc import ABC, abstractmethod


class Coffee(ABC):
    @abstractmethod
    def cost(self) -> float: ...

    @abstractmethod
    def description(self) -> str: ...


class Espresso(Coffee):
    def cost(self) -> float:
        return 2.00

    def description(self) -> str:
        return "Espresso"


class CoffeeDecorator(Coffee):
    def __init__(self, inner: Coffee):
        self._inner = inner


class Milk(CoffeeDecorator):
    def cost(self) -> float:
        return self._inner.cost() + 0.50

    def description(self) -> str:
        return self._inner.description() + ", milk"


order = Sugar(Milk(Espresso()))   # any combination, built at runtime

How it works, step by step

1. All objects share one interface, so a decorated coffee is still a Coffee.
2. Each decorator forwards the call to the object it wraps...
3. ...and adds its own work before or after (here: add its price, append its name).
4. Wrap as many times as you like; the outermost decorator is called first.
5. Adding a new add-on means writing one new decorator class. Nothing else changes.

Where you'll see it

• java.io: new BufferedReader(new InputStreamReader(new FileInputStream(file))) - each layer adds buffering or decoding.
• Collections.unmodifiableList(list) and Collections.synchronizedList(list) return decorators around your list.
• In Python, io.BufferedReader(raw) and gzip.GzipFile(fileobj=f) wrap file objects the same way, and WSGI/ASGI middleware wraps a web app.
• Web middleware and servlet filters follow the same idea: each layer adds logging, compression or authentication around the next.

Choosing among the structural patterns

Common mistakes

Check yourself

Try to answer before opening each one - recalling beats re-reading.

1. Four optional add-ons. How many subclasses cover every combination, and how many decorators?

2. new Encrypting(new Compressing(file)) - which transformation does written data go through first?

3. Why can coffee instanceof Espresso be false for a decorated espresso?

Key takeaways

• A decorator wraps an object with the same interface and adds one behavior.
• Decorators stack, so N options need N classes instead of 2^N subclasses.
• The order of wrapping changes the result - choose it deliberately.
• A decorated object is a different object: don't rely on == or instanceof for it.
• java.io streams are the textbook example.