Proxy Pattern · Design Patterns

What is the Proxy pattern?

Proxy means: put an object in front of another object so you can control access to it.

The proxy implements the same interface as the real object. Callers talk to the proxy as if it were the real thing. Behind the scenes, the proxy decides when to create the real object, whether the caller is allowed to proceed, or whether to cache a result, before forwarding the call.

In plain words: the proxy is a door. The room behind the door is the real object. Callers knock on the door; the door decides what happens next.

This differs from Decorator. A decorator’s main job is to add behavior. A proxy’s main job is to control access — even when it also happens to add a little behavior along the way.

The problem it solves

Suppose you have an image that is expensive to load.

class Image:
    def display(self) -> None:
        raise NotImplementedError


class RealImage(Image):
    def __init__(self, filename: str) -> None:
        self._filename = filename
        self._load_from_disk()  # slow

    def _load_from_disk(self) -> None:
        print(f"Loading {self._filename} from disk")

    def display(self) -> None:
        print(f"Displaying {self._filename}")

public interface Image {
    void display();
}

public class RealImage implements Image {
    private final String filename;

    public RealImage(String filename) {
        this.filename = filename;
        loadFromDisk(); // slow
    }

    private void loadFromDisk() {
        System.out.println("Loading " + filename + " from disk");
    }

    @Override
    public void display() {
        System.out.println("Displaying " + filename);
    }
}

type Image interface {
	Display()
}

type RealImage struct {
	filename string
}

func NewRealImage(filename string) *RealImage {
	img := &RealImage{filename: filename}
	img.loadFromDisk() // slow
	return img
}

func (r *RealImage) loadFromDisk() {
	fmt.Println("Loading", r.filename, "from disk")
}

func (r *RealImage) Display() {
	fmt.Println("Displaying", r.filename)
}

interface Image {
  display(): void;
}

class RealImage implements Image {
  constructor(private filename: string) {
    this.loadFromDisk(); // slow
  }

  private loadFromDisk() {
    console.log(`Loading ${this.filename} from disk`);
  }

  display() {
    console.log(`Displaying ${this.filename}`);
  }
}

If a gallery constructs a RealImage for every thumbnail, users pay the load cost even for photos they never open. You want the same Image interface, but with lazy loading baked into how the object is reached.

A virtual proxy: load only when needed

A virtual proxy delays creation of the expensive object until the first real use.

class ImageProxy(Image):
    def __init__(self, filename: str) -> None:
        self._filename = filename
        self._real_image: RealImage | None = None  # do not load yet

    def display(self) -> None:
        if self._real_image is None:
            self._real_image = RealImage(self._filename)
        self._real_image.display()


# use
photo: Image = ImageProxy("vacation.jpg")
# nothing loaded yet
photo.display()  # loads once, then shows
photo.display()  # reuses the loaded image

public class ImageProxy implements Image {
    private final String filename;
    private RealImage realImage;

    public ImageProxy(String filename) {
        this.filename = filename;
        // do not load yet
    }

    @Override
    public void display() {
        if (realImage == null) {
            realImage = new RealImage(filename);
        }
        realImage.display();
    }
}

// use
Image photo = new ImageProxy("vacation.jpg");
// nothing loaded yet
photo.display(); // loads once, then shows
photo.display(); // reuses the loaded image

type ImageProxy struct {
	filename  string
	realImage *RealImage // do not load yet
}

func (p *ImageProxy) Display() {
	if p.realImage == nil {
		p.realImage = NewRealImage(p.filename)
	}
	p.realImage.Display()
}

// use
var photo Image = &ImageProxy{filename: "vacation.jpg"}
// nothing loaded yet
photo.Display() // loads once, then shows
photo.Display() // reuses the loaded image

class ImageProxy implements Image {
  private realImage?: RealImage; // do not load yet

  constructor(private filename: string) {}

  display() {
    if (!this.realImage) {
      this.realImage = new RealImage(this.filename);
    }
    this.realImage.display();
  }
}

// use
const photo: Image = new ImageProxy('vacation.jpg');
// nothing loaded yet
photo.display(); // loads once, then shows
photo.display(); // reuses the loaded image

From the caller’s point of view, photo is just an Image. The proxy hides the timing of the expensive work.

Other common kinds of proxy

People use the same shape for several jobs:

