Learn

Architecture & pattern guides

Read the idea, build it on a Grid, prove it in a challenge. Short, practical guides — illustrated with RodGrid's own nodes — on system design, design patterns, flow modeling, and how to get the most out of the app.

All articles

Bridge

Split a design that would need one class per combination into two hierarchies, an abstraction and an implementation, joined by a reference instead of inheritance so each side grows on its own.

Nine classes for three documents

KioskBoardingPass, KioskVehicleTicket, KioskReceipt, DeskBoardingPass, DeskVehicleTicket, DeskReceipt, PdfBoardingPass, PdfVehicleTicket, PdfReceipt. Those were the nine classes a ferry operator's ticketing service used to print three documents in three places. The kiosks at the port print on thermal receipt printers driven by ESC/POS commands. The purser's desk on each ship has a label printer that takes ZPL, Zebra's printer language. Passengers who book online get a PDF by email. Each class knew two things at once: what goes on its document (for a vehicle ticket, the plate, the length band, the deck and a QR code for the loading crew) and how to put that on one device.

In March the loading crews asked for the deck number in large type at the top of the vehicle ticket, because they read it through a windscreen. A developer changed KioskVehicleTicket and PdfVehicleTicket. DeskVehicleTicket lived in another folder, written by the team that installed the ship printers, and its layout was a year-old copy of the kiosk version with the commands swapped. Nobody opened it. For three weeks, cars ticketed at the purser's desk boarded with the deck number in small print at the bottom.

Two questions in one class name

Every one of those class names answers two independent questions: which document, and which output. Subclassing grows along one line at a time, so each pair of answers became a class of its own: 3 documents × 3 outputs = 9. The operator was about to add a fourth output, an app that shows the documents on a phone, and a fourth document, a cabin card for overnight crossings: 4 × 4 = 16 classes, each layout copied four times and each device's command code four times. The copies are what drifted. The deck-number rule had three places to live, and a fix that reached two of them looked finished.

Cutting along the seam

The fix is to pull the two questions apart, give each its own hierarchy, and join the hierarchies with a reference instead of inheritance. The pattern takes its name from that reference: it is called Bridge. On one side is the abstraction, Document: what the passenger or the crew needs to see. Its subclasses, the refined abstractions BoardingPass, VehicleTicket and Receipt, each lay out their own content. On the other side is the implementor, an interface called PrintTarget, with its concrete implementors KioskPrinter, DeskPrinter and PdfOutput. A Document receives a PrintTarget when it is built and keeps it in a field, the only place the two sides touch.

The vehicle ticket's layout is now written once, in VehicleTicket, as calls on its target: a heading with the deck number in large type, the plate, the length band, the QR code, then the end of the document. KioskPrinter turns those calls into ESC/POS bytes, DeskPrinter into a ZPL label, PdfOutput into a page. The March fix becomes one change in one class, and the purser's desk gets it with everyone else. Three documents and three outputs are six concrete classes instead of nine. The phone app is one new implementor and the cabin card one new refined abstraction: 4 + 4 = 8 classes instead of 16, and neither addition edits the other side.

A Document holds a PrintTarget

The documents extend Document and the printers implement PrintTarget. The one line between the two sides is the reference Document keeps.

What crosses the bridge

The hard part of the design is choosing what PrintTarget offers. The first draft copied the kiosk printer's vocabulary: printLine, printQr, cut. cut gave the problem away. A PDF has no paper to cut, and the label printer does not take a stream of lines at all: a ZPL label places each field at coordinates on the label. The interface had been written from one implementation, and the other two would have had to fake it.

The version that stayed describes what a document needs, not what one device does: heading(text), line(text), qr(data) and finish(). Each implementor decides how to carry them out, as long as a heading stands out on every output. KioskPrinter.finish() feeds and cuts the paper, PdfOutput.finish() closes the page, and DeskPrinter collects the fields as they arrive, works out their positions and sends one label on finish(). The two interfaces sit at different levels, and that is normal for Bridge: the implementor offers small primitive operations, and the abstraction builds higher-level ones out of them. Document can have a printFor(booking) that no printer knows about, and no document knows how qr(data) is drawn.

Sooner or later one target can do something the others cannot: the PDF can carry the operator's logo in colour, and the ship and kiosk printers have no logo loaded. An empty logo() in two of the three printers is honest only if a ticket without a logo is still a correct ticket. If a document must not go out without a feature only one target has, the two sides are not independent for that document, and a method that silently does nothing hides that. Such a document has to ask its target what it supports, or be built only with targets that can serve it.

Same boxes, different reasons

When the ships' printers arrived, their vendor's library had its own interface, a print job with a method that adds a field at given coordinates. DeskPrinter wraps that library and turns each PrintTarget call into the library's calls, which makes it an Adapter: it converts an interface that already exists into the one the code expects. Bridge is a seam drawn so that both sides can grow, usually before the classes multiply, though the ferry's came after nine; Adapter repairs a mismatch between two things that already exist, and a bridge can have adapters among its implementors. An object calling through an interface also describes Strategy, which swaps one algorithm inside one context: if Document had no subclasses and only the output varied, the design would be close to one. What makes this one a Bridge is that both sides are meant to grow.

Before you draw a second hierarchy

Watch outCommon mistake: reaching for Bridge when only one dimension actually varies. An operator that prints one kind of ticket, or many documents on one printer it has no plan to replace, gains a second hierarchy that plain inheritance, or a single class, would cover more simply. The cost is more than an extra file: an implementor interface with one implementation is easily designed from that implementation, the way the first PrintTarget got cut(), so the day a second implementor really arrives, the interface often has to be redesigned anyway.

The other way to lose the split is from the inside. A VehicleTicket that checks whether its target is a DeskPrinter, to move the QR code to the right where labels have room, works on the day it is written. It also reconnects the two hierarchies through one line: the phone app's implementor, added later, gets the kiosk layout until someone finds that check. A difference that depends on the device belongs behind the interface, in the implementor, or in a primitive that the interface offers to every document.

That is the habit the Bridge Pattern Challenge rewards. Its eight nodes fit the ferry's design: a Bridge node for Document, a Port / Interface node for PrintTarget, two refined documents and three printers as Component nodes, and a Client for the kiosk software that builds the pair. Label the edge from Document to PrintTarget as a reference, not as inheritance, then read the drawing from each refined document: every path to a concrete printer should pass through PrintTarget. A path that skips it is the DeskPrinter check from the paragraph above, drawn as an edge.

Practice this