Proxy

Real-world analogy

A debit card acts as a proxy for the funds in your physical bank checking account. You present the card at a merchant terminal rather than transporting stacks of physical cash. The card processor verifies your identity, checks your balance (protection proxy), records the transaction history (logging proxy), and communicates across the payment network with the bank's central ledger (remote proxy).

The problem

You are building an analytics dashboard that displays high-resolution satellite imagery. Loading a single raw raster image (GeoRasterImage) takes 3 to 5 seconds, loads 150 MB into RAM, and opens an expensive network socket to a cloud bucket.

When the user opens the dashboard, the UI displays a list of 50 available tiles. If you instantiate all 50 GeoRasterImage objects at startup, the application freezes for 30 seconds and consumes over 7 GB of RAM, even though the user might only click to inspect one or two images:

1 // Naive implementation: Heavy immediate allocation and loading
2 class GeoRasterImage {
3   #filename;
4   #rawBuffer;
5 
6   constructor(filename) {
7     this.#filename = filename;
8     // Expensive eager loading at construction time!
9     console.log(`[EAGER] Loading 150 MB raster from cloud: ${filename}...`);
10     this.#rawBuffer = new Array(150_000_000); 
11   }
12 
13   display() {
14     console.log(`Rendering ${this.#filename} (${this.#rawBuffer.length} bytes)`);
15   }
16 }
17 
18 // Startup: Allocating 50 images freezes UI and exhausts memory
19 const tiles = [
20   new GeoRasterImage("tile_001.tif"),
21   new GeoRasterImage("tile_002.tif"),
22   // ... 48 more images loaded immediately!
23 ];

1 public class Example {
2     static class GeoRasterImage {
3         private final String filename;
4         private final byte[] buffer;
5 
6         public GeoRasterImage(String filename) {
7             this.filename = filename;
8             System.out.println("[EAGER] Loading 150 MB raster from cloud: " + filename);
9             this

Eagerly instantiating resource-heavy objects during startup degrades performance and exhausts system resources for objects that may never be rendered.

The solution

The Proxy pattern provides a surrogate or placeholder object that implements the exact same interface as the real resource (Subject). The proxy intercepts client calls and defers the expensive instantiation of the RealSubject until the exact moment a method is called (Virtual Proxy), checks security permissions (Protection Proxy), or returns cached results (Caching Proxy).

• Subject (Image): Common interface implemented by both the real object and the proxy.
• RealSubject (GeoRasterImage): The heavy, expensive, or sensitive component being wrapped.
• Proxy (LazyImageProxy): Holds a reference to the RealSubject, instantiating it lazily and controlling access to its methods.
• Client: Interacts with the Proxy identically to the RealSubject.

Step-by-step implementation

Step 1: Define the common subject contract

Both the real subject and the proxy must implement this interface.

1 class Image {
2   display() {
3     throw new Error("display() must be implemented");
4   }
5 }

1 public class Example {
2     interface Image {
3         void display();
4     }
5 
6     public static void main(

Step 2: Implement the heavy real subject

The real subject performs the heavy initialization (disk reads, network calls, memory allocation).

Step 3: Implement the virtual proxy with lazy loading

The proxy defers creating the real subject until display() is invoked.

The complete example

Here is the complete runnable example demonstrating lazy loading, caching, and access authorization via Proxies.

1 --- Operator Access (First Call: Cache Miss) ---
2 [Cache Miss] Fetching from database for cust_101...
3 [SQL Query] SELECT * FROM customers WHERE id = 'cust_101' (simulating 50ms latency)
4 Received: {
5   id: 'cust_101',
6   name: 'Alice Developer',
7   plan: 'Enterprise',
8   secretToken: '[REDACTED]'
9 }
10 
11 --- Operator Access (Second Call: Cache Hit) ---
12 [Cache Hit] Returning cached record for cust_101
13 Received: {
14   id: 'cust_101',
15 

Variations

Types of proxies in practice

1. Virtual Proxy (Lazy Loading): Postpones instantiating expensive objects until actually required.
2. Protection Proxy (Access Control): Checks caller credentials and authorization tokens before delegating.
3. Caching Proxy: Stores return values of deterministic operations in local memory, serving repeated queries without hitting disk or network.
4. Remote Proxy: Provides a local stub that handles socket serialization, network transport, and deserialization to an object running in a remote process (e.g. gRPC or Java RMI).
5. Logging / Audit Proxy: Records method invocations, arguments, timestamps, and execution duration without modifying business logic.

Dynamic proxies in JavaScript and Java

Modern languages provide meta-programming constructs to build dynamic proxies without generating boilerplate wrapper classes:

• JavaScript Proxy: The built-in new Proxy(target, handler) allows developers to define traps for property access (get), assignment (set), function calls (apply), and property enumeration (has). Vue 3's entire reactivity engine is powered by JavaScript Proxy objects.
• Java Dynamic Proxies: java.lang.reflect.Proxy.newProxyInstance() dynamically constructs a proxy implementing any interface at runtime, dispatching all calls to an InvocationHandler.

Where you've already used it

• Hibernate / Spring Data JPA Lazy Loading: When an entity has a @ManyToOne(fetch = FetchType.LAZY) relationship, Hibernate returns a proxy subclass (via ByteBuddy). The database SQL query is only executed when entity.getRelated().getName() is invoked.
• Vue 3 Reactivity: Vue wraps state objects in JavaScript Proxy instances to detect mutations and trigger targeted DOM updates.
• Spring @Transactional & Security: Spring injects AOP proxies around service beans to open database transactions, commit/rollback, and enforce @PreAuthorize security checks.
• Reverse Proxies (Nginx, Envoy, Cloudflare): Network-level proxies that terminate TLS, balance load, throttle rates, and cache static assets before forwarding requests to backend origin servers.

Pros and cons

When not to use it

Do not use Proxy if the real subject is already lightweight, cheap to instantiate, and does not require security or caching controls. Adding proxy wrappers around trivial domain POJOs adds unnecessary indirection.

Related patterns

Interview questions

How does Proxy differ from Decorator? While both share the exact same interface as the wrapped object, Proxy controls access, lifecycle (lazy initialization), and caching, often creating the RealSubject itself. Decorator adds new business capabilities and responsibilities, usually receiving the component from the client.

How does JavaScript's built-in Proxy object work? new Proxy(target, handler) intercepts fundamental language operations on the target object using traps (such as get, set, deleteProperty, and apply), enabling reactive data binding, validation, and property virtualization.

What is the difference between static proxies and dynamic proxies in Java? A static proxy is written by hand at compile time, implementing the target interface explicitly. A dynamic proxy is generated in memory at runtime via java.lang.reflect.Proxy or bytecode manipulation (ByteBuddy), forwarding all method calls to an InvocationHandler.

How does Hibernate implement lazy loading using proxies? When loading an entity with lazy relationships, Hibernate initializes the field with a dynamic proxy that holds an uninitialized state flag and the entity's ID. When a getter is called on the proxy, it intercepts the call, executes a SELECT query against the database, populates the real entity, and delegates the getter.