Part of the Design Patterns series. For a high-level overview of software design patterns and principles, see Design Patterns: An Architectural Overview.

Sub-blogs in this series:

• Creational Patterns
• Structural Patterns (Current)
• Behavioral Patterns

Structural Patterns

Structural design patterns explain how to assemble objects and classes into larger structures while keeping these structures flexible, decoupled, and efficient.

Where creational patterns govern instantiation and lifecycle, structural patterns focus on composition over inheritance—identifying simple ways to realize relationships between entities without introducing tight coupling or class explosion.

The "Wrapper-Kinda" Patterns

A large family of structural patterns are colloquially grouped as "wrapper-kinda patterns":

• Decorator
• Facade
• Adapter
• Proxy

The distinction between these patterns comes down to intent, while "wrapper" is an umbrella programming term rather than a separate pattern:

• Facade creates a new, simplified interface to make an entire complex subsystem easier to use.
• Adapter converts an existing incompatible interface into an expected target interface so two systems can collaborate.
• Wrapper is not a distinct pattern—it is the structural idiom of placing an outer class around an inner object, and is the official Gang of Four (GoF) alias for both Adapter and Decorator.

1. Adapter vs. Wrapper

In the software design literature, "Wrapper" is a general category:

• GoF Alias: The original Gang of Four book explicitly lists "Wrapper" as an alternate name for two patterns:
  • Adapter (Wrapper): Wraps an object to change its interface to match what a caller expects.
  • Decorator (Wrapper): Wraps an object to add behavior/responsibilities dynamically without changing its interface.
• Idiomatic usage: Whenever developers write a class that holds an instance of another class and forwards calls to it, they say they are "wrapping" it. Every Adapter is a Wrapper, but not every Wrapper is an Adapter (it could be a Decorator, a Proxy, or a simple utility wrapper like Integer wrapping int).

2. Facade vs. Adapter

Code Comparison

Adapter: Translating an Existing Class to an Expected Interface

You have an existing payment interface (PaymentProcessor) that your checkout flow uses. You want to integrate a third-party SDK (PayPalSdk) that has completely different method signatures.

// 1. The interface your system already uses
public interface PaymentProcessor {
    void pay(double amountInCents);
}

// 2. The existing third-party class with an incompatible interface
public class PayPalSdk {
    public void makePayment(BigDecimal dollars, String currency) {
        // Third-party execution logic
    }
}

// 3. The Adapter: Wraps the SDK to conform to your existing interface
public class PayPalAdapter implements PaymentProcessor {
    private final PayPalSdk payPalSdk;

    public PayPalAdapter(PayPalSdk payPalSdk) {
        this.payPalSdk = payPalSdk;
    }

    @Override
    public void pay(double amountInCents) {
        BigDecimal dollars = BigDecimal.valueOf(amountInCents / 100.0);
        payPalSdk.makePayment(dollars, "USD");
    }
}

The client calls paymentProcessor.pay(5000) without knowing PayPal is under the hood. The target interface already existed; the adapter made the alien class fit it.

Facade: Orchestrating Multiple Subsystems Behind a Simpler API

You have multiple separate services (Inventory, Payment, Notification, Shipping). Clients shouldn't manage their orchestration order or error handling directly.

public class OrderFulfillmentFacade {
    private final InventoryService inventory;
    private final PaymentProcessor payment;
    private final ShippingService shipping;
    private final NotificationService notifier;

    public OrderFulfillmentFacade(InventoryService inventory, PaymentProcessor payment,
                                  ShippingService shipping, NotificationService notifier) {
        this.inventory = inventory;
        this.payment = payment;
        this.shipping = shipping;
        this.notifier = notifier;
    }

    // A single simple method replacing dozens of client-side coordination calls
    public OrderReceipt placeOrder(String itemId, int qty, String userEmail, String address) {
        inventory.reserve(itemId, qty);
        double cost = inventory.calculatePrice(itemId, qty);
        payment.pay(cost);
        String trackingId = shipping.ship(itemId, qty, address);
        notifier.sendConfirmation(userEmail, trackingId);
        
        return new OrderReceipt(trackingId, cost);
    }
}

Mental Model Summary

• "I can't plug Class A into Class B because their method names/signatures don't match." $\rightarrow$ Use an Adapter.
• "Using this library/system requires 15 method calls across 4 different objects." $\rightarrow$ Use a Facade.
• "I want to add caching/logging/metrics around an object without modifying its class." $\rightarrow$ Use a Decorator (often colloquially called a Wrapper).
• "I want to control access, lazy-load, or intercept calls to an object without the client knowing." $\rightarrow$ Use a Proxy.

1. Adapter Pattern

The Adapter pattern converts the interface of an existing class into another interface clients expect. It allows classes with incompatible interfaces to work together without modifying either codebase.

• Target: The interface the domain or client code depends upon.
• Adaptee: The existing component or external library with an incompatible interface.
• Adapter: The bridge class that implements Target and wraps Adaptee, translating method calls and parameter shapes.

Real-World Example from GitHub: Python's psf/requests

A prominent real-world implementation of the Adapter pattern is the HTTPAdapter in Python's psf/requests repository (requests/adapters.py).

The Problem

The requests library exposes a developer-friendly API centered around Request and Response objects, connection sessions, and URL routing. However, requests does not handle low-level sockets, HTTP connection pooling, or TLS negotiation itself—it delegates those tasks to urllib3.

urllib3 exposes a completely different interface via PoolManager.urlopen(), taking raw socket arguments and returning urllib3.response.HTTPResponse. The requests.Session class cannot interact directly with urllib3 without hardcoding protocol logic into the high-level API.

Pattern Mapping

Code Structure

1. The Target Interface (BaseAdapter)

In requests/adapters.py, BaseAdapter defines the contract that Session interacts with:

class BaseAdapter:
    """The base interface for transport adapters."""

    def __init__(self):
        super().__init__()

    def send(self, request, stream=False, timeout=None, verify=True, cert=None, proxies=None):
        """Sends PreparedRequest object. Returns Response object."""
        raise NotImplementedError

    def close(self):
        """Cleans up adapter specific items."""
        raise NotImplementedError

2. The Adaptee (urllib3.PoolManager)

urllib3 manages raw pools and connections via its own method signature:

# Low-level interface inside urllib3
response = pool_manager.urlopen(
    method="GET",
    url="/endpoint",
    body=raw_bytes,
    headers=header_dict,
    retries=retry_config,
    # ...
)

3. The Adapter (HTTPAdapter)

HTTPAdapter wraps the urllib3.PoolManager instance (the Adaptee) and implements the send() method defined by BaseAdapter (the Target):

