Composite

Composite gives single items and groups the same interface, so code can ask a whole city, a zone or a single station the same question. This page builds Pedal's city as a tree of zones and stations, and shows the bikes that nested loops quietly miss.

1. The pain

Pedal's operations dashboard shows free bikes for the whole city, each zone and each station. London has zones; some zones contain stations directly, and East has a sub-zone, Docklands, with stations of its own. The first version of the dashboard used two nested loops: zones, then the stations in each zone.

The loops quietly skipped Docklands, because a zone inside a zone isn't a station. The fix people reach for is if isinstance(child, Zone): … at every level, in every report that walks the city. Each new level of nesting, or each new report, repeats those checks.

2. The idea in one picture

Composite gives single items (leaves) and groups (composites) the same interface, and lets groups contain either. A Station answers free_bikes() with its own count; a Zone answers by asking each child and adding up. Because a zone's children are just Areas, zones can nest to any depth, and the dashboard calls one method on the city.

The design choice is how much of the interface makes sense for both. free_bikes() does; add_child() doesn't for a station. This page keeps child management on Zone only, so a station can't be asked to hold children.

3. The roles

4. Before and after

Counting free bikes both ways (Python sketch; the full program is in section 5).

def city_free_bikes(city):
    total = 0
    for zone in city.zones:
        for child in zone.children:
            if isinstance(child, Station):
                total += child.free
            elif isinstance(child, Zone):
                for s in child.children:   # one more level...
                    total += s.free
    return total

class Zone(Area):
    def free_bikes(self):
        return sum(c.free_bikes()
                   for c in self.children)

class Station(Area):
    def free_bikes(self):
        return self.free

city.free_bikes()          # 23
zone_east.free_bikes()     # 8

The recursion lives in the tree, once, instead of in every piece of code that walks it.

5. The code

Station and Zone share the Area interface; zones hold areas, including other zones. One call reports the whole city, another finds low stations at any depth.

from __future__ import annotations
from abc import ABC, abstractmethod


class Area(ABC):
    """One interface for a single station and for any group of them."""

    def __init__(self, name: str) -> None:
        self.name = name

    @abstractmethod
    def free_bikes(self) -> int: ...

    @abstractmethod
    def stations(self) -> list[Station]: ...

    @abstractmethod
    def report(self, indent: str = "") -> list[str]: ...


class Station(Area):                       # a leaf
    def __init__(self, name: str, free: int) -> None:
        super().__init__(name)
        self.free = free

    def free_bikes(self) -> int:
        return self.free

    def stations(self) -> list[Station]:
        return [self]

    def report(self, indent: str = "") -> list[str]:
        return [f"{indent}{self.name}: {self.free} free"]


class Zone(Area):                          # a composite: holds areas, which may be zones themselves
    def __init__(self, name: str, children: list[Area]) -> None:
        super().__init__(name)
        self.children = children

    def free_bikes(self) -> int:
        return sum(c.free_bikes() for c in self.children)

    def stations(self) -> list[Station]:
        return [s for c in self.children for s in c.stations()]

    def report(self, indent: str = "") -> list[str]:
        n = len(self.stations())
        head = f"{indent}{self.name}: {self.free_bikes()} free bikes at {n} station{'s' if n != 1 else ''}"
        return [head] + [line for c in self.children for line in c.report(indent + "  ")]


if __name__ == "__main__":
    city = Zone("London", [
        Zone("Central", [Station("S-12 Holborn", 7), Station("S-14 Bank", 8)]),
        Zone("East", [Station("S-31 Bow", 3), Zone("Docklands", [Station("S-40 Canary Wharf", 5)])]),
    ])
    print("\n".join(city.report()))
    low = [s.name for s in city.stations() if s.free_bikes() < 4]
    print(f"stations below 4 free: {', '.join(low)}")
    one: Area = Station("S-12 Holborn", 7)
    print(f"the same call on one station: {one.name} has {one.free_bikes()} free bikes")

// One interface for a single station and for any group of them.
abstract class Area {
  constructor(readonly name: string) {}
  abstract freeBikes(): number;
  abstract stations(): Station[];
  abstract report(indent?: string): string[];
}

class Station extends Area {   // a leaf
  constructor(name: string, private readonly free: number) { super(name); }
  freeBikes(): number { return this.free; }
  stations(): Station[] { return [this]; }
  report(indent = ""): string[] { return [`${indent}${this.name}: ${this.free} free`]; }
}

