Mediator pattern

Introduction

The Mediator pattern is a behavioral pattern for coordinating several objects through one coordinator. It is useful when the interaction has routing, filtering, or sequencing rules that would otherwise spread across many participants.

The Problem It Solves

You are building a chat application. Each User object needs to send messages to every other user in the room. The naive approach gives each user direct references to all the others:

With 5 users you have 20 direct connections. With 50 users, 2,450. Every join or leave updates every other user. Testing one user in isolation requires bringing along all its contacts, and the coupling graph is a complete mesh that gets harder to change as participants are added.

Here is what changes when you apply the Mediator pattern.

Structure

ChatMediator is the abstraction. ChatRoom is the concrete mediator that holds all users and routes messages. Each ChatUser knows only the mediator interface, never other users directly. The N * (N-1) mesh collapses to N connections (each user to the room) plus the room itself.

Visualize this as a before/after: the "before" is a mesh graph with arrows between every pair of nodes, and the "after" is a star with the mediator at the center. The topology makes the reduction in direct coupling easy to see.

Implementation

// The mediator interface. Components depend on this abstraction,
// never on each other. Swappable for testing (mock mediator).
public interface ChatMediator {
  void sendMessage(ChatUser sender, String message);
  void addUser(ChatUser user);
  void removeUser(ChatUser user);
}

Event-based mediator variant

For systems with multiple event types (not just chat messages), the mediator can route by event type. This prevents the mediator interface from growing a new method for every interaction:

// Generic event that any component can publish through the mediator.
public record MediatorEvent(String type, Map<String, Object> payload) {}

// Event-based mediator: components register interest in specific event types.
public class EventMediator {
    private final Map<String, List<Consumer<MediatorEvent>>> handlers =
        new ConcurrentHashMap<>();

    public void on(String eventType, Consumer<MediatorEvent> handler) {
        handlers.computeIfAbsent(eventType, k -> new CopyOnWriteArrayList<>())
                .add(handler);
    }

    // Any component can publish. The mediator routes to interested handlers.
    public void publish(MediatorEvent event) {
        List<Consumer<MediatorEvent>> list = handlers.get(event.type());
        if (list != null) {
            for (Consumer<MediatorEvent> handler : list) {
                handler.accept(event);
            }
        }
    }
}

This variant sits between a pure Mediator and an Event Bus. It is useful when a mediator interface would otherwise grow a method for every event type.

Private messaging through the mediator

A common extension: the mediator can route to a specific user instead of broadcasting. This is still Mediator because the sender does not reference the recipient directly.