A Stand-In That Controls Access
The Proxy pattern introduces a class that implements the same interface as a real subject object but sits in front of it, controlling how and when the real object is created, accessed, or invoked. Unlike Decorator, which adds new behavior to an object the client actively wants to use as-is, Proxy's defining intent is controlling access: deciding whether a call reaches the real object at all, deferring its creation, checking permissions before forwarding, or intercepting calls to add caching or logging without the client knowing the real object was ever bypassed or delayed. Because the proxy and real subject share an interface, client code written against the interface works identically whether it holds a proxy or the real object.
Cricket analogy: A team's media manager acts as a proxy between journalists and a star player like MS Dhoni, deciding which questions actually reach him and when, while journalists interact with the same 'press access' interface regardless of whether the manager or Dhoni himself is answering.
The Main Proxy Variants
Virtual proxies defer creation of an expensive real object until it's actually needed, such as not loading a large image from disk until it's actually scrolled into view. Protection proxies check the caller's permissions before forwarding a request, rejecting unauthorized calls without the real object ever being touched. Remote proxies represent an object that lives in a different address space or on a different machine, hiding network communication details behind a local-looking interface, as with gRPC or RMI stubs. Caching proxies store the results of expensive calls and return cached results for repeated identical requests instead of re-invoking the real subject. All four variants share the identical structural shape: same interface as the real subject, a held reference to it, and added logic wrapped around the delegated call.
Cricket analogy: A stadium doesn't print the giant screen replay until a boundary is actually hit (virtual proxy, deferred work), a ground pass checks accreditation before letting someone onto the pitch (protection proxy), and a satellite feed relays live footage from an overseas venue as if it were local (remote proxy).
A Worked Example
interface Image {
display(): void;
}
class RealImage implements Image {
constructor(private filename: string) {
this.loadFromDisk(); // expensive operation
}
private loadFromDisk() {
console.log(`Loading ${this.filename} from disk (slow)`);
}
display() {
console.log(`Displaying ${this.filename}`);
}
}
// Virtual proxy: defers creating RealImage until display() is actually called
class ImageProxy implements Image {
private realImage: RealImage | null = null;
constructor(private filename: string) {}
display() {
if (this.realImage === null) {
this.realImage = new RealImage(this.filename); // lazy load, only once
}
this.realImage.display();
}
}
const gallery: Image[] = [
new ImageProxy('vacation1.jpg'),
new ImageProxy('vacation2.jpg'),
];
// Disk loading only happens for images the user actually scrolls to and views
gallery[0].display();Proxy and Decorator share the identical UML structure (a wrapper implementing the same interface as the wrapped object), which is why they're often confused. The difference is intent: Decorator's purpose is to add or enhance behavior the client wants applied to an object it's actively using; Proxy's purpose is to control whether, when, and how the client's calls reach the real object at all, sometimes without the client ever knowing a substitution or interception occurred.
A remote proxy that makes a method call look exactly like a local, in-memory call can hide real network latency, partial failure, and serialization costs from callers who reasonably assume the call is cheap and synchronous. This is sometimes called violating the 'first law of distributed computing' (don't pretend the network isn't there); document remote proxies clearly so callers understand the hidden cost.
Choosing Proxy Over Alternatives
Reach for Proxy when you need to intervene in access to an object without changing the object's own code and without the client needing to know an intervention is happening at all, such as adding authorization checks around a legacy service class you cannot modify. If the client should be aware that extra behavior is being layered on and actively opts into it, Decorator communicates that intent more clearly. If what you actually need is a completely different, simplified interface rather than gatekeeping the existing one, Facade is the better fit. Choosing between these three structurally similar patterns comes down to answering one question: are you translating an interface, simplifying a subsystem, adding wanted behavior, or gating and deferring access?
Cricket analogy: A board uses a 'central contract' gatekeeping layer (proxy-like) to control which players can be selected for international duty without changing the players themselves, distinct from a coach who openly adds a new batting technique a player wants (decorator-like).
- Proxy provides a surrogate object implementing the same interface as a real subject, controlling access to it.
- It differs from Decorator in intent: controlling access versus adding wanted behavior to an object.
- Virtual proxies defer expensive object creation until it's actually needed.
- Protection proxies check permissions before forwarding a call to the real subject.
- Remote proxies hide network communication behind a local-looking interface.
- Caching proxies return stored results instead of re-invoking the real subject for repeated calls.
- Proxies that make remote calls look local risk hiding real latency and failure modes from callers.
Practice what you learned
1. What is the defining intent of the Proxy pattern?
2. In the ImageProxy example, when does the expensive loadFromDisk() operation actually happen?
3. Which proxy variant checks a caller's permissions before forwarding a request to the real subject?
4. How does Proxy differ from Decorator despite sharing the same structural shape?
5. What risk is specifically associated with remote proxies?
Was this page helpful?
You May Also Like
Decorator Pattern
The Decorator pattern attaches additional responsibilities to an object dynamically by wrapping it in one or more decorator objects that share its interface.
Adapter Pattern
The Adapter pattern converts the interface of a class into another interface clients expect, letting incompatible interfaces work together without modifying existing code.
Facade Pattern
The Facade pattern provides a single, simplified interface to a larger, more complex body of subsystem code, making it easier to use without hiding advanced access.
Composite Pattern
The Composite pattern composes objects into tree structures to represent part-whole hierarchies, letting clients treat individual objects and compositions of objects uniformly.
Related Reading
Related Study Notes in Software Engineering
Browse all study notesMicroservices Study Notes
Software Architecture · 30 topics
Software EngineeringTesting & TDD Study Notes
Software Testing · 30 topics
Software EngineeringSoftware Engineering Study Notes
Python · 75 topics
Software EngineeringGit & Version Control Study Notes
Bash · 40 topics
Software EngineeringSystem Design Study Notes
Architecture · 46 topics