class Zone extends Area {   // a composite: holds areas, which may be zones themselves
  constructor(name: string, private readonly children: Area[]) { super(name); }
  freeBikes(): number { return this.children.reduce((sum, c) => sum + c.freeBikes(), 0); }
  stations(): Station[] { return this.children.flatMap((c) => c.stations()); }
  report(indent = ""): string[] {
    const n = this.stations().length;
    const head = `${indent}${this.name}: ${this.freeBikes()} free bikes at ${n} station${n !== 1 ? "s" : ""}`;
    return [head, ...this.children.flatMap((c) => c.report(indent + "  "))];
  }
}

const city = new Zone("London", [
  new Zone("Central", [new Station("S-12 Holborn", 7), new Station("S-14 Bank", 8)]),
  new Zone("East", [new Station("S-31 Bow", 3), new Zone("Docklands", [new Station("S-40 Canary Wharf", 5)])]),
]);
console.log(city.report().join("\n"));
const low = city.stations().filter((s) => s.freeBikes() < 4).map((s) => s.name);
console.log(`stations below 4 free: ${low.join(", ")}`);
const one: Area = new Station("S-12 Holborn", 7);
console.log(`the same call on one station: ${one.name} has ${one.freeBikes()} free bikes`);

import java.util.ArrayList;
import java.util.List;

public class Main {
    // One interface for a single station and for any group of them.
    abstract static class Area {
        final String name;
        Area(String name) { this.name = name; }
        abstract int freeBikes();
        abstract List<Station> stations();
        abstract List<String> report(String indent);
    }

    static class Station extends Area {   // a leaf
        private final int free;
        Station(String name, int free) { super(name); this.free = free; }
        int freeBikes() { return free; }
        List<Station> stations() { return List.of(this); }
        List<String> report(String indent) { return List.of(indent + name + ": " + free + " free"); }
    }

    static class Zone extends Area {   // a composite: holds areas, which may be zones themselves
        private final List<Area> children;
        Zone(String name, List<Area> children) { super(name); this.children = children; }
        int freeBikes() { return children.stream().mapToInt(Area::freeBikes).sum(); }
        List<Station> stations() {
            List<Station> out = new ArrayList<>();
            for (Area c : children) out.addAll(c.stations());
            return out;
        }
        List<String> report(String indent) {
            int n = stations().size();
            List<String> out = new ArrayList<>();
            out.add(indent + name + ": " + freeBikes() + " free bikes at " + n + " station" + (n != 1 ? "s" : ""));
            for (Area c : children) out.addAll(c.report(indent + "  "));
            return out;
        }
    }

    public static void main(String[] args) {
        Zone city = new Zone("London", List.of(
            new Zone("Central", List.of(new Station("S-12 Holborn", 7), new Station("S-14 Bank", 8))),
            new Zone("East", List.of(new Station("S-31 Bow", 3), new Zone("Docklands", List.of(new Station("S-40 Canary Wharf", 5)))))));
        System.out.println(String.join("\n", city.report("")));
        List<String> low = new ArrayList<>();
        for (Station s : city.stations()) if (s.freeBikes() < 4) low.add(s.name);
        System.out.println("stations below 4 free: " + String.join(", ", low));
        Area one = new Station("S-12 Holborn", 7);
        System.out.println("the same call on one station: " + one.name + " has " + one.freeBikes() + " free bikes");
    }
}

Output (the same in all three languages)

London: 23 free bikes at 4 stations
  Central: 15 free bikes at 2 stations
    S-12 Holborn: 7 free
    S-14 Bank: 8 free
  East: 8 free bikes at 2 stations
    S-31 Bow: 3 free
    Docklands: 5 free bikes at 1 station
      S-40 Canary Wharf: 5 free
stations below 4 free: S-31 Bow
the same call on one station: S-12 Holborn has 7 free bikes

6. Try it

Ask any part of the city

Click a zone or station to call free_bikes() on it and watch the call spread down the tree. Compare with the two-loop version.

7. When not to use it

8. How it goes wrong

9. Remember it and say it

In an interview or code review

• Say it's a tree of one type: "Stations and zones share an Area interface; a zone holds areas, so nesting is unlimited."
• State the interface decision: child management lives on Zone only (safety) rather than on Area (uniformity).
• Mention cost: totals are recomputed per call; at large scale, keep running counts on each zone.
• Pair it: composites are often walked with an iterator or visited by a visitor (pages 20 and 21).

10. Check yourself

11. Go deeper