Protection proxy. Check permissions before forwarding. A document editor might allow reading for everyone, but only editors can call save().
Remote proxy. Look local, talk over the network. The caller thinks it has a normal object; the proxy sends the request to another machine.
Caching / smart proxy. Remember a previous result, count references, or write an audit line before calling through.

The shared idea is always the same: same interface, controlled access, real object somewhere behind the proxy.

A protection proxy example

class Document:
    def read(self) -> str:
        raise NotImplementedError

    def save(self, content: str) -> None:
        raise NotImplementedError


class RealDocument(Document):
    def __init__(self, content: str) -> None:
        self._content = content

    def read(self) -> str:
        return self._content

    def save(self, content: str) -> None:
        self._content = content


class ProtectedDocument(Document):
    def __init__(self, document: RealDocument, can_edit: bool) -> None:
        self._document = document
        self._can_edit = can_edit

    def read(self) -> str:
        return self._document.read()

    def save(self, content: str) -> None:
        if not self._can_edit:
            raise PermissionError("Read-only access")
        self._document.save(content)

public interface Document {
    String read();
    void save(String content);
}

public class RealDocument implements Document {
    private String content;

    public RealDocument(String content) {
        this.content = content;
    }

    @Override
    public String read() {
        return content;
    }

    @Override
    public void save(String content) {
        this.content = content;
    }
}

public class ProtectedDocument implements Document {
    private final RealDocument document;
    private final boolean canEdit;

    public ProtectedDocument(RealDocument document, boolean canEdit) {
        this.document = document;
        this.canEdit = canEdit;
    }

    @Override
    public String read() {
        return document.read();
    }

    @Override
    public void save(String content) {
        if (!canEdit) {
            throw new SecurityException("Read-only access");
        }
        document.save(content);
    }
}

type Document interface {
	Read() string
	Save(content string)
}

type RealDocument struct {
	content string
}

func (d *RealDocument) Read() string        { return d.content }
func (d *RealDocument) Save(content string) { d.content = content }

type ProtectedDocument struct {
	document *RealDocument
	canEdit  bool
}

func (p *ProtectedDocument) Read() string { return p.document.Read() }

func (p *ProtectedDocument) Save(content string) {
	if !p.canEdit {
		panic("read-only access")
	}
	p.document.Save(content)
}

interface Document {
  read(): string;
  save(content: string): void;
}

class RealDocument implements Document {
  constructor(private content: string) {}

  read() {
    return this.content;
  }

  save(content: string) {
    this.content = content;
  }
}

class ProtectedDocument implements Document {
  constructor(
    private document: RealDocument,
    private canEdit: boolean,
  ) {}

  read() {
    return this.document.read();
  }

  save(content: string) {
    if (!this.canEdit) {
      throw new Error('Read-only access');
    }
    this.document.save(content);
  }
}

Callers still depend on Document. The proxy enforces the rule without changing RealDocument.

When it helps

Use a proxy when the object’s access path needs special handling: expensive creation, security checks, remote calls, or light caching around an existing type.

It also helps when you want callers to keep using a familiar interface while you change what happens underneath.

When it hurts

Do not add a proxy “just in case.” An extra layer that always forwards with no real policy makes the code harder to follow.

Be careful when the proxy changes behavior enough to surprise callers — silently failing, or caching mutable data without a clear invalidation rule. A good proxy stays honest: same interface, predictable semantics, documented side effects.

If your goal is mainly to stack optional features, look at Decorator first. If your goal is to simplify a whole subsystem with many classes, look at Facade.

Practical tips

Give the proxy the same interface as the real subject.
Keep business rules in the real object; let the proxy handle access, timing, and transport.
For lazy loading, create the real object once and reuse it.
Name the proxy after its job (ImageProxy, CachingProductRepository) so readers know why it exists.
Document the cost — “first display() hits disk.”

Check your understanding

What is Proxy, in one sentence?
An object that stands in for another and controls how callers reach it.

How is it different from Decorator?
Decorator focuses on adding behavior; Proxy focuses on controlling access, though both wrap an object.

What is a virtual proxy?
A proxy that delays creating or loading the real object until it is needed.

Why keep the same interface?
So callers do not need to know they are talking to a stand-in.

What to learn next

Next: Composite Pattern — treat single items and groups of items through one interface.