class HTTPAdapter(BaseAdapter):
    def __init__(self, pool_connections=10, pool_maxsize=10, max_retries=0, **kwargs):
        super().__init__()
        # Encapsulates the adaptee
        self.poolmanager = urllib3.PoolManager(
            num_pools=pool_connections,
            maxsize=pool_maxsize,
            # ...
        )

    def send(self, request, stream=False, timeout=None, verify=True, cert=None, proxies=None):
        # 1. Translate high-level PreparedRequest data into urllib3 urlopen() arguments
        conn = self.get_connection(request.url, proxies)
        low_level_resp = conn.urlopen(
            method=request.method,
            url=request.path_url,
            body=request.body,
            headers=request.headers,
            redirect=False,
            assert_same_host=False,
            preload_content=False,
            decode_content=False,
            # ...
        )
        # 2. Convert urllib3.response.HTTPResponse into requests.Response
        return self.build_response(request, low_level_resp)

4. The Client (Session)

requests.Session interacts exclusively with the BaseAdapter interface:

class Session:
    def __init__(self):
        self.adapters = OrderedDict()
        # Mount the adapter to URL prefixes
        self.mount("https://", HTTPAdapter())
        self.mount("http://", HTTPAdapter())

    def send(self, request, **kwargs):
        # Retrieve the adapter mounted for the given scheme
        adapter = self.get_adapter(url=request.url)
        # Execute via the target interface
        return adapter.send(request, **kwargs)

Why This Design Works

• Decoupling: requests.Session knows nothing about socket timeouts, pooling, or urllib3 internals.
• Pluggability: Third-party libraries can provide custom adapters conforming to BaseAdapter—such as requests-mock (for unit testing without network calls) or requests-cache—and mount them directly using session.mount('custom://', CustomAdapter()) without altering Session code.

Another Notable Example: axios/axios

In JavaScript/TypeScript, axios/axios (lib/adapters/) uses the Adapter pattern to run the identical high-level axios.get() / axios.post() API across both the browser and Node.js runtimes:

• lib/adapters/xhr.js: Adapts browser-native XMLHttpRequest to return a unified AxiosPromise.
• lib/adapters/http.js: Adapts Node.js core modules (http and https) to the identical AxiosPromise return shape.

2. Facade Pattern

The Facade pattern creates a brand-new, unified high-level interface to make a complex subsystem easier to use.

Rather than hiding the subsystem from power users who need granular control, the Facade provides a convenient entry door for the most common 80% use case (such as OrderFulfillmentFacade above coordinating inventory, payment, shipping, and notification).

3. Decorator Pattern

The Decorator pattern attaches additional responsibilities to an object dynamically. Decorators provide a flexible alternative to subclassing for extending functionality.

Unlike an Adapter (which changes the interface), a Decorator implements the exact same interface as the object it wraps:

// Component interface
public interface DataService {
    String fetchData(String query);
}

// Concrete Component
public class DatabaseService implements DataService {
    @Override
    public String fetchData(String query) {
        // Direct database query
        return "Raw result for: " + query;
    }
}

// Base Decorator
public abstract class DataServiceDecorator implements DataService {
    protected final DataService wrappee;

    public DataServiceDecorator(DataService wrappee) {
        this.wrappee = wrappee;
    }

    @Override
    public String fetchData(String query) {
        return wrappee.fetchData(query);
    }
}

// Concrete Decorator: Caching
public class CachingDataDecorator extends DataServiceDecorator {
    private final Map<String, String> cache = new ConcurrentHashMap<>();

    public CachingDataDecorator(DataService wrappee) {
        super(wrappee);
    }

    @Override
    public String fetchData(String query) {
        return cache.computeIfAbsent(query, wrappee::fetchData);
    }
}

Decorators can be stacked recursively at runtime:

DataService service = new LoggingDataDecorator(new CachingDataDecorator(new DatabaseService()));

4. Proxy Pattern

The Proxy Pattern is a structural design pattern that provides a surrogate or placeholder for another object to control, mediate, or enhance access to it.

Instead of client code communicating directly with a resource-heavy or sensitive object, it communicates with the Proxy. Because the Proxy implements the exact same interface as the target (the Real Subject), client code cannot tell the difference.

Core Anatomy

       +-----------------------+
       |     <<Interface>>     |
       |        Subject        |
       |  + request(): void    |
       +-----------------------+
              ^          ^
              |          |
    implements|          | implements
              |          |
+-------------------+  +--------------------------------+
|    RealSubject    |  |             Proxy              |
| + request(): void |  | - realSubject: RealSubject      |
+-------------------+  | + request(): void              |
          ^            +--------------------------------+
          |                       |
          +---- delegates to -----+

1. Subject Interface: Declares common operations implemented by both RealSubject and Proxy.
2. Real Subject: The core class providing the actual business logic or heavy resource.
3. Proxy: Maintains a reference to the RealSubject, handles access controls, caching, or lazy initialization, and delegates execution when appropriate.

Common Types of Proxies

• Virtual Proxy (Lazy Loading): Postpones the instantiation of memory-intensive or slow objects until they are actually invoked (e.g., Hibernate uninitialized entity proxies).
• Protection Proxy (Security & Access Control): Checks caller permissions, roles, or tokens before allowing invocation of the underlying subject.
• Smart / Intercepting Proxy (Resource Management & AOP): Injects operational logic—such as tracking connection lifecycles, statement cleaning, or wrapping operations inside database transactions (e.g., Spring AOP, connection pools).
• Remote Proxy: Acts as a local representation of an object running across a network or in another JVM (e.g., gRPC stubs, Java RMI).

Real-World Java Usage from GitHub: HikariCP

In production systems, JDBC connection pools like HikariCP rely heavily on the Proxy Pattern.

The Problem

When application code invokes connection.close(), closing the actual underlying physical TCP socket to the database is expensive. The connection pool needs close() to mean "return this connection to the pool for reuse" rather than terminating the database socket.

The Implementation

HikariCP implements java.sql.Connection via com.zaxxer.hikari.pool.ProxyConnection:

• Subject: java.sql.Connection
• Real Subject: The driver's physical JDBC connection (e.g., org.postgresql.jdbc.PgConnection)
• Proxy: com.zaxxer.hikari.pool.ProxyConnection

Here is a simplified view of how HikariCP structures this on GitHub:

// 1. Subject Interface: java.sql.Connection
package com.zaxxer.hikari.pool;

import java.sql.Connection;
import java.sql.SQLException;

// 2. Proxy: Implements Connection, holds delegate to real physical driver connection
public abstract class ProxyConnection implements Connection {
    
    // The underlying physical JDBC connection provided by the database driver
    protected Connection delegate;
    
    private final PoolEntry poolEntry;
    private final FastList<Statement> openStatements;
    private boolean isClosed;

    protected ProxyConnection(PoolEntry poolEntry, Connection connection, ...) {
        this.poolEntry = poolEntry;
        this.delegate = connection;
        this.openStatements = ...;
    }

