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

Adapter

Make an existing class usable through the interface a client already expects, with every translation, including units, error values and exceptions, kept in one wrapper, and choose between an object adapter and a class adapter.

Twelve sensors, one loop

A greenhouse's climate controller runs one loop every ten seconds. It reads twelve temperature sensors, averages them per zone, and decides whether to open the vents, run the heaters or start the misting fans. The loop knows the sensors through one small interface, TemperatureSensor, with a single method: celsius() returns the current reading in degrees Celsius, or throws SensorUnavailable when there is none, in which case the loop leaves that zone's equipment as it was. The loop has run for two years, and all of its tests talk to that interface.

Then the sensor model is discontinued. The replacement probes come with their manufacturer's library, and its class, ProbeV2, looks nothing like TemperatureSensor. It has sample(), which returns an object such as { raw: 7215, unit: "F" }, in hundredths of a degree Fahrenheit. When a probe is unplugged it does not throw: it returns raw: -32768. The library is not yours to change, and the loop is the part of the system you least want to touch.

Two places the difference could go

The quick fix goes into the loop: if (sensor instanceof ProbeV2), convert, check for -32768, carry on. It works for one probe model. The next model brings a second branch, and soon the code that decides when to open a vent also knows how three manufacturers count degrees. Every test of the climate logic now has to fake vendor objects as well.

The other place is a new class between the two. ProbeV2Sensor implements TemperatureSensor and holds one ProbeV2; its celsius() calls sample() and converts the answer. The loop is given one ProbeV2Sensor per new probe and treats it exactly like the old sensors. In the pattern's vocabulary the loop is the Client, TemperatureSensor is the Target it expects, ProbeV2 is the Adaptee, the existing class with the wrong interface, and ProbeV2Sensor is the Adapter, the one class that knows both sides: it converts the interface of an existing class into the one a client already expects, so the two work together without either of them changing.

The loop sees only the Target

The adapter implements the interface the loop already uses and turns each call into the probe library's terms.

What the translation really holds

Renaming sample() to celsius() is the smallest part of the job. raw: 7215 with unit: "F" is 72.15 °F, which the adapter returns as 22.31 °C. That conversion is written once, in the adapter, and no number the loop receives leaves it guessing the unit.

The unplugged probe is the part that matters. Suppose the first version of the adapter converted every sample the same way. Then -32768 becomes -327.68 °F, the adapter returns about -199.8 °C, and the loop does what it was built to do with a zone that cold: it turns on every heater in that zone, on a summer afternoon. The library's way of saying "no reading" has to become the Target's way of saying it, so the adapter checks for the sentinel value and throws SensorUnavailable, and the loop's existing rule, leave the equipment as it is, now covers the new probe without a line of the loop changing. The library's own exceptions get the same treatment. A ProbeTimeout that escapes the adapter is a vendor type the loop would have to know about, so the adapter catches it and throws SensorUnavailable too.

So the interface the adapter has to honour is more than its method names. The unit, the value that means "nothing" and the exceptions a call can throw are all part of what the client relies on, and each of them is translated in the adapter.

Watch outLeaking adaptee-specific logic into the client brings the legacy interface right back out. Say someone adds a check to the loop that ignores readings below -100, because they once saw the probe's sentinel. The loop now depends on ProbeV2 without naming it, and the check only fits that one library: if the next model reports a missing reading as +32767, its 327.67 °F arrives as about 164 °C, passes the check, and the loop opens every vent and starts the misting fans. In the adapter, the same mistake would be fixed in the one class that knows the probe.

Holding the probe, or being one

ProbeV2Sensor as written keeps a ProbeV2 in a field and forwards to it: an object adapter, built by composition. A class adapter inherits from the adaptee instead, class ProbeV2Sensor extends ProbeV2 implements TemperatureSensor, and calls the sample() it inherited. That saves one object and lets the adapter override a ProbeV2 method, but it ties the adapter to that exact class. When the manufacturer ships WirelessProbeV2, a subclass, the object adapter takes it in the same field, while the class adapter, which inherits only ProbeV2's behaviour, needs a second class to adapt it. Inheriting also needs a class the library lets you subclass, and in Java or C# it leaves the vendor's sample() callable on the adapter. Object adapters are the usual choice.

How much an adapter should know

An adapter translates; it does not decide. Say the new probes read half a degree high, and the manufacturer documents that offset for the model. Correcting it in ProbeV2Sensor is right, because it is a fact about the adaptee. A rule that sunny zones should run a degree cooler is climate logic, and it belongs in the loop or its configuration, even if the adapter is the easiest place to type it. One question sorts the two: is the code there because of what this probe reports, or because of how the greenhouse should run? The first is translation; the second is climate logic.

Translating one class's interface is as far as this pattern goes. When the other side is a whole system with a model of its own, with its own codes, identifiers and meanings, keeping that model out of yours is the job of an Anti-Corruption Layer, usually built from adapters and more; Hexagonal (Ports & Adapters) uses the word for the code that connects an application's ports to one technology.

Several patterns wrap an object, and the question that tells them apart is what happens to the interface. An adapter changes it to one that already exists. A Facade creates a new, smaller one over several parts. A Decorator keeps it and adds behaviour; a Proxy keeps it and controls access to the object behind it. Bridge can look like an adapter on a diagram, but its aim is to let two hierarchies vary independently, and it is usually planned before the classes multiply, where an adapter is added to make two existing pieces fit.

Six nodes, two probes

The Adapter Pattern Challenge allows six nodes, which is exactly enough for this greenhouse with two replacement probes from different manufacturers: a Component node for the climate loop, a Port / Interface node for TemperatureSensor, and an Adapter node and a Service node for each probe library. Wire the loop to the interface and to nothing else, and connect each Adapter to the interface it implements and to the Service it translates for. Then spend your attention on the labels of those last edges: write on each one what that adapter converts, such as Fahrenheit, a scale of hundredths or the unplugged value. When every conversion you can name sits on an adapter's edge, neither manufacturer's quirks can reach the loop.

Practice this