Proxy Pattern

Description

Proxy is the structural pattern for standing in front of an object and controlling access to it: the proxy has the same interface, so callers can't tell the difference, but it decides when the real object is created, whether a call is allowed, whether the call is needed at all, or where it really runs. Lazy loading in ORMs, caching clients, security checks and remote stubs are all proxies. This skill covers the kinds of proxy, how they work, and where they surprise people.

A photo gallery shows 500 thumbnails, but each HighResImage loads a 20 MB file in its constructor. Creating the list takes forever, even though the user will open maybe three photos.

A second, related problem: you want every call to a document store to be permission-checked and logged. Putting those checks inside every method of the store mixes security code with storage code - and it's easy to forget one.

We'll go from simple to more technical:

1. The pattern: same interface, controlled access.
2. The kinds of proxy - virtual, protection, caching, remote, logging.
3. Where you'll see proxies: ORMs, Spring, RPC stubs, CDNs.
4. The surprises: self-invocation, lazy loading after the session closes, stale caches and chatty remote calls.

The pattern

A Proxy implements the same interface as the real object and stands in for it, controlling access: when the real object is created, whether a call is allowed, or whether it's needed at all.

interface Image {
    void display();
}

class HighResImage implements Image {
    HighResImage(String path) { /* expensive: loads 20 MB from disk */ }
    public void display() { /* draw it */ }
}

class LazyImageProxy implements Image {
    private final String path;
    private HighResImage real;          // not loaded yet

    LazyImageProxy(String path) { this.path = path; }   // cheap

    public void display() {
        if (real == null) real = new HighResImage(path);  // load on first real use
        real.display();
    }
}

from abc import ABC, abstractmethod


class Image(ABC):
    @abstractmethod
    def display(self) -> None: ...


class HighResImage(Image):
    def __init__(self, path: str):
        ...  # expensive: loads 20 MB from disk

    def display(self) -> None:
        ...  # draw it


class LazyImageProxy(Image):
    def __init__(self, path: str):                 # cheap
        self._path = path
        self._real: HighResImage | None = None     # not loaded yet

    def display(self) -> None:
        if self._real is None:
            self._real = HighResImage(self._path)  # load on first real use
        self._real.display()

The gallery holds 500 cheap proxies; only the photos the user actually opens are ever loaded.

How it works, step by step

1. Proxy and real object implement the same interface, so clients can't tell them apart.
2. The proxy holds (or knows how to get) the real object.
3. Before forwarding a call it applies its control: load lazily, check permissions, return a cached value, or send the call over the network.
4. Common kinds: virtual (lazy loading), protection (access checks), caching, remote (stand-in for an object on another machine) and logging proxies.

Where you'll see it

• Hibernate/JPA lazy associations: order.getCustomer() returns a proxy that loads the customer on first use.
• Spring wraps your beans in proxies to add @Transactional, @Cacheable and security behavior.
• java.lang.reflect.Proxy creates proxies at runtime; gRPC and RMI client stubs are remote proxies.
• In Python, SQLAlchemy's lazy relationships load on first access, functools.cached_property computes an attribute on first use, and a class with __getattr__ can forward every call to a real object it creates - or connects to - only when needed.
• In infrastructure, reverse proxies and CDNs cache and protect servers the same way.

Choosing among the structural patterns

Common mistakes

Check yourself

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

1. Name four kinds of proxy and what each one controls.

2. A Spring bean calls its own @Transactional method through this. Does a transaction start?

3. Proxy and Decorator both share the interface and wrap an object. What is the difference?

Key takeaways

• A proxy has the same interface as the real object and controls access to it.
• Kinds: virtual (lazy), protection (security), caching, remote and logging.
• Calls that don't go through the proxy (self-invocation) skip its behavior.
• Caching proxies need an invalidation strategy.
• Decorator adds behavior; Proxy controls access.