    // 3. Intercepted method: Controls access & alters standard behavior
    @Override
    public final void close() throws SQLException {
        // Mark the proxy as closed so client cannot reuse this handle
        if (isClosed) {
            return;
        }
        isClosed = true;

        // Clean up open statements associated with this checkout
        closeStatements();

        // INSTEAD of calling delegate.close() (which kills the physical socket),
        // it recycles the entry back to HikariCP's internal pool:
        poolEntry.recycle();
    }

    // 4. Delegated methods: Straight pass-through to real physical connection
    @Override
    public void commit() throws SQLException {
        checkClosed();
        delegate.commit();
    }

    @Override
    public void rollback() throws SQLException {
        checkClosed();
        delegate.rollback();
    }
}

// Client Usage in Application Code
DataSource ds = new HikariDataSource(config);

// Hikari returns HikariProxyConnection (a subclass of ProxyConnection)
try (Connection conn = ds.getConnection()) {
    // conn is the Proxy, acting as java.sql.Connection
    try (PreparedStatement ps = conn.prepareStatement("SELECT * FROM users")) {
        ResultSet rs = ps.executeQuery();
        // ... process results
    }
} // AutoCloseable triggers conn.close() here

// Result: The physical database connection stays alive and is placed back in 
// Hikari's pool ready for the next request.

Static vs. Dynamic Proxies in Java

5. Composite Pattern

The Composite Pattern is a structural design pattern used to compose objects into tree structures that represent part-whole hierarchies. It enables client code to treat individual leaf objects and complex object compositions uniformly through a common interface.

The pattern relies on three roles:

• Component: An interface or abstract class declaring common operations for all elements in the tree.
• Leaf: A primitive building block with no children that implements the operation directly.
• Composite: A container holding children (leaves or other composites) that implements the operation by delegating it to its child elements.

The Bad Example: Without Composite

Consider a file system calculator where File and Directory are separate, unrelated classes. Without a unified interface, the client must manage separate lists, perform type checks, and manually handle recursive unpacking.

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

class File {
    private String name;
    private long sizeInBytes;

    public File(String name, long sizeInBytes) {
        this.name = name;
        this.sizeInBytes = sizeInBytes;
    }

    public long getSize() {
        return sizeInBytes;
    }
}

class Directory {
    private String name;
    // Flaw: Directory must maintain separate collections for every type
    private List<File> files = new ArrayList<>();
    private List<Directory> subDirectories = new ArrayList<>();

    public Directory(String name) {
        this.name = name;
    }

    public void addFile(File file) {
        files.add(file);
    }

    public void addDirectory(Directory dir) {
        subDirectories.add(dir);
    }

    public List<File> getFiles() {
        return files;
    }

    public List<Directory> getSubDirectories() {
        return subDirectories;
    }
}

Why This Breaks Down in Client Code:

public class Client {
    // The client is burdened with manual recursion and type-specific handling
    public static long calculateTotalSize(Directory root) {
        long total = 0;

        for (File file : root.getFiles()) {
            total += file.getSize();
        }

        for (Directory subDir : root.getSubDirectories()) {
            // Must manually recurse into directory types
            total += calculateTotalSize(subDir);
        }

        return total;
    }
}

• Violates Open/Closed Principle (OCP): If you add a Symlink, ZipArchive, or HardLink, you must add new lists to Directory and rewrite the client's calculation logic.
• No Uniformity: The client cannot pass a single File to calculateTotalSize()—it only accepts Directory.

The Good Example: With Composite Pattern

Introduce a shared FileSystemItem component interface. Both File (Leaf) and Directory (Composite) implement this interface.

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

// 1. Component
interface FileSystemItem {
    long getSize();
    void print(String indent);
}

// 2. Leaf
class File implements FileSystemItem {
    private String name;
    private long sizeInBytes;

    public File(String name, long sizeInBytes) {
        this.name = name;
        this.sizeInBytes = sizeInBytes;
    }

    @Override
    public long getSize() {
        return sizeInBytes;
    }

    @Override
    public void print(String indent) {
        System.out.println(indent + "- " + name + " (" + sizeInBytes + " bytes)");
    }
}

// 3. Composite
class Directory implements FileSystemItem {
    private String name;
    // Stores both Files and nested Directories under the same abstraction
    private List<FileSystemItem> children = new ArrayList<>();

    public Directory(String name) {
        this.name = name;
    }

    public void add(FileSystemItem item) {
        children.add(item);
    }

    public void remove(FileSystemItem item) {
        children.remove(item);
    }

    @Override
    public long getSize() {
        long total = 0;
        // Delegates work to each child, regardless of whether it is a File or Directory
        for (FileSystemItem item : children) {
            total += item.getSize();
        }
        return total;
    }

    @Override
    public void print(String indent) {
        System.out.println(indent + "+ [" + name + "]");
        for (FileSystemItem item : children) {
            item.print(indent + "  ");
        }
    }
}

Clean Client Usage:

public class Main {
    public static void main(String[] args) {
        // Build the tree
        Directory root = new Directory("workspace");
        root.add(new File("README.md", 1200));

        Directory src = new Directory("src");
        src.add(new File("App.java", 4500));
        src.add(new File("Utils.java", 2300));
        root.add(src);

        // Uniform invocation: client does not care whether 'target' is a leaf or composite
        printItemDetails(root);
        printItemDetails(new File("Standalone.txt", 800));
    }

    public static void printItemDetails(FileSystemItem item) {
        System.out.println("Total Size: " + item.getSize() + " bytes");
        item.print("");
    }
}

Real-World Example from GitHub: JUnit (junit-team/junit4)

One of the most famous real-world implementations is found in the classic architecture of JUnit (originally co-written by Erich Gamma, co-author of the Gang of Four design patterns book).

In junit-team/junit4, test execution is structured as an object tree using the Composite Pattern.

1. The Component: junit.framework.Test

package junit.framework;

public interface Test {
    int countTestCases();
    void run(TestResult result);
}

2. The Leaf: junit.framework.TestCase

A single unit test method implements Test:

package junit.framework;

public abstract class TestCase extends Assert implements Test {
    // ...
    @Override
    public void run(TestResult result) {
        result.run(this); // Executes this single test case
    }
}

3. The Composite: junit.framework.TestSuite

A suite contains a collection of Test objects, which can be individual test cases or other nested test suites:

package junit.framework;

import java.util.Vector;

public class TestSuite implements Test {
    // Holds children using the Component interface
    private Vector<Test> fTests = new Vector<Test>(10);

    public void addTest(Test test) {
        fTests.add(test);
    }

    @Override
    public int countTestCases() {
        int count = 0;
        for (Test each : fTests) {
            count += each.countTestCases(); // Recursive leaf counting
        }
        return count;
    }

    @Override
    public void run(TestResult result) {
        for (Test each : fTests) {
            if (result.shouldStop()) {
                break;
            }
            runTest(each, result); // Delegates to each child: each.run(result)
        }
    }

    public void runTest(Test test, TestResult result) {
        test.run(result);
    }
}

Why JUnit Uses It:

A test runner (TestRunner) only interacts with Test.run(result). Because TestSuite implements Test and can hold other TestSuite instances, you can group tests hierarchically (e.g., Package Suite $\rightarrow$ Class Suite $\rightarrow$ Individual Method Test Case) without the runner needing to know if it is running one isolated test or a suite of 20,000 tests.

6. Flyweight Pattern

The Flyweight Pattern is a structural Gang of Four (GoF) design pattern used to minimize memory usage by sharing common data across a large number of similar, fine-grained objects.

Instead of keeping duplicate data across thousands or millions of instances, the Flyweight pattern divides an object's state into two distinct parts:

• Intrinsic State (Shared & Immutable): Context-independent data that never changes between usages (e.g., character font metrics, 3D mesh geometry, or particle texture). This is stored directly inside the flyweight object.
• Extrinsic State (Unique & Contextual): State that varies depending on where and how the object is used (e.g., screen coordinates, velocity, or current color). This is stored or computed by the client and passed into flyweight methods as arguments.

Toy examples make Flyweight look pointless because instantiating a whole class hierarchy just to print "You drank a potion" is textbook over-engineering.

In real systems, the Flyweight pattern solves a very specific physical problem: memory exhaustion and garbage collection thrashing when an application must track millions of fine-grained entities that share heavy, repetitive metadata.

Here are three production-grade usages from major open-source Java repositories on GitHub:

1. Apache POI (apache/poi): Spreadsheet Cell Formatting

A standard enterprise spreadsheet can easily contain 1,000,000 cells.

If every individual cell object held its own styling attributes—font family, font size, bold/italic flags, 4 border styles, 4 border colors, cell fill pattern, background color, number format pattern, and alignment—each cell would consume several hundred bytes of metadata. Across a million cells, formatting alone would consume gigabytes of heap.

Apache POI solves this by decoupling the extrinsic state (the cell's position and data) from the intrinsic state (the formatting rules), using the underlying OpenXML/Excel styles table as a Flyweight pool.

The Architecture in apache/poi

• Flyweight Object (XSSFCellStyle): Encapsulates borders, fills, fonts, and data formats.
• Flyweight Factory / Cache (StylesTable): Stores unique style records indexed by ID.
• Context / Extrinsic Holder (XSSFCell): Stores only the row index, column index, raw value, and a 2-byte or 4-byte integer style index (cell.getStyleIndex()).

Simplified Excerpt from Apache POI Source

// GitHub: apache/poi/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFCell.java
public class XSSFCell implements Cell {
    private final CTCell _cell; // Underlying XML bean containing row, col, and style ID
    private final XSSFRow _row;

    @Override
    public CellStyle getCellStyle() {
        // The cell does NOT store font, borders, or colors directly.
        // It fetches the shared flyweight from the workbook's StylesTable.
        long styleId = _cell.isSetS() ? _cell.getS() : 0;
        return _row.getSheet().getWorkbook().getStylesSource().getStyleAt((int) styleId);
    }

    @Override
    public void setCellStyle(CellStyle style) {
        if (style == null) {
            _cell.unsetS();
            return;
        }
        XSSFCellStyle xstyle = (XSSFCellStyle) style;
        // Verify the style belongs to this workbook's shared table
        xstyle.verifyBelongsToStylesSource(_row.getSheet().getWorkbook().getStylesSource());
        // Only store the index to the shared flyweight in this cell
        _cell.setS(xstyle.getIndex());
    }
}

// GitHub: apache/poi/src/ooxml/java/org/apache/poi/xssf/model/StylesTable.java
public class StylesTable extends POIXMLDocumentPart {
    // The Flyweight Pool: shared list of distinct styles
    private final List<XSSFCellStyle> styleTable = new ArrayList<>();

    public XSSFCellStyle getStyleAt(int idx) {
        return styleTable.get(idx);
    }

    public int putCellStyle(XSSFCellStyle style) {
        int idx = styleTable.indexOf(style);
        if (idx != -1) {
            return idx; // Reuse existing instance
        }
        styleTable.add(style);
        return styleTable.size() - 1;
    }
}

By applying the pattern, 1,000,000 cells sharing 12 distinct visual layouts only allocate 12 CellStyle objects instead of 1,000,000 duplicate instances.

2. JetBrains IntelliJ IDEA (JetBrains/intellij-community): Syntax Trees & Token Types

IntelliJ indexes and keeps Abstract Syntax Trees (ASTs) for tens of thousands of files in memory. In a large project, there are tens of millions of syntax tokens (semicolons, braces, keywords like public, return, class, whitespace).

If every single token in the AST held references to its language, lexer state, debug strings, parser rule IDs, and indexing flags, the IDE would crash out-of-memory within minutes of opening a large repository.

The Architecture in intellij-community

• Flyweight Object (IElementType): Represents token metadata (is it a keyword? is it whitespace? which language does it belong to?).
• Extrinsic Holder (LeafElement / ASTNode): Stores only its position in the document (offset, length), parent/sibling pointers in the syntax tree, and a reference to the shared IElementType.

Simplified Excerpt from IntelliJ Community Source

// GitHub: JetBrains/intellij-community/platform/core-api/src/com/intellij/psi/tree/IElementType.java
public class IElementType {
    public static final short FIRST_TOKEN_INDEX = 1;
    private static final List<IElementType> ourRegistry = new CopyOnWriteArrayList<>();
    
    private final short myIndex;
    private final String myDebugName;
    private final Language myLanguage;

    // Factory registration ensures singletons for language tokens
    public IElementType(String debugName, Language language) {
        this.myDebugName = debugName;
        this.myLanguage = language;
        synchronized (IElementType.class) {
            ourRegistry.add(this);
            this.myIndex = (short) ourRegistry.size();
        }
    }

    public short getIndex() {
        return myIndex;
    }
}

// Concrete Flyweights defined as singletons for all Java codebases:
// GitHub: JetBrains/intellij-community/java/java-psi-api/src/com/intellij/psi/JavaTokenType.java
public interface JavaTokenType {
    IElementType CLASS_KEYWORD   = new IElementType("CLASS_KEYWORD", JavaLanguage.INSTANCE);
    IElementType PUBLIC_KEYWORD  = new IElementType("PUBLIC_KEYWORD", JavaLanguage.INSTANCE);
    IElementType SEMICOLON       = new IElementType("SEMICOLON", JavaLanguage.INSTANCE);
    IElementType LBRACE          = new IElementType("LBRACE", JavaLanguage.INSTANCE);
    IElementType RBRACE          = new IElementType("RBRACE", JavaLanguage.INSTANCE);
}

// Extrinsic State: Millions of AST nodes point to the exact same static IElementType instances
// GitHub: JetBrains/intellij-community/platform/core-impl/src/com/intellij/psi/impl/source/tree/LeafElement.java
public class LeafElement extends TreeElement {
    private final IElementType myElementType; // Shared Flyweight reference (8 bytes)
    private int myStartOffset;                // Extrinsic: position in file
    private int myLength;                     // Extrinsic: token length

    public LeafElement(IElementType type, int startOffset, int length) {
        this.myElementType = type;
        this.myStartOffset = startOffset;
        this.myLength = length;
    }

    public IElementType getElementType() {
        return myElementType;
    }
}

When parsing 500,000 occurrences of the ; character across your codebase, the tree creates 500,000 lightweight offset containers (LeafElement), but all 500,000 point to the exact same JavaTokenType.SEMICOLON object.

3. Netty (netty/netty): Zero-Allocation Pipeline Keys

Netty processes millions of network packets per second. In Netty's channel pipeline, components frequently store and look up state on a ChannelHandlerContext using typed keys (e.g., retrieving the authenticated user session, client ID, or SSL session).

If an application used Map<String, Object> or dynamically instantiated keys on hot network paths:

1. Strings would require expensive hashCode() and equals() lookups on every packet.
2. Creating keys would produce garbage allocations that trigger GC pauses.

Netty uses a Flyweight implementation via ConstantPool and AttributeKey.

Simplified Excerpt from Netty Source

// GitHub: netty/netty/common/src/main/java/io/netty/util/ConstantPool.java
public abstract class ConstantPool<T extends Constant<T>> {

    // Flyweight cache ensuring unique constants are shared across threads
    private final ConcurrentMap<String, T> constants = new ConcurrentHashMap<>();
    private final AtomicInteger nextId = new AtomicInteger(1);

    public T valueOf(String name) {
        checkNotNull(name, "name");
        return getOrCreate(name);
    }

    private T getOrCreate(String name) {
        T constant = constants.get(name);
        if (constant == null) {
            T tempConstant = newConstant(nextId.getAndIncrement(), name);
            constant = constants.putIfAbsent(name, tempConstant);
            if (constant == null) {
                return tempConstant;
            }
        }
        return constant;
    }

    protected abstract T newConstant(int id, String name);
}

// GitHub: netty/netty/common/src/main/java/io/netty/util/AttributeKey.java
public final class AttributeKey<T> extends AbstractConstant<AttributeKey<T>> {

    private static final ConstantPool<AttributeKey<Object>> pool = 
        new ConstantPool<AttributeKey<Object>>() {
            @Override
            protected AttributeKey<Object> newConstant(int id, String name) {
                return new AttributeKey<>(id, name);
            }
        };

    // Flyweight factory method
    @SuppressWarnings("unchecked")
    public static <T> AttributeKey<T> valueOf(String name) {
        return (AttributeKey<T>) pool.valueOf(name);
    }

    private AttributeKey(int id, String name) {
        super(id, name);
    }
}

Why Netty Does This:

Because AttributeKey.valueOf("CLIENT_ID") is guaranteed to return the exact same canonical reference everywhere in the JVM, Netty's internal attribute storage can check key equality using pointer comparison (==) rather than string comparison:

// High-throughput channel read loop:
AttributeKey<Session> KEY = AttributeKey.valueOf("SESSION");

// Fast pointer identity check, zero allocations, no string hashing:
if (this.key == KEY) {
    return this.value;
}

Real-World Litmus Test

You should only reach for the Flyweight pattern when your system satisfies all three conditions:

7. Bridge Pattern

The Bridge Pattern decouples an abstraction from its implementation so both can vary independently.

When you rely solely on inheritance to extend a class across two orthogonal dimensions (e.g., What something is vs. How it is drawn/executed), you get a combinatorial explosion of subclasses ($M \times N$). The Bridge pattern replaces inheritance with composition by extracting one dimension into a separate interface and referencing it inside the abstraction.

The Problem: Combinatorial Explosion (Bad Example)

Suppose you have geometric shapes (Circle, Square) and rendering formats (Vector, Raster). Implementing both dimensions via class inheritance forces you to create a distinct subclass for every possible combination:

               Shape
             /       \
       Circle         Square
       /    \         /    \
VectorRaster  VectorRaster
CircleCircle  SquareSquare

# BAD: Using inheritance across two independent dimensions

class Shape:
    def draw(self):
        raise NotImplementedError

class VectorCircle(Shape):
    def draw(self):
        print("Drawing Circle as Vector paths")

class RasterCircle(Shape):
    def draw(self):
        print("Drawing Circle as Raster pixels")

class VectorSquare(Shape):
    def draw(self):
        print("Drawing Square as Vector paths")

class RasterSquare(Shape):
    def draw(self):
        print("Drawing Square as Raster pixels")

Why This Breaks Down:

• Subclass Explosion: Adding a third shape (Triangle) requires 2 new classes. Adding a third renderer (SVG) requires 3 new classes. If you have $N$ shapes and $M$ renderers, you must maintain $N \times M$ classes.
• Code Duplication: Raster drawing logic is duplicated across RasterCircle and RasterSquare.
• Tight Coupling: The shape domain logic is glued directly to rendering technology.

The Solution: The Bridge Pattern (Good Example)

Separate the system into two distinct hierarchies:

1. Abstraction: High-level control logic (Shape).
2. Implementor: Low-level platform/execution details (Renderer).

The abstraction maintains a reference (the Bridge) to an implementor instance:

Abstraction Hierarchy            Implementor Hierarchy
      Shape  ------ [bridge] ---->  Renderer
     /     \                        /      \
 Circle   Square            VectorRenderer RasterRenderer

from abc import ABC, abstractmethod

# -------------------------------------------------------------------
# 1. IMPLEMENTOR HIERARCHY (How to draw)
# -------------------------------------------------------------------
class Renderer(ABC):
    @abstractmethod
    def render_circle(self, radius: float):
        pass

    @abstractmethod
    def render_square(self, side: float):
        pass

class VectorRenderer(Renderer):
    def render_circle(self, radius: float):
        print(f"Drawing vector circle with radius {radius}")

    def render_square(self, side: float):
        print(f"Drawing vector square with side {side}")

class RasterRenderer(Renderer):
    def render_circle(self, radius: float):
        print(f"Drawing pixels for circle of radius {radius}")

    def render_square(self, side: float):
        print(f"Drawing pixels for square of side {side}")

# -------------------------------------------------------------------
# 2. ABSTRACTION HIERARCHY (What to draw)
# -------------------------------------------------------------------
class Shape(ABC):
    def __init__(self, renderer: Renderer):
        # The "Bridge" connection
        self._renderer = renderer

    @abstractmethod
    def draw(self):
        pass

class Circle(Shape):
    def __init__(self, renderer: Renderer, radius: float):
        super().__init__(renderer)
        self.radius = radius

    def draw(self):
        # Delegates drawing to the implementor
        self._renderer.render_circle(self.radius)

class Square(Shape):
    def __init__(self, renderer: Renderer, side: float):
        super().__init__(renderer)
        self.side = side

    def draw(self):
        self._renderer.render_square(self.side)

# -------------------------------------------------------------------
# Client Code
# -------------------------------------------------------------------
raster = RasterRenderer()
vector = VectorRenderer()

circle = Circle(vector, radius=5.0)
square = Square(raster, side=10.0)

circle.draw()  # Output: Drawing vector circle with radius 5.0
square.draw()  # Output: Drawing pixels for square of side 10.0

# Dynamic switching at runtime:
circle._renderer = raster
circle.draw()  # Output: Drawing pixels for circle of radius 5.0

Core Mechanics & Benefits

Use the Bridge pattern when a class must evolve along two or more independent axes (e.g., GUI platforms vs. application windows, database drivers vs. query builders, device drivers vs. remote controls).

Critical Questions & Architectural Failure Modes

1. Why Not Inherit Multiple Interfaces?

Inheriting multiple interfaces (e.g., class VectorCircle implements Shape, VectorDrawable) solves type classification, but it does not solve the structural problem of code reuse or combinatorial growth:

• Does not prevent class explosion: An interface defines what methods exist, not reusable state or execution logic. If you have 5 shapes and 4 renderers, you still have to write and maintain $5 \times 4 = 20$ concrete classes.
• Compile-time lock-in: Inheritance binds implementation at compile time. Once an object is instantiated as a VectorCircle, it cannot swap its rendering pipeline to RasterRenderer at runtime. With Bridge, shape.renderer = rasterRenderer is a trivial reference swap.
• Code duplication: In languages without default interface methods, VectorCircle and VectorSquare duplicate the exact same vector API calls. Even in languages with default interface methods (Java, C#), interfaces cannot hold non-static state (like device contexts, canvas handles, or transform matrices).
• Violation of SRP: A class implementing both Shape and VectorDrawable is forced to change for two unrelated reasons: changes in shape geometry algorithms or changes in vector rendering protocols.

2. When Can You NOT Use the Bridge Pattern?

The textbook Shape/Renderer example relies on a clean, orthogonal split: shapes provide pure geometric data, and renderers consume it. In production, abstractions frequently fail to split cleanly:

1. Lowest Common Denominator Trap (Asymmetric Capabilities): A clean bridge assumes all implementors can satisfy the same interface. When implementations have vastly different capabilities, the implementor interface either bloats or turns into a neutered baseline.
   • Example: An implementor hierarchy for StorageBackend with implementations LocalDisk and S3CloudStorage. If S3 supports multipart uploads, presigned URLs, and eventual consistency tags, but LocalDisk only knows POSIX byte streams, how do you design StorageBridge? Adding cloud-specific methods makes LocalDisk throw NotSupportedException; omitting them cripples the cloud backend.
2. Leaky Abstractions and Bi-directional Data Dependencies: The Bridge requires a one-way dependency: Abstraction -> Implementor. If the abstraction requires low-level implementation details to compute high-level logic, the boundary collapses.
   • Example: In a text layout engine, Paragraph (abstraction) cannot compute line wraps and hyphenation without knowing the exact sub-pixel font metrics and kerning tables from the platform's FontEngine (implementor). The bridge turns into a chatty, cyclic dependency.
3. Deep Domain Variance Across Concrete Types: If rendering a Path on a GPU requires tessellation shaders and vertex buffers, but rendering Text on a GPU requires signed distance field textures, an implementor interface cannot expose a clean, generic contract like draw(Geometry g) without leaking low-level rendering types back into the domain layer.

What to Use When Bridge Fails

How to Choose: Abstraction vs. Implementation

The choice comes down to who orchestrates versus who executes primitives:

The Three Diagnostic Tests:

1. The "Driver" Test: Ask: Which side is the domain concept, and which side is the platform/driver?
   • In a Smart Home system: RemoteControl is the abstraction; DeviceDriver (for Sony, Samsung, LG) is the implementor.
   • In a notification system: Alert (UrgentAlert, DigestAlert) is the abstraction; NotificationGateway (SMS, Email, Push) is the implementor.
2. The Dependency Direction Test: The Abstraction holds a reference to the Implementor—never the reverse. The Abstraction delegates work downward to primitive methods defined by the Implementor.
3. Granularity Mismatch: The Abstraction defines high-level operations that make sense to the end user or business logic (remote.mute()). The Implementor provides the narrow, atomic primitives required to make it happen (audio_chip.set_gain(0)).

What About Multiple Dimensions: Shape, Color, BorderType?

The Bridge pattern strictly decouples two orthogonal hierarchies (1 Abstraction $\times$ 1 Implementor).

Attempting to chain Bridges for three or more dimensions (Shape -> ColorBridge -> BorderBridge) leads to tangled delegation chains and architectural confusion. More importantly, Color and BorderType are attributes/styles, not execution platforms.

[!NOTE] The "Toy Analogy Trap" (Why Refactoring Guru's Shape + Color Example Is Flawed) In tutorials like Refactoring Guru, you often see Color modeled as an implementor interface with Red and Blue subclasses. In production, this is an anti-pattern:

• Data vs. Polymorphism: A color does not calculate, route, or execute anything. It is passive data (a tuple of integers or a hex string). Creating a class Red(Color) that returns "#FF0000" is artificial over-engineering.
• The Abstraction doesn't call meaningful primitives: What does Shape ask Color to do? In the fake example, it just fetches a string that could have been an instance variable on Shape.

When modeling shapes with color, borders, textures, and renderers, use one of these three battle-tested approaches:

Approach 1: Value Objects / Components (The Standard Solution)

Model styling definitions as value objects or properties. The Bridge is preserved purely between Shape (abstraction) and Renderer (implementor), while styling data is passed through:

from dataclasses import dataclass

@dataclass(frozen=True)
class Color:
    r: int
    g: int
    b: int

@dataclass(frozen=True)
class Border:
    thickness: float
    style: str  # "dashed", "solid"

# Bridge remains: Shape (Abstraction) -> Renderer (Implementor)
class Shape:
    def __init__(self, renderer, color: Color, border: Border):
        self.renderer = renderer
        self.color = color
        self.border = border

class Circle(Shape):
    def __init__(self, renderer, radius: float, color: Color, border: Border):
        super().__init__(renderer, color, border)
        self.radius = radius

    def draw(self):
        # Passes geometry and styling data to the rendering engine
        self.renderer.render_circle(self.radius, self.color, self.border)

Approach 2: Grouping into a "Style / Graphics Context"

When styling dimensions grow (Color, BorderType, FillType, Shadow, Opacity), group them into a single Style or Paint object (as seen in frameworks like Skia, Flutter, or HTML5 Canvas). The Shape supplies geometry, Style supplies appearance, and Renderer executes drawing:

@dataclass
class Style:
    fill_color: Color
    border_color: Color
    border_thickness: float
    border_style: str
    opacity: float = 1.0

class Circle(Shape):
    def __init__(self, renderer, radius: float, style: Style):
        self.renderer = renderer
        self.radius = radius
        self.style = style

    def draw(self):
        self.renderer.render_circle(self.radius, self.style)

Approach 3: Decorator Pattern (For Layered Visual Enhancements)

If borders or visual modifiers need to be added or wrapped dynamically at runtime around existing shapes without altering the shape's class:

class ShapeDecorator(Shape):
    def __init__(self, decorated_shape: Shape):
        self._decorated_shape = decorated_shape

    def draw(self):
        self._decorated_shape.draw()

class BorderDecorator(ShapeDecorator):
    def __init__(self, shape: Shape, border: Border):
        super().__init__(shape)
        self.border = border

    def draw(self):
        super().draw()
        self._apply_border()

    def _apply_border(self):
        print(f"Applying border {self.border}")

Pattern Selection Summary

• Two orthogonal class hierarchies (e.g., Domain Logic vs. Platform Driver): Use Bridge.
• Many swappable visual/styling attributes: Use Value Objects / Style Aggregates.
• Dynamic, onion-skin wrapping of behavior or appearance: Use Decorator.
• Complex multi-part configuration: Use Builder to construct the shape with all its styling components.

"Does Anyone Actually Use the Word 'Bridge' in Real Code?"

Under the hood, almost every GoF structural pattern compiles to the exact same memory layout: Class A ----has-a----> Interface B

If you only look at the AST or class layout, these four patterns are virtually indistinguishable:

In normal day-to-day codebases, developers rarely say "Bridge"—they say "driver," "backend," "provider," or "engine."

When is a Bridge Over-Engineering? (Simpler Alternatives)

A full-blown GoF Bridge is one of the most frequently over-engineered patterns. If you don't have two independently varying axes of subclassing, introducing a Bridge is pure accidental complexity:

• Case A: You only have one dimension that varies: If you have 10 shapes, but you're only ever targeting one graphics API, an implementor hierarchy is useless boilerplate.
• Case B: First-Class Functions / Closures: In modern languages (Go, Python, Rust, modern C++), you don't need an entire Renderer interface:

  class Circle:
      def __init__(self, radius: float, draw_fn):
          self.radius = radius
          self.draw_fn = draw_fn
  
      def draw(self):
          self.draw_fn(self.radius)
  

• Case C: Compile-Time / Static Polymorphism: If you know your platform target at compile time (compiling for Linux vs. Windows, or Metal vs. Vulkan), C++ templates, Go build tags, or Rust traits resolve the separation with zero runtime cost:

  template <typename Renderer>
  class Circle {
      Renderer renderer;
      float radius;
  public:
      Circle(Renderer r, float rad) : renderer(r), radius(rad) {}
      void draw() { renderer.render_circle(radius); }
  };
  

Real-World Open-Source Debates Referencing the GoF Bridge by Name

The term carries precise weight in engine and framework engineering where maintainers debate multi-platform architecture:

1. The .NET MAUI / Xamarin Architecture Debates (dotnet/maui): Xamarin.Forms was architected literally around the textbook GoF Bridge:
   • Abstraction: Cross-platform controls (Button, Entry, ListView)
   • Implementor: Platform-specific native renderers (ButtonRenderer on Android, iOS, UWP) In the dotnet/maui RFCs, Microsoft architects dismantled the textbook Bridge in favor of lightweight "Mapper" dictionaries because the old Bridge caused circular dependencies, severe Android memory leaks, and forced developers to subclass the entire implementor side just to customize one native property.
2. OpenJDK Bug System & Mailing Lists: The AWT "Peer Bridge": Java's AWT (java.awt.Component as Abstraction, java.awt.peer.ComponentPeer as Implementor) is the historical poster child for the Bridge pattern. In Project Wakefield (pure Wayland support) and Solaris/Motif backend deprecations, engineers explicitly debate modifications to the "Peer Bridge" architecture.
3. Chromium / Blink: Decoupling Platform Windows from Widget Trees: Chrome separates views::Widget (cross-platform UI abstraction) from ui::PlatformWindow (native Wayland, X11, Win32, Cocoa backend). Design docs transitioning Chrome Linux from X11 to Ozone explicitly evaluate Ozone as a Bridge/Implementor hierarchy to prevent platform-specific #ifdef directives from creeping into widget layout logic.
4. OpenCV (opencv/opencv): Decoupling Video Capture Hardware: In PRs refactoring cv::VideoCapture (Abstraction) and cv::IVideoCapture (Implementor / VideoIO backend plugins like DirectShow, Media Foundation, V4L2, AVFoundation), maintainers specifically used Bridge to allow new hardware grabbers to compile as dynamic .so / .dll modules without recompiling client code.

Why Bridging UI Controls (Buttons) Failed vs. Where Bridge Actually Wins

Separating Button (abstraction) from AndroidButton (implementation) sounds ideal in theory, but in real-world framework engineering, it is often an anti-pattern:

1. The UX and Conceptual Model Are Not Actually Orthogonal:
   • Android (Material Design): Elevation surfaces, tonal palettes, ripple state machines, FAB morphing.
   • iOS (Human Interface Guidelines): Dynamic type resizing, pull-down menu attachments, glass/vibrancy backgrounds, role-based tints.
   • Forcing both into a single bridged Button causes either the Lowest-Common-Denominator Trap (stripping native feel down to text and background color) or the Kitchen Sink Leaky Abstraction (a single bloated class with Elevation, RippleColor, and IosConfig).
2. Loss of Compile-Time Type Safety: Accessing iOS-specific features forces developers into runtime downcasting (button.renderer as? IOSButtonPeer), nullifying the abstraction.
3. Asymmetric Event and Gesture Loops: Touch dispatch is fundamentally bidirectional (Android MotionEvent interception vs iOS UIResponder chains), introducing latency and accessibility tool failures (TalkBack vs VoiceOver).

How Modern Frameworks Solved This

Where Bridge Proves Vastly Superior: Two Production Case Studies

The Bridge pattern succeeds when the two hierarchies meet three criteria that UI buttons fail:

1. The Implementor is a dumb, low-level primitive engine (not an opinionated, bidirectional UI system).
2. The Abstraction contains heavy, reusable domain logic that shouldn't be duplicated per platform.
3. The data flow is strictly unidirectional (the Abstraction calls down to the Implementor; the Implementor doesn't drive the Abstraction).

Case 1: Logging & Telemetry Engines (Policy vs. Ingestion Sink)

• Dimension A (Abstraction / Policy): StandardLogger, AsyncBatchLogger (buffers entries in a concurrent lock-free ring buffer, worker thread flush), AuditingLogger (HMAC cryptographic hashing), SamplingLogger (rate limits).
• Dimension B (Implementor / Physical Sink): FileSink, SyslogSink, KafkaSink, CloudWatchSink.

The Subclassing Disaster: Subclassing requires $N \times M = 16$ classes (AsyncBatchKafkaLogger, AsyncBatchFileLogger, etc.). Complex, error-prone concurrent ring-buffer threading logic is copy-pasted across every platform subclass!

The Bridge Solution:

from abc import ABC, abstractmethod

# --- IMPLEMENTOR (Dumb Sink Primitive) ---
class LogSink(ABC):
    @abstractmethod
    def emit_batch(self, entries: list[str]):
        """Pure primitive: just writes raw strings out."""
        pass

class FileSink(LogSink):
    def __init__(self, filepath: str):
        self._file = open(filepath, "a")

    def emit_batch(self, entries: list[str]):
        self._file.writelines(f"{e}\n" for e in entries)

class KafkaSink(LogSink):
    def __init__(self, topic: str):
        self._topic = topic

    def emit_batch(self, entries: list[str]):
        # Send payload to Kafka broker
        pass

# --- ABSTRACTION (Complex Policy & Coordination) ---
class Logger(ABC):
    def __init__(self, sink: LogSink):
        self._sink = sink  # The Bridge

    @abstractmethod
    def log(self, message: str):
        pass

class AsyncBatchLogger(Logger):
    def __init__(self, sink: LogSink, batch_size: int = 1000):
        super().__init__(sink)
        self._queue = []
        self._batch_size = batch_size

    def log(self, message: str):
        self._queue.append(message)
        if len(self._queue) >= self._batch_size:
            self.flush()

    def flush(self):
        # Complex flush, retry, and worker logic written ONCE
        self._sink.emit_batch(self._queue)
        self._queue.clear()

• AsyncBatchLogger owns all concurrency and ring buffers written once.
• 4 policies + 4 sinks = 8 classes instead of 16.

Case 2: Database Query Builders (AST Semantics vs. SQL Dialects)

• Dimension A (Abstraction): SelectQuery, UpsertQuery, WindowAggregateQuery (AST validation, join checking, conflict targets).
• Dimension B (Implementor): PostgresDialect, MySQLDialect, SqliteDialect.

The Subclassing Disaster: An UpsertQuery has complex semantic validation: verifying target unique constraints, column deduplication, and update clause ordering. Subclassing per dialect forces you to duplicate validation across PostgresUpsertQuery, MySQLUpsertQuery (ON DUPLICATE KEY UPDATE), and SqliteUpsertQuery (ON CONFLICT DO UPDATE).

The Bridge Solution:

# --- IMPLEMENTOR (Dialect Compiler) ---
class SQLDialect(ABC):
    @abstractmethod
    def compile_upsert(self, table: str, keys: list[str], values: dict, conflicts: list[str]) -> str:
        pass

class PostgresDialect(SQLDialect):
    def compile_upsert(self, table, keys, values, conflicts):
        col_str = ", ".join(keys)
        conflict_str = ", ".join(conflicts)
        update_str = ", ".join(f"{k} = EXCLUDED.{k}" for k in values)
        return f"INSERT INTO {table} ({col_str}) VALUES (...) ON CONFLICT ({conflict_str}) DO UPDATE SET {update_str};"

class MySQLDialect(SQLDialect):
    def compile_upsert(self, table, keys, values, conflicts):
        col_str = ", ".join(keys)
        update_str = ", ".join(f"{k} = VALUES({k})" for k in values)
        return f"INSERT INTO {table} ({col_str}) VALUES (...) ON DUPLICATE KEY UPDATE {update_str};"

# --- ABSTRACTION (AST Construction & Validation) ---
class Query(ABC):
    def __init__(self, dialect: SQLDialect):
        self._dialect = dialect  # The Bridge

    @abstractmethod
    def to_sql(self) -> str:
        pass

class UpsertQuery(Query):
    def __init__(self, dialect: SQLDialect, table: str):
        super().__init__(dialect)
        self.table = table
        self.conflict_cols = []
        self.updates = {}

    def on_conflict(self, *columns):
        # Heavy semantic validation shared across ALL engines:
        if not columns:
            raise ValueError("Conflict target requires at least one column")
        self.conflict_cols.extend(columns)
        return self

    def to_sql(self) -> str:
        # Validate AST before delegating compilation
        if not self.conflict_cols:
            raise IllegalStateException("Cannot compile upsert without conflict target")
        return self._dialect.compile_upsert(self.table, self.updates.keys(), self.updates, self.conflict_cols)

• AST building and sanitization exist in exactly one place.
• If MySQL changes its grammar in version 8.0, only MySQLDialect changes; all query abstraction classes remain untouched.

Summary Comparison: Why Bridge Won Here vs. Failed for Buttons

Production Real-World Examples from GitHub

1. matplotlib/matplotlib: Graphics Rendering Engine

A classic real-world implementation of the Bridge pattern on GitHub is the graphics rendering engine in Python's matplotlib/matplotlib (lib/matplotlib/backend_bases.py and lib/matplotlib/artist.py).

Matplotlib separates what to draw (Artist hierarchy: Line2D, Text, Patch, Axes) from where and how to render it (RendererBase hierarchy: RendererAgg, RendererPdf, RendererSVG, RendererCairo).

# The Implementor Interface (lib/matplotlib/backend_bases.py)
class RendererBase:
    def draw_path(self, gc, path, transform, rgbFace=None):
        raise NotImplementedError
    def draw_text(self, gc, x, y, s, prop, angle, ismath=False, mtext=None):
        raise NotImplementedError

# The Abstraction (lib/matplotlib/artist.py)
class Artist:
    def draw(self, renderer):
        raise NotImplementedError

# Refined Abstraction crossing the Bridge
class Line2D(Artist):
    def draw(self, renderer):
        if not self.get_visible():
            return
        gc = renderer.new_gc()
        gc.set_foreground(self._color)
        path = self.get_path()
        transform = self.get_transform()
        renderer.draw_path(gc, path, transform)
        gc.restore()

2. facebook/react: react-reconciler

In facebook/react (packages/react-reconciler), the reconciler decouples the core component lifecycle from host platform rendering:

• Abstraction: Virtual DOM diffing engine, Fiber tree reconciliation, hooks management, and scheduling priorities.
• Implementor Contract (HostConfig): Environment operations like createInstance(), appendInitialChild(), commitUpdate(), and removeChild().
• Concrete Implementors: react-dom (browser DOM), react-native (iOS/Android native views), ink (terminal ANSI), and @react-three/fiber (Three.js WebGL).

Series Navigation

• ⬅️ Previous: Design Patterns: Creational
• 🏠 Overview: Design Patterns: An Architectural Overview
• ➡️ Next: Design Patterns: Behavioral