Picture this: You're building a clinic management system. You have three appointment types: general consultations, lab tests, and surgeries. Each is modelled as a clean class. Your first feature request is straightforward: calculate the billing fee for each appointment. You add a calculateFee() method to each class. Done.

Then the insurance team needs claim codes per appointment type. You add generateClaimCode() to each class. Then admin wants appointment summaries for records. You add generateSummary(). The compliance team needs discharge notes. Another method on every class.

Six months in, your clean appointment classes look like this:

public class Surgery {
    private String patientName;
    private String procedureName;
    private int durationMinutes;

    public double calculateFee() { /* billing logic */ }
    public String generateClaimCode() { /* insurance code */ }
    public String generateSummary() { /* appointment summary */ }
    public String generateDischargeNote() { /* discharge logic */ }
    // ...more unrelated methods keep piling up
}

Every new operation means modifying every appointment class. Your classes have stopped being models of clinical appointments. They've become dumping grounds for every feature the business ever asked for. Adding a new operation is risky: you touch every class, risk introducing bugs, and trigger a full regression cycle.

The Visitor pattern solves this by separating operations from the object structure they work on. New operations become new visitor classes, and you never touch the appointment classes again.

Understanding the Visitor Pattern

Think of it like a clinic administrator processing different appointment types: the administrator (visitor) knows how to handle a general consultation, a lab test, and a surgery differently. Each appointment doesn't need to know how it gets processed; it just hands itself to the administrator. When the insurance team sends their own claims processor, the appointments don't change, only the processor does.

This pattern promotes Open/Closed Principle, Single Responsibility, and Separation of Concerns by keeping operations in dedicated visitor classes rather than scattered across the element hierarchy.

Visitor Pattern Components

Core Components

• Element Interface: Declares an accept(visitor) method that each concrete element must implement

• Visitor Interface: Declares a visit() method overload for each concrete element type

• Concrete Elements: The object structure (GeneralConsultation, LabTest, Surgery). Each calls visitor.visit(this) in its accept method

• Concrete Visitors: Implement the operation for every element type (BillingVisitor, InsuranceClaimVisitor)

Complete Java Implementation

Let's build a clinic management system that demonstrates the Visitor pattern's power in adding new operations without touching appointment classes.

Element Interface

public interface Appointment {
    void accept(AppointmentVisitor visitor);
    String getPatientName();
}

Visitor Interface

public interface AppointmentVisitor {
    void visit(GeneralConsultation consultation);
    void visit(LabTest labTest);
    void visit(Surgery surgery);
}

Concrete Elements

public class GeneralConsultation implements Appointment {
    private String patientName;
    private String doctorName;

    public GeneralConsultation(String patientName, String doctorName) {
        this.patientName = patientName;
        this.doctorName = doctorName;
    }

    public String getDoctorName() { return doctorName; }

    @Override public String getPatientName() { return patientName; }
    @Override public void accept(AppointmentVisitor visitor) { visitor.visit(this); }
}

public class LabTest implements Appointment {
    private String patientName;
    private String testType;

    public LabTest(String patientName, String testType) {
        this.patientName = patientName;
        this.testType = testType;
    }

    public String getTestType() { return testType; }

    @Override public String getPatientName() { return patientName; }
    @Override public void accept(AppointmentVisitor visitor) { visitor.visit(this); }
}

public class Surgery implements Appointment {
    private String patientName;
    private String procedureName;

    public Surgery(String patientName, String procedureName) {
        this.patientName = patientName;
        this.procedureName = procedureName;
    }

    public String getProcedureName() { return procedureName; }

    @Override public String getPatientName() { return patientName; }
    @Override public void accept(AppointmentVisitor visitor) { visitor.visit(this); }
}

Concrete Visitors

public class BillingVisitor implements AppointmentVisitor {
    private double totalBill;

    @Override
    public void visit(GeneralConsultation consultation) {
        double fee = 80.00;
        totalBill += fee;
        System.out.println(consultation.getPatientName() + " [Consultation] $" + fee + " (Dr. " + consultation.getDoctorName() + ")");
    }

    @Override
    public void visit(LabTest labTest) {
        double fee = 45.00;
        totalBill += fee;
        System.out.println(labTest.getPatientName() + " [Lab Test] $" + fee + " (" + labTest.getTestType() + ")");
    }

    @Override
    public void visit(Surgery surgery) {
        double fee = 500.00;
        totalBill += fee;
        System.out.println(surgery.getPatientName() + " [Surgery] $" + fee + " (" + surgery.getProcedureName() + ")");
    }

    public double getTotalBill() { return totalBill; }
}

public class InsuranceClaimVisitor implements AppointmentVisitor {

    @Override
    public void visit(GeneralConsultation consultation) {
        System.out.println(consultation.getPatientName() + " Code: GP-001 Type: General Practice");
    }

    @Override
    public void visit(LabTest labTest) {
        System.out.println(labTest.getPatientName() + " Code: LT-042 Type: Diagnostic Lab");
    }

    @Override
    public void visit(Surgery surgery) {
        System.out.println(surgery.getPatientName() + " Code: SG-301 Type: Surgical Procedure");
    }
}

Client

public class ClinicBillingDemo {
    public static void main(String[] args) {
        System.out.println("=== Clinic Management System ===\n");

        List<Appointment> appointments = Arrays.asList(
            new GeneralConsultation("Alice Johnson", "Smith"),
            new LabTest("Bob Williams", "Blood Panel"),
            new Surgery("Carol Davis", "Appendectomy"),
            new GeneralConsultation("David Brown", "Patel")
        );

        System.out.println("--- Insurance Claims ---");
        InsuranceClaimVisitor claims = new InsuranceClaimVisitor();
        for (Appointment appointment : appointments) {
            appointment.accept(claims);
        }

        System.out.println("\n--- Patient Bills ---");
        BillingVisitor billing = new BillingVisitor();
        for (Appointment appointment : appointments) {
            appointment.accept(billing);
        }
        System.out.println("Total: $" + billing.getTotalBill());
    }
}

Expected Output:

=== Clinic Management System ===

--- Insurance Claims ---
Alice Johnson Code: GP-001 Type: General Practice
Bob Williams Code: LT-042 Type: Diagnostic Lab
Carol Davis Code: SG-301 Type: Surgical Procedure
David Brown Code: GP-001 Type: General Practice

--- Patient Bills ---
Alice Johnson [Consultation] $80.0 (Dr. Smith)
Bob Williams [Lab Test] $45.0 (Blood Panel)
Carol Davis [Surgery] $500.0 (Appendectomy)
David Brown [Consultation] $80.0 (Dr. Patel)
Total: $705.0

🚀 Get the Complete Implementation

The full code with additional visitors (risk analysis, compliance audit) is available in our Design Patterns Repository.

# Clone and run the complete demo
git clone https://github.com/shift-elevate/design-patterns.git
cd design-patterns
mvn test -Dtest=VisitorPatternTest

Real World Examples

The Visitor pattern is extensively used in real-world systems where stable structures need evolving operations:

1. Compiler Abstract Syntax Trees

Compilers build an AST (Abstract Syntax Tree) representing the parsed source code. Different compiler phases (type checking, optimisation, code generation, linting) are implemented as separate visitors that traverse the same tree. The AST node classes remain untouched while each new compiler phase is a new visitor, making compiler toolchains highly extensible.

2. Document Export

Applications that model documents as a tree of elements (paragraphs, headings, tables, images) use the Visitor pattern for export operations. Each export format (PDF, HTML, plain text) is implemented as a separate visitor that knows how to render every element type, without any element class needing to know about export formats.

3. Static Code Analysis

Static analysis tools analyse source code by visiting AST nodes. Each analysis rule (detect null dereference, find unused variables, enforce naming conventions) is an independent visitor. Adding a new rule means adding a new visitor, and the AST structure and existing rules are never modified.

When to Use the Visitor Pattern

Understanding when to apply the Visitor pattern is crucial for making the right architectural decisions. Here's when it shines and when alternatives might be better:

✅ Ideal Scenarios:

• You have a stable object structure but need to frequently add new operations.

• You want to keep unrelated operations out of the element classes.

• A class hierarchy contains many distinct types and you need type-specific behaviour across multiple operations.

• You need to accumulate state across elements during traversal (like totalling tax across all assets).

❌ Skip It When:

• The element hierarchy changes frequently, as adding a new element type requires updating every visitor.

• The object structure is simple and has only a handful of operations that rarely change.

• Encapsulation of element internals is critical, as visitors often need access to internal fields.

• The double-dispatch mechanism adds more complexity than the problem warrants.

Next Steps: Apply the Visitor Pattern in Your Project

Ready to implement the Visitor pattern in your own projects? Here's a structured approach to get you started:

1. Identify Stable Structures: Find class hierarchies that rarely gain new types but frequently gain new operations.

2. Define the Visitor Interface: Declare one method per concrete element type so each visitor knows how to handle every element.

3. Add Accept to Elements: Each element implements a method that hands itself to the visitor, keeping all operation logic out of the element.

4. Create Concrete Visitors: Implement each operation as a dedicated visitor class with its own state.

5. Drive from the Client: Iterate the element collection and let each element accept the visitor in turn.

The Visitor pattern transforms bloated element classes into clean, focused models by relocating operations to dedicated visitor classes that can evolve independently. Your element classes model your domain; your visitor classes model what you do with it.

A queue is a linear data structure that follows the First-In-First-Out (FIFO) principle. Think of it like a line at a coffee shop: the first person to join the line is the first person to be served. Queues are essential for managing tasks in order, from handling print jobs to processing requests in web servers.

Explanation

A queue operates on two main principles:

FIFO (First-In-First-Out): Elements are removed in the same order they were added. The first element you add is the first one you remove.

Core Operations:

• Enqueue: Add an element to the back of the queue

• Dequeue: Remove and return the element from the front of the queue

• Peek: View the front element without removing it

• isEmpty: Check if the queue has no elements

Let's see FIFO in action with a simple example:

const queue = [];

function enqueue(element) {
  queue.push(element);
}

function dequeue() {
  return queue.shift();
}

enqueue('First');
enqueue('Second');
enqueue('Third');
console.log('Queue:', queue);

const item1 = dequeue();
console.log('Removed:', item1);

const item2 = dequeue();
console.log('Removed:', item2);

console.log('Remaining:', queue);

Watch the visualization: Notice how “First” goes in first and comes out first, maintaining the exact order elements were added.

The key insight is that queues maintain order naturally. Unlike stacks where you work with the most recent item, queues ensure fair processing where older items get handled first.

Implementation

We'll implement a queue using an array with methods that maintain the FIFO principle. While arrays provide flexibility, we'll restrict operations to queue-specific behaviours.

Queue Class

class Queue {
  constructor() {
    this.items = [];
  }

  // Add element to the back of the queue
  enqueue(element) {
    this.items.push(element);
    console.log(`Enqueued: ${element}`);
  }

  // Remove and return element from the front
  dequeue() {
    if (this.isEmpty()) {
      console.log('Queue is empty');
      return null;
    }
    const removed = this.items.shift();
    console.log(`Dequeued: ${removed}`);
    return removed;
  }

  // View the front element without removing it
  peek() {
    if (this.isEmpty()) {
      return null;
    }
    return this.items[0];
  }

  // Check if queue is empty
  isEmpty() {
    return this.items.length === 0;
  }

  // Get the size of the queue
  size() {
    return this.items.length;
  }

  // Clear all elements
  clear() {
    this.items = [];
    console.log('Queue cleared');
  }

  // Display queue contents
  print() {
    console.log('Queue:', this.items.join(' <- '));
  }
}

Enqueue Operation

The enqueue operation adds elements to the back of the queue using push(). This ensures new elements always go to the end, maintaining FIFO order.

const queue = [];

function enqueue(element) {
  queue.push(element);
  console.log(`Enqueued: ${element}`);
}

enqueue('Download file');
enqueue('Process data');
enqueue('Send email');

console.log('Queue:', queue);

Watch the visualization: Each “push()” adds an element to the end. The queue grows from left to right, with new tasks joining at the back of the line.

Dequeue Operation

The dequeue operation removes and returns the element from the front using shift(). This maintains FIFO by always serving the oldest element first.

const queue = ['Download file', 'Process data', 'Send email'];

function dequeue() {
  return queue.shift();
}

console.log('Initial queue:', queue);

const processed1 = dequeue();
const processed2 = dequeue();

console.log('Processed:', processed1, 'and', processed2);
console.log('Remaining:', queue);

Watch the visualization: Notice how shift() always removes from index 0. The first task in gets processed first, and the remaining tasks shift forward in the queue.

Peek Operation

Peek lets you view the front element without removing it. This is useful when you need to check what's next without actually processing it.

const queue = ['Download file', 'Process data', 'Send email'];

function peek() {
  return queue[0];
}

const nextTask = peek();

console.log('Next task:', nextTask);
console.log('Queue unchanged:', queue);

Watch the visualization: The nextJob variable gets the value, but the jobQueue array remains unchanged. Peek is a read-only operation.

Complexity

Time Complexity:

• Enqueue: O(1) - Adding to the end of an array is constant time

• Dequeue: O(n) - Removing from the front requires shifting all remaining elements

• Peek: O(1) - Accessing the first element is constant time

• isEmpty/size: O(1) - Checking length is constant time

Space Complexity: O(n) - Where n is the number of elements stored in the queue

Imagine you need to store a list of your top 5 favorite songs. You could create five separate variables, or you could use a single array. Arrays are the most fundamental data structure in programming, an ordered collection that lets you store and access multiple values under one name.

Explanation

An array stores elements in contiguous, indexed slots. Each element has a position called an index, starting at 0.

Core Operations:

• Insert: Add an element to the array

• Delete: Remove an element from the array

• Seek: Read an element at a specific index

• Traverse: Visit every element in order

Think of an array like a row of numbered lockers. Locker 0 holds the first item, locker 1 holds the second, and so on. You can jump directly to any locker if you know its number.

Let's see this in action:

const numbers = [10, 20, 30, 40, 50];

console.log('First element:', numbers[0]);
console.log('Second element:', numbers[1]);
console.log('Total elements:', numbers.length);

Watch the visualization: Notice how index “0” maps to the first element. The length property always equals the highest index + 1. Arrays are zero-indexed, so a 5-element array has indices 0 through 4.

The key insight: arrays give you O(1) random access. No matter how large the array, reading any element by index takes the same amount of time.

Implementation

Creating Arrays

// Empty array
const empty = [];

// Array with initial values
const numbers = [10, 20, 30, 40, 50];

// Access by index
console.log('Element at index 2:', numbers[2]);

// Last element using length
console.log('Last element:', numbers[numbers.length - 1]);

Watch the visualization: Track how numbers[2] directly jumps to index 2 without scanning through 0 and 1. That's direct access in action.

Insert Operation

push() adds an element to the end of the array in O(1). No existing elements need to move.

const numbers = [10, 20];

numbers.push(30);
console.log('After push:', numbers);

numbers.push(40);
console.log('After another push:', numbers);

console.log('Length:', numbers.length);

Watch the visualization: Each push() places the new element at the next available slot at the end. The length grows by 1 each time, but nothing else shifts.

Delete Operation

pop() removes and returns the last element in O(1). Like push, no other elements are affected.

const numbers = [10, 20, 30, 40];

const last = numbers.pop();
console.log('Removed:', last);
console.log('After pop:', numbers);

const second = numbers.pop();
console.log('Removed:', second);
console.log('After pop:', numbers);

Watch the visualization: Each pop() removes from the end and the length shrinks by 1. The remaining elements stay exactly where they are, so no shifting occurs.

Seek Operation

Seeking retrieves an element directly by its index in O(1). No scanning required because the array computes the exact memory location instantly.

const numbers = [10, 20, 30, 40, 50];

console.log('Element at index 0:', numbers[0]);
console.log('Element at index 3:', numbers[3]);
console.log('Last element:', numbers[numbers.length - 1]);

Watch the visualization: Whether you seek index 0 or index 4, the operation takes the same amount of time. That's the power of index-based access.

Traverse Operation

Traversal visits every element in the array from index 0 to the last. Unlike seek, you don't know which index you want, so you need to process all of them. This costs O(n) since you touch every element once.

const numbers = [10, 20, 30];

let total = 0;
for (let i = 0; i < numbers.length; i++) {
  console.log(`Index ${i}: ${numbers[i]}`);
  total += numbers[i];
}

console.log('Total:', total);

Watch the visualization: The index “i” steps through 0, 1, 2 in order, and every element is visited exactly once. The more elements in the array, the longer a traversal takes.

Complexity

Time Complexity

• Seek (access by index): O(1), direct jump to memory location

• Insert (push to end): O(1), no shifting needed

• Delete (pop from end): O(1), no shifting needed

• Traverse: O(n), every element is visited once

Space Complexity

O(n), where n is the number of elements stored in the array

Picture this: You're building a database connection manager for your application. Your initial approach seems logical: create a new connection object whenever you need to access the database.

But requirements evolve quickly. You realize you need to limit database connections to prevent resource exhaustion, maintain connection pooling, and ensure consistent configuration across your application. Your code becomes scattered with connection creation logic, leading to resource leaks, inconsistent configurations, and performance issues.

Suddenly, you're dealing with multiple database connections consuming memory, different configurations causing data inconsistencies, and a system that's hard to manage and debug. Sound familiar?

The Singleton pattern solves this challenge elegantly. Let's explore how.

Understanding the Singleton Pattern

The Singleton pattern ensures that a class has only one instance and provides a global point of access to that instance. It guarantees that no other instance can be created and provides a way to access the single instance from anywhere in the application.

Think of it like your computer's clipboard: there's only one clipboard, and every application reads from and writes to the same one. When you copy text in your browser and paste it in your editor, both apps are accessing the same shared instance. You wouldn't want multiple clipboards causing confusion about what was last copied.

This pattern promotes Resource Management, Global Access, and Instance Control while ensuring consistent behaviour across the application.

Singleton Pattern Components

Core Components

• Singleton: The class that ensures only one instance exists, with a private constructor, static instance variable, and static getter method

• Singleton - Eager Initialization: A variant that creates the instance at class loading time, trading lazy creation for simplicity and inherent thread safety

Complete Java Implementation

Let's build a database connection manager that demonstrates the Singleton pattern's power in managing single instances with global access.

Singleton (DatabaseConnectionManager)

public class DatabaseConnectionManager {
    private static volatile DatabaseConnectionManager instance;
    private String connectionString;
    private boolean isConnected;
    private int connectionCount;
    
    private DatabaseConnectionManager() {
        this.connectionString = "jdbc:mysql://localhost:3306/mydb";
        this.isConnected = false;
        this.connectionCount = 0;
        System.out.println("DatabaseConnectionManager instance created");
    }
    
    public static DatabaseConnectionManager getInstance() {
        if (instance == null) {
            synchronized (DatabaseConnectionManager.class) {
                if (instance == null) {
                    instance = new DatabaseConnectionManager();
                }
            }
        }
        return instance;
    }
    
    public void connect() {
        if (!isConnected) {
            isConnected = true;
            connectionCount++;
            System.out.println("Connected to database: " + connectionString);
        } else {
            System.out.println("Already connected to database");
        }
    }
    
    public void disconnect() {
        if (isConnected) {
            isConnected = false;
            System.out.println("Disconnected from database");
        } else {
            System.out.println("Not connected to database");
        }
    }
    
    public void executeQuery(String query) {
        if (isConnected) {
            System.out.println("Executing query: " + query);
        } else {
            System.out.println("Cannot execute query - not connected to database");
        }
    }
    
    public String getConnectionString() { return connectionString; }
    public boolean isConnected() { return isConnected; }
    public int getConnectionCount() { return connectionCount; }
    
    public void setConnectionString(String connectionString) {
        this.connectionString = connectionString;
        System.out.println("Connection string updated to: " + connectionString);
    }
}

Singleton - Eager Initialization (ConfigurationManager)

public class ConfigurationManager {
    private static final ConfigurationManager instance = new ConfigurationManager();
    private String appName;
    private String version;
    private Map<String, String> settings;
    
    private ConfigurationManager() {
        this.appName = "My Application";
        this.version = "1.0.0";
        this.settings = new HashMap<>();
        loadDefaultSettings();
        System.out.println("ConfigurationManager instance created (eager initialization)");
    }
    
    public static ConfigurationManager getInstance() {
        return instance;
    }
    
    private void loadDefaultSettings() {
        settings.put("theme", "dark");
        settings.put("language", "en");
        settings.put("timeout", "30");
    }
    
    public String getSetting(String key) {
        return settings.get(key);
    }
    
    public void setSetting(String key, String value) {
        settings.put(key, value);
        System.out.println("Setting updated: " + key + " = " + value);
    }
    
    public String getAppName() { return appName; }
    public String getVersion() { return version; }
    public Map<String, String> getAllSettings() { return new HashMap<>(settings); }
}

Client

public class SingletonDemo {
    public static void main(String[] args) {
        System.out.println("=== Singleton Pattern Demo ===\n");
        
        System.out.println("=== Database Connection Manager ===");
        DatabaseConnectionManager dbManager1 = DatabaseConnectionManager.getInstance();
        DatabaseConnectionManager dbManager2 = DatabaseConnectionManager.getInstance();
        
        System.out.println("Are both instances the same? " + (dbManager1 == dbManager2));
        
        dbManager1.connect();
        dbManager2.executeQuery("SELECT * FROM users");
        dbManager1.disconnect();
        
        System.out.println("\n=== Configuration Manager ===");
        ConfigurationManager config1 = ConfigurationManager.getInstance();
        ConfigurationManager config2 = ConfigurationManager.getInstance();
        
        System.out.println("Are both instances the same? " + (config1 == config2));
        
        System.out.println("App Name: " + config1.getAppName());
        System.out.println("Version: " + config1.getVersion());
        config1.setSetting("theme", "light");
        System.out.println("Theme setting: " + config2.getSetting("theme"));
        
        System.out.println("\n=== Thread Safety Test ===");
        testThreadSafety();
    }
    
    private static void testThreadSafety() {
        System.out.println("Testing thread safety with multiple threads...");
        
        Thread[] threads = new Thread[3];
        for (int i = 0; i < 3; i++) {
            final int threadId = i;
            threads[i] = new Thread(() -> {
                DatabaseConnectionManager instance = DatabaseConnectionManager.getInstance();
                System.out.println("Thread " + threadId + " got instance: " + instance.hashCode());
            });
        }
        
        for (Thread thread : threads) {
            thread.start();
        }
        
        for (Thread thread : threads) {
            try {
                thread.join();
            } catch (InterruptedException e) {
                e.printStackTrace();
            }
        }
    }
}

Expected Output:

=== Singleton Pattern Demo ===

=== Database Connection Manager ===
DatabaseConnectionManager instance created
Are both instances the same? true
Connected to database: jdbc:mysql://localhost:3306/mydb
Executing query: SELECT * FROM users
Disconnected from database

=== Configuration Manager ===
ConfigurationManager instance created (eager initialization)
Are both instances the same? true
App Name: My Application
Version: 1.0.0
Setting updated: theme = light
Theme setting: light

=== Thread Safety Test ===
Testing thread safety with multiple threads...
Thread 0 got instance: 1234567890
Thread 1 got instance: 1234567890
Thread 2 got instance: 1234567890

🚀 Get the Complete Implementation

The full code with advanced singleton implementations and thread safety is available in our Design Patterns Repository.

# Clone and run the complete demo
git clone https://github.com/shift-elevate/design-patterns.git
cd design-patterns
mvn test -Dtest=SingletonPatternTest

Real World Examples

The Singleton pattern is extensively used in real-world applications:

1. Database Connection Pools

Database connection managers use Singleton patterns to ensure only one connection pool exists, preventing resource exhaustion and maintaining consistent connection management.

2. Logging Systems

Logging frameworks use Singleton patterns to provide a single, global logging instance that can be accessed from anywhere in the application.

3. Configuration Management

Configuration managers use Singleton patterns to ensure consistent application settings across all components.

4. Cache Systems

Cache managers use Singleton patterns to provide a single, shared cache instance that can be accessed by multiple components.

When to Use Singleton Pattern

Understanding when to apply the Singleton pattern is crucial for making the right architectural decisions. Here's when it shines and when alternatives might be better:

✅ Ideal Scenarios:

• You need exactly one instance of a class throughout the application.

• You want to control access to shared resources (database connections, file systems).

• You need a global point of access for configuration or logging.

• You want to ensure consistent behavior across the application.

❌ Skip It When:

• You need multiple instances with different configurations.

• The class doesn't maintain state or has no shared resources.

• You're building a library that might be used in different contexts.

• You need to subclass the singleton class.

Next Steps: Apply Singleton Pattern in Your Project

Ready to implement the Singleton pattern in your own projects? Here's a structured approach to get you started:

1. Identify Single Instance Needs: Look for classes that should have only one instance (loggers, configuration managers, connection pools).

2. Make Constructor Private: Prevent external instantiation of the class.

3. Create Static Getter Method: Provide a way to access the single instance.

4. Ensure Thread Safety: Use double-checked locking or enum singleton for thread safety.

5. Test Singleton Behavior: Verify that only one instance is created and accessed.

The Singleton pattern transforms uncontrolled object creation into managed, single-instance systems. By ensuring only one instance exists, you build applications with consistent behaviour and efficient resource management.

Found this helpful? Share it with a colleague who's struggling with uncontrolled object creation. Got questions? We'd love to hear from you at [email protected]

This pattern is essential for any service exposed to external clients such as APIs, microservices, or cloud functions, where you cannot fully control how callers behave. By implementing intelligent rate limiting, you prevent abuse, protect downstream dependencies, and maintain consistent performance for all users.

This guide walks you through the Throttling pattern from concept to practical implementation, covering the three core rate limiting algorithms, how to apply them in a real API service, and how to choose the right approach for your use case.

• Understanding the Throttling Pattern

• Implementing the Throttling Pattern

• When to Use Throttling Pattern

• Best Practices

Understanding the Throttling Pattern

The Throttling pattern sits in front of your service and intercepts each incoming request. Before passing the request through, it checks whether the client has exceeded their allowed rate. If they have, the request is rejected with a rate limit error (typically HTTP 429) rather than forwarded to the service.

Core Throttling Strategies

Throttling Pattern Strategies

Key Benefits

• System Protection: Prevents services from being overwhelmed by excessive requests.

• Resource Management: Ensures fair allocation of system resources.

• Cost Control: Prevents runaway costs from unexpected traffic spikes.

• Quality of Service: Maintains consistent performance for legitimate users.

• Abuse Prevention: Protects against malicious or accidental abuse.

Implementing the Throttling Pattern

Let's build a throttling system that implements three classic rate limiting algorithms, then applies one of them in a practical API service.

Implementation Overview

• TokenBucketRateLimiter: The most flexible algorithm. Clients accumulate tokens over time and spend one per request, allowing short bursts while enforcing a long-term average rate.

• SlidingWindowRateLimiter: The most accurate algorithm. Tracks the timestamp of every request and counts how many fall within the last N milliseconds, giving a precise rolling rate.

• FixedWindowRateLimiter: The simplest algorithm. Counts requests per fixed time slot and resets the counter when the slot changes.

• RateLimitedApiService: A practical API service that applies Token Bucket throttling per client.

• Main: A runnable demo showing normal usage and burst traffic hitting the rate limit.

This implementation uses plain Java with no external dependencies. For production systems, consider using a distributed cache like Redis to share rate limit state across multiple service instances. An in-memory limiter only enforces limits on a single node.

Rate Limiting Algorithms

/**
 * Token Bucket: imagine a bucket that fills with tokens over time.
 * Each request consumes one token. If the bucket is empty, the request is rejected.
 * Allows short bursts (up to capacity) while enforcing a steady long-term rate.
 */
public class TokenBucketRateLimiter {
    private final int capacity;       // Max tokens the bucket can hold (burst limit)
    private final double refillPerMs; // Tokens added per millisecond
    private final Map<String, Bucket> buckets = new HashMap<>();

    public TokenBucketRateLimiter(int capacity, int refillPerSecond) {
        this.capacity = capacity;
        this.refillPerMs = refillPerSecond / 1000.0;
    }

    /** Returns true if the request is allowed, false if rate-limited */
    public boolean isAllowed(String clientId) {
        Bucket bucket = buckets.computeIfAbsent(clientId, k -> new Bucket(capacity));
        bucket.refill();
        return bucket.tryConsume();
    }

    private class Bucket {
        private double tokens;
        private long lastRefillTime = System.currentTimeMillis();

        Bucket(int initialTokens) { this.tokens = initialTokens; }

        /** Add tokens based on how much time has passed since the last refill */
        void refill() {
            long now = System.currentTimeMillis();
            double tokensToAdd = (now - lastRefillTime) * refillPerMs;
            tokens = Math.min(capacity, tokens + tokensToAdd);
            lastRefillTime = now;
        }

        boolean tryConsume() {
            if (tokens >= 1.0) {
                tokens -= 1.0;
                return true;
            }
            return false;
        }
    }
}

/**
 * Sliding Window: tracks the timestamp of every recent request.
 * Only counts requests that fall within the last windowMs milliseconds.
 * Most accurate approach with no boundary artifacts, but uses more memory.
 */
public class SlidingWindowRateLimiter {
    private final int maxRequests;
    private final long windowMs;
    private final Map<String, Queue<Long>> requestLogs = new HashMap<>();

    public SlidingWindowRateLimiter(int maxRequests, long windowMs) {
        this.maxRequests = maxRequests;
        this.windowMs = windowMs;
    }

    public synchronized boolean isAllowed(String clientId) {
        long now = System.currentTimeMillis();
        Queue<Long> timestamps = requestLogs.computeIfAbsent(clientId, k -> new LinkedList<>());

        // Drop timestamps that have slid outside the current window
        while (!timestamps.isEmpty() && now - timestamps.peek() > windowMs) {
            timestamps.poll();
        }

        if (timestamps.size() < maxRequests) {
            timestamps.offer(now);
            return true;
        }
        return false;
    }
}

/**
 * Fixed Window: counts requests within a fixed time slot (e.g., the current minute).
 * Simplest to implement. Trade-off: a burst at a window boundary can send
 * up to 2× the limit in a short period.
 */
public class FixedWindowRateLimiter {
    private final int maxRequests;
    private final long windowMs;
    private final Map<String, Window> windows = new HashMap<>();

    public FixedWindowRateLimiter(int maxRequests, long windowMs) {
        this.maxRequests = maxRequests;
        this.windowMs = windowMs;
    }

    public synchronized boolean isAllowed(String clientId) {
        long currentSlot = System.currentTimeMillis() / windowMs;
        Window window = windows.computeIfAbsent(clientId, k -> new Window(currentSlot));

        // New time slot, reset the counter
        if (window.slot != currentSlot) {
            window.slot = currentSlot;
            window.count = 0;
        }

        if (window.count < maxRequests) {
            window.count++;
            return true;
        }
        return false;
    }

    private static class Window {
        long slot;
        int count = 0;
        Window(long slot) { this.slot = slot; }
    }
}

Practical Implementation: Rate-Limited API Service

/** An API service that enforces per-client rate limits using Token Bucket */
public class RateLimitedApiService {
    private final TokenBucketRateLimiter rateLimiter;

    public RateLimitedApiService(int requestsPerSecond) {
        // Allow bursts up to 5 requests, then refill at the specified rate
        this.rateLimiter = new TokenBucketRateLimiter(5, requestsPerSecond);
    }

    public ApiResponse handleRequest(String clientId, String operation) {
        if (!rateLimiter.isAllowed(clientId)) {
            System.out.println("  [" + clientId + "] THROTTLED: " + operation);
            return new ApiResponse(429, "Rate limit exceeded. Slow down your requests.");
        }
        System.out.println("  [" + clientId + "] OK: " + operation);
        return new ApiResponse(200, "Success");
    }
}

// Simple data class for the API response
public record ApiResponse(int status, String message) {}

Putting It All Together

public class Main {
    public static void main(String[] args) throws InterruptedException {
        // 2 requests/sec with a burst capacity of 5
        RateLimitedApiService service = new RateLimitedApiService(2);

        // Happy path: spread-out requests stay within the rate limit
        System.out.println("=== Normal usage ===");
        service.handleRequest("client-A", "GET /products");
        Thread.sleep(600);
        service.handleRequest("client-A", "GET /orders");
        Thread.sleep(600);
        service.handleRequest("client-A", "GET /profile");

        System.out.println();

        // Burst: 8 requests in quick succession exhaust the bucket and trigger throttling
        System.out.println("=== Burst traffic ===");
        for (int i = 1; i <= 8; i++) {
            service.handleRequest("client-B", "GET /products (request " + i + ")");
        }
    }
}

Example Output

=== Normal usage ===
  [client-A] OK: GET /products
  [client-A] OK: GET /orders
  [client-A] OK: GET /profile

=== Burst traffic ===
  [client-B] OK: GET /products (request 1)
  [client-B] OK: GET /products (request 2)
  [client-B] OK: GET /products (request 3)
  [client-B] OK: GET /products (request 4)
  [client-B] OK: GET /products (request 5)
  [client-B] THROTTLED: GET /products (request 6)
  [client-B] THROTTLED: GET /products (request 7)
  [client-B] THROTTLED: GET /products (request 8)

Choosing the Right Algorithm

All three algorithms limit request rates, but they behave differently at the edges:

• Token Bucket is best when you want to allow short bursts. A client who hasn't sent requests in a while accumulates tokens they can spend all at once, then must wait for the bucket to refill. Use this when occasional spikes are acceptable and you want to reward clients who space out their requests.

• Sliding Window is the most accurate and fairest. It counts exactly how many requests arrived in the last N seconds at any point in time, with no boundary effects. The trade-off is memory: it stores one timestamp per recent request. Use this when precision matters most.

• Fixed Window is the simplest to understand and implement. The risk is the boundary burst: a client can fire maxRequests at 11:59:59 and another maxRequests at 12:00:00, that's 2× the limit in two seconds. Use this for non-critical limits where simplicity is preferred.

When to Use Throttling Pattern

✅ Ideal Scenarios:

• Your API or service is called by external clients whose request behaviour you cannot fully control.

• You need to protect downstream services from being flooded by a single misbehaving client.

• You want fair resource allocation, preventing one client from monopolizing shared capacity.

• You are enforcing business rules around tiered limits (free vs. paid plans).

• You need to cap usage of an expensive downstream service or API to control costs.

• You're building a public-facing API where abuse protection is required.

❌ Skip It When:

• Your service is only called by internal, trusted systems with predictable and controlled request rates.

• You need to guarantee processing of every request. Consider the Queue-based Load Leveling pattern instead.

• The cost of dropped requests exceeds the cost of the overload you're trying to prevent.

• All clients are coordinated and can implement cooperative rate limiting at the source.

• You're in an early-stage prototype where operational complexity isn't yet warranted.

Best Practices

• Return meaningful responses: Respond with HTTP 429 and include a Retry-After header so clients know when to try again. This turns a confusing failure into an actionable signal.

• Key limiters per client, not globally: A single misbehaving client shouldn't degrade service for others. Use a per-client identifier such as user ID, API key, or IP address as the rate limit key.

• Use multiple granularities: Per-second limits protect against bursts; per-minute or per-hour limits enforce usage quotas. Many production APIs enforce both simultaneously.

• Log throttled requests: Don't silently discard them. Throttling events are valuable signals for capacity planning and for diagnosing client integration problems.

• Plan for distributed deployments: An in-memory rate limiter only works on a single instance. For multi-node deployments, synchronize counters using a shared store like Redis so limits are enforced consistently across all nodes.

• Start permissive, tighten gradually: It is much easier to lower limits after clients are integrated than to raise them once they've built assumptions around the current values. Start generous and adjust based on observed behaviour.

Found this helpful? Share it with a colleague who's struggling with system overload and performance issues. Got questions? We'd love to hear from you at [email protected]

We will see how we can refactor using the Extract Class technique to organize temporary fields into dedicated classes.

Clean Code Reference

❝

⚠️ Code Smell: Temporary Field
✅ Refactoring: Extract Class
🎯 Goal: Clear class interfaces and better field organization

The Temporary Field code smell occurs when instance variables are only used in certain circumstances, making the class interface confusing and the object's state unclear. The Extract Class refactoring technique moves these temporary fields into dedicated classes that better represent their purpose.

The Code Smell: Temporary Field

Temporary Fields are instance variables that are only used in specific methods or under certain conditions, making the class interface confusing. These fields often represent intermediate calculations, temporary state, or data that's only relevant during specific processing stages. This makes the object's state unclear and can lead to bugs when fields contain stale or irrelevant values.

Symptoms

Impact

Fields only used in certain methods

Confusing class interface

Unclear object state

Difficult to understand

Fields initialized to null or zero

Higher bug risk

Here's a typical example of Temporary Field:

public class OrderProcessor {
    // Core order fields
    private String orderId;
    private Customer customer;
    private List<OrderItem> items;
    private double totalAmount;

    // Temporary fields - only used during discount calculation
    private String appliedDiscountCode;
    private double discountAmount;

    // Temporary fields - only used during payment
    private boolean paymentProcessed;
    private String transactionId;

    // Temporary fields - only used during shipment
    private String shippingAddress;
    private String trackingNumber;

    public OrderProcessor(String orderId, Customer customer, List<OrderItem> items) {
        this.orderId = orderId;
        this.customer = customer;
        this.items = items;
        this.totalAmount = calculateBaseTotal();

        // Initialize temporary fields to default values
        this.appliedDiscountCode = null;
        this.discountAmount = 0.0;
        this.paymentProcessed = false;
        this.transactionId = null;
        this.shippingAddress = null;
        this.trackingNumber = null;
    }

    public double applyDiscount(String discountCode) {
        this.appliedDiscountCode = discountCode;
        this.discountAmount = calculateDiscount(discountCode);
        return this.totalAmount - this.discountAmount;
    }

    public boolean processPayment(String paymentMethod) {
        PaymentResult result = paymentGateway.charge(paymentMethod, totalAmount);
        this.paymentProcessed = result.isSuccess();
        this.transactionId = result.getTransactionId();
        return this.paymentProcessed;
    }

    public void prepareShipment(String shippingAddress) {
        this.shippingAddress = shippingAddress;
        this.trackingNumber = "TRK" + orderId;
    }

    private double calculateDiscount(String discountCode) {
        if (discountCode == null) return 0.0;
        switch (discountCode) {
            case "SAVE10": return totalAmount * 0.10;
            case "SAVE20": return totalAmount * 0.20;
            default: return 0.0;
        }
    }

    private double calculateBaseTotal() {
        return items.stream()
                .mapToDouble(item -> item.getPrice() * item.getQuantity())
                .sum();
    }

}

In this example, OrderProcessor has three groups of temporary fields: discount fields (appliedDiscountCode, discountAmount), payment fields (paymentProcessed, transactionId), and shipment fields (shippingAddress, trackingNumber). These fields are only relevant during specific processing stages, yet they clutter the class interface throughout the object's lifetime.

The Refactoring: Extract Class

The Extract Class refactoring technique moves temporary fields into dedicated classes that better represent their purpose and usage context. This makes the main class interface cleaner and the object's state more predictable.

By creating dedicated classes for discount information, payment details, and shipment data, we transform temporary state into well-defined objects that only exist when relevant.

Step by Step Refactoring Process:

1. Identify temporary fields that are only used in specific contexts.

2. Group related temporary fields that are used together.

3. Create new classes to represent these contexts.

4. Move temporary fields into the appropriate classes.

5. Update methods to work with the new classes.

Here's the refactored version:

The temporary fields have been organized into dedicated classes:

1. OrderProcessor - Refactored main class

2. DiscountInfo - Extracted discount data

3. PaymentInfo - Extracted payment data

4. ShipmentInfo - Extracted shipment data

OrderProcessor - Refactored Main Class

public class OrderProcessor {
    private final String orderId;
    private final Customer customer;
    private final List<OrderItem> items;
    private final double totalAmount;

    private DiscountInfo discountInfo;
    private PaymentInfo paymentInfo;
    private ShipmentInfo shipmentInfo;

    public OrderProcessor(String orderId, Customer customer, List<OrderItem> items) {
        this.orderId = orderId;
        this.customer = customer;
        this.items = items;
        this.totalAmount = calculateBaseTotal();
    }

    public double applyDiscount(String discountCode) {
        this.discountInfo = new DiscountInfo(discountCode, totalAmount);
        return totalAmount - discountInfo.getAmount();
    }

    public boolean processPayment(String paymentMethod) {
        PaymentResult result = paymentGateway.charge(paymentMethod, totalAmount);
        this.paymentInfo = new PaymentInfo(paymentMethod, result);
        return paymentInfo.isProcessed();
    }

    public void prepareShipment(String shippingAddress) {
        this.shipmentInfo = new ShipmentInfo(orderId, shippingAddress);
    }

    private double calculateBaseTotal() {
        return items.stream()
                .mapToDouble(item -> item.getPrice() * item.getQuantity())
                .sum();
    }

}

DiscountInfo - Extracted Discount Data

public class DiscountInfo {
    private final String code;
    private final double amount;

    public DiscountInfo(String code, double orderTotal) {
        this.code = code;
        this.amount = calculateDiscount(code, orderTotal);
    }

    private double calculateDiscount(String code, double orderTotal) {
        if (code == null) return 0.0;
        switch (code) {
            case "SAVE10": return orderTotal * 0.10;
            case "SAVE20": return orderTotal * 0.20;
            default: return 0.0;
        }
    }

    @Override
    public String toString() {
        return String.format("Discount{code='%s', amount=%.2f}", code, amount);
    }
}

PaymentInfo - Extracted Payment Data

public class PaymentInfo {
    private final String method;
    private final boolean processed;
    private final String transactionId;

    public PaymentInfo(String method, PaymentResult result) {
        this.method = method;
        this.processed = result.isSuccess();
        this.transactionId = result.getTransactionId();
    }

    @Override
    public String toString() {
        return String.format("Payment{method='%s', processed=%b, txId='%s'}", method, processed, transactionId);
    }
}

ShipmentInfo - Extracted Shipment Data

public class ShipmentInfo {
    private final String address;
    private final String trackingNumber;

    public ShipmentInfo(String orderId, String address) {
        this.address = address;
        this.trackingNumber = "TRK" + orderId;
    }

    @Override
    public String toString() {
        return String.format("Shipment{address='%s', tracking='%s'}", address, trackingNumber);
    }
}

Usage Example - Putting It All Together

Notice how the refactored version transforms 6 scattered temporary fields into 3 focused objects. The OrderProcessor constructor no longer initializes fields to null or zero, each object is created only when its processing stage begins.

When you access paymentInfo.getTransactionId() or shipmentInfo.getTrackingNumber(), it's immediately clear what processing stage produced that data. Compare this to the original where every field existed at all times, even when irrelevant.

public class OrderProcessingDemo {
    public static void main(String[] args) {
        System.out.println("=== Order Processing System ===\n");

        Customer customer = new Customer("johndoe");
        List<OrderItem> items = List.of(
            new OrderItem("Laptop", 999.99, 1),
            new OrderItem("Mouse", 29.99, 2)
        );

        OrderProcessor processor = new OrderProcessor("ORD-001", customer, items);
        System.out.println("Base total: $" + processor.getTotalAmount());

        double discountedTotal = processor.applyDiscount("SAVE10");
        System.out.println("After discount: $" + discountedTotal);
        System.out.println("Discount applied: " + processor.getDiscountInfo());

        boolean paid = processor.processPayment("CREDIT_CARD");
        System.out.println("\nPayment processed: " + paid);
        System.out.println("Payment details: " + processor.getPaymentInfo());

        processor.prepareShipment("123 Main St, Springfield");
        System.out.println("\nShipment prepared: " + processor.getShipmentInfo());
    }
}

Expected Output:

=== Order Processing System ===

Base total: $1059.97
After discount: $953.97
Discount applied: Discount{code='SAVE10', amount=106.00}

Payment processed: true
Payment details: Payment{method='CREDIT_CARD', processed=true, txId='TXN-789'}

Shipment prepared: Shipment{address='123 Main St, Springfield', tracking='TRKORD-001'}

Benefits of Extract Class for Temporary Fields

Benefit

Description

Clearer Class Interface

The main class interface is cleaner and more focused on its core responsibilities.

Better State Management

Temporary fields are organized into logical groups with clear purposes.

Improved Maintainability

Related functionality is grouped together, making it easier to understand and modify.

When to Apply Extract Class for Temporary Fields

• Instance variables that are only used in specific methods or contexts.

• Fields that are set but not always used, making the object's state unclear.

• Classes with many temporary fields that represent different aspects of processing.

• When the class interface becomes confusing due to too many fields.

• When you find yourself initializing many fields to default values that might not be used.

Apply Extract Class refactoring to one class with temporary fields in your current project today. Start with the class that has the most confusing interface due to temporary fields.

Repository & Resources

Complete Code Examples: Clean Code Repository

Find the complete implementation of Temporary Field refactoring and other clean code techniques in our dedicated repository. Each example includes:

• Before and after code comparisons

• Unit tests demonstrating the improvements

Found this helpful? Share it with a colleague who's struggling with Temporary Fields. Got questions? We'd love to hear from you at [email protected]

This pattern is essential for maintaining data integrity in microservices architectures where services operate independently and cannot participate in traditional distributed transactions. By implementing intelligent compensation mechanisms, you can achieve eventual consistency and handle partial failures gracefully.

This guide walks you through the Compensating Transaction pattern from concept to practical implementation, covering how to structure compensatable steps, manage transaction state, and roll back gracefully when distributed operations fail.

• Understanding the Compensating Transaction Pattern

• Implementing the Compensating Transaction Pattern

• When to Use Compensating Transaction Pattern

• Best Practices

Understanding the Compensating Transaction Pattern

The Compensating Transaction pattern works by pairing each operation in a distributed transaction with a corresponding compensation operation that can reverse its effects. When a transaction fails partway through, the system executes compensation operations for all completed steps.

Core Architecture

Compensating Transaction Pattern Interactions

Key Benefits

• Eventual Consistency: Ensures data consistency across distributed services over time.

• Failure Recovery: Provides mechanisms to handle partial transaction failures.

• Service Independence: Allows services to operate independently without tight coupling.

• Scalability: Enables horizontal scaling without distributed transaction overhead.

• Flexibility: Supports complex business logic and custom compensation strategies.

Implementing the Compensating Transaction Pattern

Let's build a comprehensive compensating transaction system that handles complex distributed operations with proper compensation logic and monitoring.

Implementation Overview

• CompensatingTransaction & TransactionStep: Lightweight data models for tracking transaction state and step status

• CompensatingTransactionManager: Core manager handling transaction lifecycle, step execution, and synchronous compensation

• OrderProcessingService: Practical e-commerce example wiring all three steps together

• Service Classes: Order, Payment, and Inventory service implementations with compensation logic

• Main: A runnable demo showing both the happy path and a failure/rollback scenario

Note on Implementation

This implementation keeps things simple by design: plain HashMap, synchronous compensation, and no external dependencies. For production systems, consider using a persistent store (PostgreSQL, Redis) for transaction state durability so compensation can survive restarts, and frameworks like Axon Framework or Apache Camel for complex multi-service workflows.

Transaction and Step Classes

/** Tracks the state and steps of a single distributed transaction */
public class CompensatingTransaction {
    private final String id;
    private final List<TransactionStep> steps = new ArrayList<>();
    private String status = "ACTIVE"; // ACTIVE → COMPLETED or COMPENSATED

    public CompensatingTransaction(String id) {
        this.id = id;
    }

    public void addStep(TransactionStep step) {
        steps.add(step);
    }

    /** Returns only the steps that completed successfully — these need to be undone */
    public List<TransactionStep> getCompletedSteps() {
        List<TransactionStep> completed = new ArrayList<>();
        for (TransactionStep step : steps) {
            if (step.isCompleted()) completed.add(step);
        }
        return completed;
    }

    public void markCompleted()   { status = "COMPLETED"; }
    public void markCompensated() { status = "COMPENSATED"; }

    public String getId()     { return id; }
    public String getStatus() { return status; }
}

/**
 * Represents a single step in a distributed transaction.
 * Each step must define:
 *   execute()    — what to do when things go right
 *   compensate() — how to undo it when things go wrong
 */
public abstract class TransactionStep {
    private final String name;
    private boolean completed = false;

    public TransactionStep(String name) {
        this.name = name;
    }

    /** Perform the step. Return true if successful, false otherwise. */
    public abstract boolean execute() throws Exception;

    /** Undo the effects of this step. Called during compensation. */
    public abstract void compensate() throws Exception;

    public void markCompleted()  { this.completed = true; }
    public boolean isCompleted() { return completed; }
    public String getName()      { return name; }
}

Core Transaction Manager

public class CompensatingTransactionManager {
    // Stores active transactions keyed by their ID
    private final Map<String, CompensatingTransaction> transactions = new HashMap<>();
    private int nextId = 1;

    /** Start a new transaction and return its unique ID */
    public String startTransaction() {
        String id = "txn-" + nextId++;
        transactions.put(id, new CompensatingTransaction(id));
        System.out.println("Started transaction: " + id);
        return id;
    }

    /**
     * Execute a step within the transaction.
     * If the step fails, all previously completed steps are automatically undone.
     */
    public boolean executeStep(String transactionId, TransactionStep step) {
        CompensatingTransaction txn = findTransaction(transactionId);
        txn.addStep(step);

        try {
            boolean success = step.execute();
            if (success) {
                step.markCompleted();
                System.out.println("  ✓ " + step.getName());
                return true;
            } else {
                System.out.println("  ✗ " + step.getName() + " failed — starting compensation");
                compensate(transactionId);
                return false;
            }
        } catch (Exception e) {
            System.out.println("  ✗ " + step.getName() + " threw: " + e.getMessage());
            compensate(transactionId);
            return false;
        }
    }

    /** Mark the transaction as successfully completed */
    public void completeTransaction(String transactionId) {
        findTransaction(transactionId).markCompleted();
        transactions.remove(transactionId);
        System.out.println("Transaction completed: " + transactionId);
    }

    /**
     * Undo all completed steps in reverse order.
     * Reverse order is critical — it ensures each step is undone
     * in a way that respects dependencies between operations.
     */
    public void compensate(String transactionId) {
        CompensatingTransaction txn = findTransaction(transactionId);
        System.out.println("Compensating transaction: " + transactionId);

        List<TransactionStep> toUndo = txn.getCompletedSteps();
        Collections.reverse(toUndo); // Undo last step first

        for (TransactionStep step : toUndo) {
            try {
                step.compensate();
                System.out.println("  ↩ Undid: " + step.getName());
            } catch (Exception e) {
                // Log and continue — compensation must be best-effort
                System.err.println("  ✗ Could not undo " + step.getName() + ": " + e.getMessage());
            }
        }

        txn.markCompensated();
        transactions.remove(transactionId);
        System.out.println("Transaction rolled back: " + transactionId);
    }

    private CompensatingTransaction findTransaction(String id) {
        CompensatingTransaction txn = transactions.get(id);
        if (txn == null) throw new IllegalArgumentException("Transaction not found: " + id);
        return txn;
    }
}

Practical Implementation: E-commerce Order Processing

public class OrderProcessingService {
    private final CompensatingTransactionManager txnManager;
    private final OrderService orderService;
    private final PaymentService paymentService;
    private final InventoryService inventoryService;

    public OrderProcessingService(CompensatingTransactionManager txnManager,
                                  OrderService orderService, PaymentService paymentService,
                                  InventoryService inventoryService) {
        this.txnManager = txnManager;
        this.orderService = orderService;
        this.paymentService = paymentService;
        this.inventoryService = inventoryService;
    }

    public String processOrder(OrderRequest request) {
        String txnId = txnManager.startTransaction();

        // Each step is tried in sequence.
        // If any step fails, the manager automatically rolls back all previous steps.
        CreateOrderStep createStep = new CreateOrderStep(orderService, request);
        if (!txnManager.executeStep(txnId, createStep)) {
            return "Order failed — all changes have been rolled back";
        }

        ProcessPaymentStep paymentStep = new ProcessPaymentStep(paymentService, createStep.getOrderId(), request.getAmount());
        if (!txnManager.executeStep(txnId, paymentStep)) {
            return "Order failed — all changes have been rolled back";
        }

        ReserveInventoryStep inventoryStep = new ReserveInventoryStep(inventoryService, createStep.getOrderId(), request.getItems());
        if (!txnManager.executeStep(txnId, inventoryStep)) {
            return "Order failed — all changes have been rolled back";
        }

        txnManager.completeTransaction(txnId);
        return createStep.getOrderId();
    }
}

// Step 1: Create the order record
public class CreateOrderStep extends TransactionStep {
    private final OrderService orderService;
    private final OrderRequest request;
    private String orderId; // Saved so compensation knows what to cancel

    public CreateOrderStep(OrderService orderService, OrderRequest request) {
        super("Create Order");
        this.orderService = orderService;
        this.request = request;
    }

    @Override
    public boolean execute() {
        orderId = orderService.createOrder(request);
        return orderId != null;
    }

    @Override
    public void compensate() {
        // Undo: cancel the order we just created
        if (orderId != null) orderService.cancelOrder(orderId);
    }

    public String getOrderId() { return orderId; }
}

// Step 2: Charge the customer
public class ProcessPaymentStep extends TransactionStep {
    private final PaymentService paymentService;
    private final String orderId;
    private final double amount;
    private String paymentId; // Saved so compensation knows what to refund

    public ProcessPaymentStep(PaymentService paymentService, String orderId, double amount) {
        super("Process Payment");
        this.paymentService = paymentService;
        this.orderId = orderId;
        this.amount = amount;
    }

    @Override
    public boolean execute() {
        paymentId = paymentService.processPayment(orderId, amount);
        return paymentId != null;
    }

    @Override
    public void compensate() {
        // Undo: refund the payment
        if (paymentId != null) paymentService.refundPayment(paymentId);
    }
}

// Step 3: Reserve stock
public class ReserveInventoryStep extends TransactionStep {
    private final InventoryService inventoryService;
    private final String orderId;
    private final List<OrderItem> items;
    private List<String> reservationIds; // Saved so we know what to release

    public ReserveInventoryStep(InventoryService inventoryService, String orderId, List<OrderItem> items) {
        super("Reserve Inventory");
        this.inventoryService = inventoryService;
        this.orderId = orderId;
        this.items = items;
    }

    @Override
    public boolean execute() {
        reservationIds = inventoryService.reserveItems(orderId, items);
        return reservationIds != null && !reservationIds.isEmpty();
    }

    @Override
    public void compensate() {
        // Undo: release the reserved stock
        if (reservationIds != null) inventoryService.releaseReservations(reservationIds);
    }
}

Supporting Service Classes

/** Manages order records */
public class OrderService {
    private final Map<String, String> orders = new HashMap<>(); // orderId → status

    public String createOrder(OrderRequest request) {
        String orderId = "order-" + System.currentTimeMillis();
        orders.put(orderId, "CREATED");
        System.out.println("    Created order: " + orderId);
        return orderId;
    }

    public void cancelOrder(String orderId) {
        orders.put(orderId, "CANCELLED");
        System.out.println("    Cancelled order: " + orderId);
    }
}

/** Handles payment processing */
public class PaymentService {
    private final Map<String, String> payments = new HashMap<>(); // paymentId → status

    public String processPayment(String orderId, double amount) {
        String paymentId = "pay-" + System.currentTimeMillis();
        payments.put(paymentId, "CHARGED");
        System.out.println("    Charged $" + amount + " for order: " + orderId);
        return paymentId;
    }

    public void refundPayment(String paymentId) {
        payments.put(paymentId, "REFUNDED");
        System.out.println("    Refunded payment: " + paymentId);
    }
}

/** Manages inventory reservations */
public class InventoryService {
    private final Map<String, String> reservations = new HashMap<>();

    public List<String> reserveItems(String orderId, List<OrderItem> items) {
        List<String> ids = new ArrayList<>();
        for (OrderItem item : items) {
            String resId = "res-" + item.getProductId();
            reservations.put(resId, "RESERVED");
            ids.add(resId);
        }
        System.out.println("    Reserved " + items.size() + " item(s) for order: " + orderId);
        return ids;
    }

    public void releaseReservations(List<String> reservationIds) {
        for (String id : reservationIds) reservations.put(id, "RELEASED");
        System.out.println("    Released reservations: " + reservationIds);
    }
}

Data Classes

// Simple data container for an order request
public class OrderRequest {
    private final String customerId;
    private final List<OrderItem> items;
    private final double amount;

    public OrderRequest(String customerId, List<OrderItem> items, double amount) {
        this.customerId = customerId;
        this.items = items;
        this.amount = amount;
    }

    public String getCustomerId()    { return customerId; }
    public List<OrderItem> getItems(){ return items; }
    public double getAmount()        { return amount; }
}

// Represents a single product in an order
public class OrderItem {
    private final String productId;
    private final int quantity;

    public OrderItem(String productId, int quantity) {
        this.productId = productId;
        this.quantity = quantity;
    }

    public String getProductId() { return productId; }
    public int getQuantity()     { return quantity; }
}

Putting It All Together

public class Main {
    public static void main(String[] args) {
        CompensatingTransactionManager txnManager = new CompensatingTransactionManager();
        OrderProcessingService service = new OrderProcessingService(
            txnManager,
            new OrderService(),
            new PaymentService(),
            new InventoryService()
        );

        // Happy path — all steps succeed
        System.out.println("=== Successful order ===");
        OrderRequest request = new OrderRequest(
            "customer-1", List.of(new OrderItem("product-A", 2)), 49.99
        );
        System.out.println("Result: " + service.processOrder(request));

        System.out.println();

        // Failure path — payment returns null (simulating a failed charge)
        System.out.println("=== Failed payment scenario ===");
        PaymentService failingPayments = new PaymentService() {
            @Override
            public String processPayment(String orderId, double amount) {
                System.out.println("    Payment declined!");
                return null; // Returning null signals failure to the step
            }
        };
        OrderProcessingService serviceWithFailure = new OrderProcessingService(
            new CompensatingTransactionManager(),
            new OrderService(), failingPayments,
            new InventoryService()
        );
        System.out.println("Result: " + serviceWithFailure.processOrder(request));
    }
}

Example Output

=== Successful order ===
Started transaction: txn-1
  ✓ Create Order
  ✓ Process Payment
  ✓ Reserve Inventory
Transaction completed: txn-1
Result: order-1234567890

=== Failed payment scenario ===
Started transaction: txn-1
  ✓ Create Order
    Payment declined!
  ✗ Process Payment failed — starting compensation
Compensating transaction: txn-1
  ↩ Undid: Create Order
Transaction rolled back: txn-1
Result: Order failed — all changes have been rolled back

When Compensation Itself Fails

Compensation can also fail: a refund API times out, a service is down. When that happens, the system is in an inconsistent state that can't be resolved automatically. Here's how to handle it:

• Retry with backoff: Most failures are transient. Retrying the compensation (with a short delay between attempts) resolves the majority of cases. This is why compensation operations must be idempotent: retrying a refund should never charge twice.

• Log to a failed-compensation store: Persist the details of every failed compensation. A background job can pick these up and retry them later, even across restarts.

• Alert a human: If retries are exhausted, escalate. At that point it requires manual intervention. Someone reviews the logs and resolves the inconsistency directly.

There is no fully automated solution for every scenario. Compensation is best-effort: the goal is to resolve failures automatically in most cases, with a clear escalation path for the rest.

When to Use Compensating Transaction Pattern

Understanding when to apply the Compensating Transaction pattern is crucial for making the right architectural decisions. Here's when it shines and when alternatives might be better:

✅ Ideal Scenarios:

• Your system performs multi-step distributed operations that span multiple independent services.

• You need eventual consistency across service boundaries without traditional ACID transactions.

• Business operations are logically reversible (refunds, cancellations, inventory releases).

• You're building event-driven or microservices architectures where tight coupling is undesirable.

• Partial transaction failures require clean, auditable rollback mechanisms.

• You need to maintain transaction history for compliance or debugging purposes.

❌ Skip It When:

• Strong ACID consistency is required: use traditional database transactions instead.

• Operations are not logically reversible or meaningful compensation cannot be defined.

• Your system is a monolith where local transactions within a single database suffice.

• The added complexity of compensation logic outweighs the consistency benefits.

• All operations happen within a single service or database boundary.

• Real-time consistency is critical and eventual consistency is unacceptable.

Best Practices

Make compensation idempotent: Retrying a failed compensation must produce the same result.

Persist transaction state: In memory storage won't survive a crash during compensation. Use PostgreSQL or Redis.

Compensate in reverse order: Undo steps in reverse to respect business logic dependencies during rollback.

Alert on compensation failures: Log and surface failed compensations immediately as they require human intervention.

Set transaction timeouts: Long running incomplete transactions should automatically trigger compensation.

Monitor compensation rates: Rising compensation frequency signals upstream reliability issues worth investigating.

Found this helpful? Share it with a colleague who's struggling with distributed transaction management in their microservices architecture. Got questions? We'd love to hear from you at [email protected]

Picture this: You're building a diagramming tool. Users can add shapes, reposition them, and rename the canvas. Simple enough. Then they ask for the one feature every editor needs: the ability to undo changes.

Your first instinct is to store a copy of the previous state directly on the canvas class. Then users want multiple undo steps, so you replace that single reference with a list. Then they want redo. The DiagramCanvas, which should only know about shapes and titles, is now managing its own edit history:

public class DiagramCanvas {
    private String title;
    private List<String> shapes;

    private DiagramCanvas previousState;

    public DiagramCanvas snapshot() {
        DiagramCanvas copy = new DiagramCanvas(title);
        copy.shapes = new ArrayList<>(this.shapes);
        return copy;
    }

    public void addShape(String shape) {
        this.previousState = this.snapshot();
        shapes.add(shape);
    }

    public void undo() {
        if (previousState == null) return;
        this.shapes = previousState.shapes;
        this.title = previousState.title;
        this.previousState = null;
    }
}

Every new canvas property means updating the copy and restore logic. Redo needs yet another reference. The class has become its own historian, violating Single Responsibility and making it fragile to extend.

The Memento pattern solves this by externalizing state snapshots into dedicated objects, keeping the originator clean while giving you unlimited undo/redo history.

Understanding the Memento Pattern

The Memento pattern captures an object's internal state at a point in time and stores it externally, so the object can be restored to that state later, without exposing its internal structure.

Think of it like a word processor's version history: before you make a big edit, the app quietly snapshots your document. If you don't like the result, you restore the snapshot. The document knows how to create and apply snapshots; the version history manager just holds onto them.

This pattern promotes Single Responsibility, Encapsulation, and Separation of Concerns by keeping history management out of the originator.

Memento Pattern Components

Core Components

• Memento: A snapshot of the originator's state at a specific point in time, immutable and opaque to everyone except the originator.

• Originator: The object whose state needs to be saved; creates mementos and uses them to restore its own state.

• Caretaker: Manages the history of mementos (undo/redo stacks) without inspecting their contents.

Complete Java Implementation

Let's build a diagram editor that demonstrates the Memento pattern's power in managing state history without polluting the core canvas object.

Memento

class CanvasSnapshot {
    private final String title;
    private final List<String> shapes;

    CanvasSnapshot(String title, List<String> shapes) {
        this.title = title;
        this.shapes = List.copyOf(shapes);
    }

    String getTitle() { return title; }
    List<String> getShapes() { return shapes; }
}

Originator

public class DiagramCanvas {
    private String title;
    private List<String> shapes;

    public DiagramCanvas(String title) {
        this.title = title;
        this.shapes = new ArrayList<>();
    }

    public void addShape(String shape) {
        shapes.add(shape);
    }

    public CanvasSnapshot save() {
        return new CanvasSnapshot(title, shapes);
    }

    public void restore(CanvasSnapshot snapshot) {
        this.title = snapshot.getTitle();
        this.shapes = new ArrayList<>(snapshot.getShapes());
    }

    public void print() {
        System.out.println("  Title  : " + title);
        System.out.println("  Shapes : " + (shapes.isEmpty() ? "(none)" : String.join(", ", shapes)));
    }
}

Caretaker

public class CanvasHistory {
    private Deque<CanvasSnapshot> undoStack = new ArrayDeque<>();
    private Deque<CanvasSnapshot> redoStack = new ArrayDeque<>();

    public void save(DiagramCanvas canvas) {
        undoStack.push(canvas.save());
        redoStack.clear();
        System.out.println("[History] Saved. Undo steps available: " + undoStack.size());
    }

    public void undo(DiagramCanvas canvas) {
        if (undoStack.isEmpty()) {
            System.out.println("[History] Nothing to undo.");
            return;
        }
        redoStack.push(canvas.save());
        canvas.restore(undoStack.pop());
        System.out.println("[History] Undo applied.");
    }

    public void redo(DiagramCanvas canvas) {
        if (redoStack.isEmpty()) {
            System.out.println("[History] Nothing to redo.");
            return;
        }
        undoStack.push(canvas.save());
        canvas.restore(redoStack.pop());
        System.out.println("[History] Redo applied.");
    }
}

Client

public class DiagramEditorDemo {
    public static void main(String[] args) {
        System.out.println("=== Diagram Editor ===\n");

        DiagramCanvas canvas = new DiagramCanvas("Untitled Diagram");
        CanvasHistory history = new CanvasHistory();

        System.out.println("-- Initial canvas --");
        canvas.print();

        System.out.println("\n-- Adding a rectangle --");
        history.save(canvas);
        canvas.addShape("Rectangle: (10, 20, 100x50)");
        canvas.print();

        System.out.println("\n-- Adding a circle --");
        history.save(canvas);
        canvas.addShape("Circle: (150, 30, r=40)");
        canvas.print();

        System.out.println("\n-- Undo --");
        history.undo(canvas);
        canvas.print();

        System.out.println("\n-- Redo --");
        history.redo(canvas);
        canvas.print();
    }
}

Expected Output:

=== Diagram Editor ===

-- Initial canvas --
  Title  : Untitled Diagram
  Shapes : (none)

-- Adding a rectangle --
[History] Saved. Undo steps available: 1
  Title  : Untitled Diagram
  Shapes : Rectangle: (10, 20, 100x50)

-- Adding a circle --
[History] Saved. Undo steps available: 2
  Title  : Untitled Diagram
  Shapes : Rectangle: (10, 20, 100x50), Circle: (150, 30, r=40)

-- Undo --
[History] Undo applied.
  Title  : Untitled Diagram
  Shapes : Rectangle: (10, 20, 100x50)

-- Redo --
[History] Redo applied.
  Title  : Untitled Diagram
  Shapes : Rectangle: (10, 20, 100x50), Circle: (150, 30, r=40)

🚀 Get the Complete Implementation

The full code with incremental saves and versioned snapshot support is available in our Design Patterns Repository.

# Clone and run the complete demo
git clone https://github.com/shift-elevate/design-patterns.git
cd design-patterns
mvn test -Dtest=DiagramEditorMementoTest

Real World Examples

The Memento pattern is used extensively in applications that require state history management:

1. Text Editors and IDEs

Every modern editor uses the Memento pattern under the hood for undo/redo. Each keystroke or save point creates a memento of the buffer's state. The editor's history manager (caretaker) maintains stacks for undo and redo, and the document (originator) knows how to serialize and restore its own state without the history manager ever needing to inspect it.

2. Database Transaction Rollback

Database engines use memento-like mechanisms to implement transaction rollback. Before executing a transaction, the engine captures the affected pages or row states as a memento (the transaction log). If the transaction fails or is explicitly rolled back, the engine restores the pre-transaction state from the log, without the transaction itself knowing how the snapshot is stored.

When to Use the Memento Pattern

Understanding when to apply the Memento pattern is crucial for making the right architectural decisions. Here's when it shines and when alternatives might be better:

✅ Ideal Scenarios:

• You need to implement undo/redo functionality.

• You want to create snapshots or save points without exposing an object's internals.

• A direct interface to an object's state would expose implementation details.

• The cost of state snapshots is acceptable relative to the benefit of history management.

• You want to keep the originator's class focused on its own responsibilities.

❌ Skip It When:

• The object's state is extremely large and snapshotting is too memory-intensive.

• State changes are continuous and fine-grained (e.g., every pixel in a video stream).

• The originator's internal state cannot be meaningfully serialized or copied.

• A simpler command-based history (storing inverse operations) would be more efficient.

Next Steps: Apply the Memento Pattern in Your Project

Ready to implement the Memento pattern in your own projects? Here's a structured approach to get you started:

1. Identify State to Capture: Find the fields in your originator that define its meaningful state, the ones users would want to undo.

2. Create the Memento Class: Snapshot those fields immutably. Defensive copy any mutable collections.

3. Add Save/Restore to the Originator: Implement save() to produce a memento and restore() to apply one, keeping all other logic out.

4. Build the Caretaker: Use two stacks (undo/redo). Save before each action, clear redo on new actions.

5. Wire the Client: Call history.save(originator) before modifying state, then let users trigger undo and redo through your UI or API.

The Memento pattern cleanly separates what state looks like from who manages its history. Your originator stays focused on its own domain, your caretaker stays focused on history, and your users get the reliable, intuitive undo/redo experience they expect.

Found this helpful? Share it with a colleague who's wrestling with undo/redo or snapshot logic in their application. Got questions? We'd love to hear from you at [email protected]

This pattern is essential for handling variable workloads in cloud applications, where traffic spikes can cause performance degradation or service failures. By implementing intelligent queuing mechanisms, you can create more resilient and predictable systems.

This guide walks you through the Queue-based Load Leveling pattern from concept to practical implementation, covering sample producer and consumer implementations, with best practices and production deployment considerations.

• Understanding the Queue-based Load Leveling Pattern

• Implementing the Queue-based Load Leveling Pattern

• When to Use Queue-based Load Leveling Pattern

• Best Practices

Understanding the Queue-based Load Leveling Pattern

The Queue-based Load Leveling pattern introduces a queue between service producers and consumers to buffer requests and smooth out workload variations. This creates a more predictable processing pattern and prevents downstream services from being overwhelmed.

Core Architecture

Queue Based Leveling Pattern Interactions

Key Benefits

• Load Smoothing: Converts variable workloads into consistent processing patterns.

• Service Protection: Prevents downstream services from being overwhelmed.

• Scalability: Enables independent scaling of producers and consumers.

• Resilience: Provides buffering during service outages or slowdowns.

• Backpressure Management: Controls the rate of processing based on consumer capacity.

Implementing the Queue-based Load Leveling Pattern

Let's build a queue-based load leveling system that demonstrates the core pattern with producers, consumers, and proper message handling.

Implementation Overview

• LoadLevelingQueue: Core bounded queue with capacity limits and basic tracking

• MessageProducer: Enqueues messages with retry support for handling full queues

• MessageConsumer: Processes messages from the queue with configurable threading

• Order Processing Example: Practical demonstration of the pattern

Note on Implementation

This implementation uses Java's BlockingQueue for thread-safe message handling. For production systems, consider using dedicated message brokers like RabbitMQ, Apache Kafka, or cloud services like AWS SQS for durability, persistence, and distributed scaling.

Core Queue Implementation

public class LoadLevelingQueue<T> {
    private final BlockingQueue<T> queue;
    private final String name;
    private final AtomicLong totalMessages = new AtomicLong(0);
    private final AtomicLong rejectedMessages = new AtomicLong(0);

    public LoadLevelingQueue(String name, int capacity) {
        this.name = name;
        this.queue = new ArrayBlockingQueue<>(capacity);
    }

    public boolean enqueue(T message) {
        boolean success = queue.offer(message);
        if (success) {
            totalMessages.incrementAndGet();
        } else {
            rejectedMessages.incrementAndGet();
        }
        return success;
    }

    public T dequeue(long timeout, TimeUnit unit) throws InterruptedException {
        return queue.poll(timeout, unit);
    }

    // Monitoring methods
    public int getCurrentSize() { return queue.size(); }
    public int getRemainingCapacity() { return queue.remainingCapacity(); }
    public long getTotalMessages() { return totalMessages.get(); }
    public long getRejectedMessages() { return rejectedMessages.get(); }
}

Message Producer Implementation

public class MessageProducer<T> {
    private final LoadLevelingQueue<T> queue;

    public MessageProducer(LoadLevelingQueue<T> queue) {
        this.queue = queue;
    }

    public boolean produce(T message) {
        return queue.enqueue(message);
    }

    public boolean produceWithRetry(T message, int maxRetries, long retryDelayMs) {
        for (int attempt = 0; attempt < maxRetries; attempt++) {
            if (produce(message)) {
                return true;
            }

            if (attempt < maxRetries - 1) {
                try {
                    Thread.sleep(retryDelayMs);
                } catch (InterruptedException e) {
                    Thread.currentThread().interrupt();
                    return false;
                }
            }
        }

        // All retries failed - send to dead letter queue or alert
        System.err.println("Failed to enqueue message after " + maxRetries + " retries");
        return false;
    }
}

Message Consumer Implementation

public class MessageConsumer<T> {
    private final LoadLevelingQueue<T> queue;
    private final Function<T, Boolean> messageProcessor;
    private final ExecutorService executorService;
    private final AtomicBoolean running = new AtomicBoolean(false);

    public MessageConsumer(String name, LoadLevelingQueue<T> queue, Function<T, Boolean> processor) {
        this.queue = queue;
        this.messageProcessor = processor;
        this.executorService = Executors.newSingleThreadExecutor(r -> {
            Thread t = new Thread(r, name + "-consumer");
            t.setDaemon(false);
            return t;
        });
    }

    public void start() {
        if (running.compareAndSet(false, true)) {
            executorService.submit(this::consumeMessages);
        }
    }

    public void stop() {
        running.set(false);
        executorService.shutdown();
        try {
            if (!executorService.awaitTermination(60, TimeUnit.SECONDS)) {
                executorService.shutdownNow();
            }
        } catch (InterruptedException e) {
            executorService.shutdownNow();
            Thread.currentThread().interrupt();
        }
    }

    private void consumeMessages() {
        while (running.get()) {
            try {
                T message = queue.dequeue(1, TimeUnit.SECONDS);
                if (message != null) {
                    messageProcessor.apply(message);
                }
            } catch (InterruptedException e) {
                Thread.currentThread().interrupt();
                break;
            } catch (Exception e) {
                System.err.println("Error processing message: " + e.getMessage());
            }
        }
    }
}

Practical Example: Order Processing System

public class OrderProcessingSystem {
    private final LoadLevelingQueue<Order> orderQueue;
    private final MessageProducer<Order> orderProducer;
    private final List<MessageConsumer<Order>> orderConsumers;

    public OrderProcessingSystem(int queueCapacity, int consumerCount) {
        this.orderQueue = new LoadLevelingQueue<>("order-queue", queueCapacity);
        this.orderProducer = new MessageProducer<>(orderQueue);
        this.orderConsumers = new ArrayList<>();

        for (int i = 0; i < consumerCount; i++) {
            MessageConsumer<Order> consumer = new MessageConsumer<>(
                "order-consumer-" + i,
                orderQueue,
                this::processOrder
            );
            orderConsumers.add(consumer);
        }
    }

    public void start() {
        for (MessageConsumer<Order> consumer : orderConsumers) {
            consumer.start();
        }
    }

    public void stop() {
        for (MessageConsumer<Order> consumer : orderConsumers) {
            consumer.stop();
        }
    }

    public boolean submitOrder(Order order) {
        return orderProducer.produce(order);
    }

    private boolean processOrder(Order order) {
        try {
            // Simulate order processing (100-300ms)
            Thread.sleep(100 + (long)(Math.random() * 200));
            System.out.println("Processed order " + order.getId() + " for customer " + order.getCustomerId());
            return true;
        } catch (Exception e) {
            System.err.println("Failed to process order: " + e.getMessage());
            return false;
        }
    }
}

// Supporting classes
record Order(String id, String customerId, double totalAmount) {}

Putting It All Together

public class Main {
    public static void main(String[] args) throws InterruptedException {
        // Create system with queue capacity of 100 and 3 consumers
        OrderProcessingSystem system = new OrderProcessingSystem(100, 3);
        system.start();

        // Simulate variable workload - 50 orders arriving quickly
        System.out.println("Submitting 50 orders in burst...");
        for (int i = 1; i <= 50; i++) {
            boolean accepted = system.submitOrder(new Order("ORDER-" + i, "CUST-" + i, 99.99));
            System.out.println("Order " + i + " submitted: " + (accepted ? "accepted" : "rejected"));
        }

        // Let consumers process
        Thread.sleep(5000);
        system.stop();
    }
}

Example Output

Submitting 50 orders in burst...
Order 1 submitted: accepted
Order 2 submitted: accepted
...
Order 50 submitted: accepted
Processed order ORDER-1 for customer CUST-1
Processed order ORDER-2 for customer CUST-2
Processed order ORDER-3 for customer CUST-3
Processed order ORDER-5 for customer CUST-5
Processed order ORDER-4 for customer CUST-4
...

When to Use Queue-based Load Leveling Pattern

Understanding when to apply the Queue-based Load Leveling pattern is crucial for making the right architectural decisions. Here's when it shines and when alternatives might be better:

✅ Ideal Scenarios:

• Your system experiences unpredictable traffic spikes that overwhelm downstream services.

• You need to decouple producers from consumers for independent scaling.

• You want to protect backend services from being overwhelmed during peak loads.

• You need to maintain system responsiveness even when processing capacity is limited.

• You're building event-driven architectures with variable workloads.

• You want to absorb temporary failures by buffering requests until services recover.

❌ Skip It When:

• Your workloads are consistent and predictable with no spikes.

• Real-time processing is required with zero latency tolerance.

• Message ordering is critical and cannot be compromised.

• The added complexity of queue management outweighs the benefits.

• Your system has sufficient capacity to handle peak loads directly.

• You need synchronous request-response patterns (use Circuit Breaker instead).

Best Practices

Size Your Queue Appropriately: Balance memory usage against buffering needs. Too small causes message rejection during spikes; too large wastes resources and increases latency.

Implement Dead Letter Queues: Handle messages that repeatedly fail processing. Don't lose critical data—route failed messages to a separate queue for investigation.

Monitor Queue Depth: Track queue size as a key health indicator. Growing queues signal that consumers can't keep up with producers—a capacity planning signal.

Use Backpressure Signals: When queues fill up, signal producers to slow down rather than silently dropping messages. Return meaningful errors to callers.

Plan for Consumer Scaling: Design consumers to scale horizontally based on queue depth. Consider auto-scaling rules that add consumers when queue depth exceeds thresholds.

Handle Message Ordering: If ordering matters, use partitioned queues or single consumers per partition. Parallel consumers can process messages out of order.

Found this helpful? Share it with a colleague who's struggling with variable workloads in their distributed systems. Got questions? We'd love to hear from you at [email protected]

Picture this: You're building an expense management system for a growing company. Your initial approach seems logical: create a method that checks the expense amount and routes it to the appropriate approver based on predefined thresholds.

Then the organization evolves. The finance team wants to add department-specific approval rules. HR needs special handling for training expenses. The CEO wants certain categories to skip levels. Your approval method becomes a tangled mess of nested conditions that breaks every time the org chart changes.

Suddenly, you're dealing with code like this:

public ApprovalResult approveExpense(Expense expense) {
    if (expense.getAmount() <= 500) {
        return teamLead.approve(expense);
    } else if (expense.getAmount() <= 2000) {
        if (expense.getCategory().equals("TRAINING")) {
            return hrManager.approve(expense);
        }
        return manager.approve(expense);
    } else if (expense.getAmount() <= 10000) {
        if (expense.getDepartment().equals("ENGINEERING")) {
            return vpEngineering.approve(expense);
        }
        return director.approve(expense);
    }
    // ... endless conditions and special cases
}

Sound familiar? The Chain of Responsibility pattern solves this challenge by letting you pass requests along a chain of handlers, where each handler decides whether to process the request or pass it to the next handler in the chain.

Understanding the Chain of Responsibility Pattern

The Chain of Responsibility pattern decouples senders of requests from their receivers by giving multiple objects a chance to handle the request. The request passes along a chain until an object handles it, enabling dynamic request routing without tight coupling.

Think of it like an expense approval workflow in a company: when you submit an expense report, it doesn't go directly to the CEO. Instead, it starts with your team lead. If the amount exceeds their approval limit, they escalate it to the manager, who might escalate it to the director, and so on. Each person in the chain either approves the expense or passes it up the hierarchy.

This pattern promotes Loose Coupling, Single Responsibility, and Open Closed Principle while enabling flexible request handling at runtime.

Chain of Responsibilities Components

Core Components

• Supporting Classes: Request and result objects that carry data through the chain (ExpenseRequest, ApprovalResult)

• Abstract Handler: Defines the interface and implements common chaining logic for all handlers

• Concrete Handlers: Extend the abstract handler with specific approval limits and processing logic

Complete Java Implementation

Let's build an expense approval system that demonstrates the Chain of Responsibility pattern's power in managing hierarchical approval workflows.

Supporting Classes

public class ExpenseRequest {
    private String employeeName;
    private String description;
    private double amount;
    private String category;

    public ExpenseRequest(String employeeName, String description,
                         double amount, String category) {
        this.employeeName = employeeName;
        this.description = description;
        this.amount = amount;
        this.category = category;
    }

    public String getEmployeeName() { return employeeName; }
    public String getDescription() { return description; }
    public double getAmount() { return amount; }
    public String getCategory() { return category; }

    @Override
    public String toString() {
        return String.format("%s - %s ($%.2f) [%s]",
                employeeName, description, amount, category);
    }
}

public class ApprovalResult {
    private boolean approved;
    private String approverRole;
    private String message;

    public ApprovalResult(boolean approved, String approverRole, String message) {
        this.approved = approved;
        this.approverRole = approverRole;
        this.message = message;
    }

    public boolean isApproved() { return approved; }
    public String getApproverRole() { return approverRole; }
    public String getMessage() { return message; }

    @Override
    public String toString() {
        String status = approved ? "Approved" : "Rejected";
        return String.format("%s by %s - %s", status, approverRole, message);
    }
}

Abstract Handler

public abstract class ExpenseApprover {
    protected ExpenseApprover nextApprover;
    protected double approvalLimit;
    protected String role;

    public ExpenseApprover(String role, double approvalLimit) {
        this.role = role;
        this.approvalLimit = approvalLimit;
    }

    public void setNextApprover(ExpenseApprover nextApprover) {
        this.nextApprover = nextApprover;
    }

    public String getApproverRole() {
        return role;
    }

    public ApprovalResult approve(ExpenseRequest request) {
        if (canApprove(request)) {
            return processApproval(request);
        } else if (nextApprover != null) {
            System.out.println(role + " escalating to " + nextApprover.getApproverRole());
            return nextApprover.approve(request);
        } else {
            return new ApprovalResult(false, role, "Exceeds maximum approval authority");
        }
    }

    protected boolean canApprove(ExpenseRequest request) {
        return request.getAmount() <= approvalLimit;
    }

    protected abstract ApprovalResult processApproval(ExpenseRequest request);
}

Concrete Handlers

public class TeamLead extends ExpenseApprover {

    public TeamLead() {
        super("Team Lead", 1000.00);
    }

    @Override
    protected ApprovalResult processApproval(ExpenseRequest request) {
        return new ApprovalResult(true, role, "Routine team expense");
    }
}

public class Manager extends ExpenseApprover {

    public Manager() {
        super("Manager", 5000.00);
    }

    @Override
    protected ApprovalResult processApproval(ExpenseRequest request) {
        return new ApprovalResult(true, role, "Departmental budget");
    }
}

public class Director extends ExpenseApprover {

    public Director() {
        super("Director", Double.MAX_VALUE);
    }

    @Override
    protected ApprovalResult processApproval(ExpenseRequest request) {
        return new ApprovalResult(true, role, "Strategic initiative");
    }
}

Client

public class ExpenseApprovalDemo {
    public static void main(String[] args) {
        System.out.println("=== Expense Approval System ===\n");

        // Build the chain of responsibility
        ExpenseApprover teamLead = new TeamLead();
        ExpenseApprover manager = new Manager();
        ExpenseApprover director = new Director();

        teamLead.setNextApprover(manager);
        manager.setNextApprover(director);

        // Process various expense requests
        ExpenseRequest[] requests = {
            new ExpenseRequest("Alice", "Office supplies", 750.00, "SUPPLIES"),
            new ExpenseRequest("Bob", "Team building event", 2500.00, "ENTERTAINMENT"),
            new ExpenseRequest("Carol", "Conference registration", 4800.00, "TRAINING"),
            new ExpenseRequest("David", "Server infrastructure", 15000.00, "EQUIPMENT")
        };

        for (ExpenseRequest request : requests) {
            System.out.println("Request: " + request);
            ApprovalResult result = teamLead.approve(request);
            System.out.println("Result: " + result);
            System.out.println();
        }
    }
}

Expected Output:

=== Expense Approval System ===

Request: Alice - Office supplies ($750.00) [SUPPLIES]
Result: Approved by Team Lead - Routine team expense

Request: Bob - Team building event ($2500.00) [ENTERTAINMENT]
Team Lead escalating to Manager
Result: Approved by Manager - Departmental budget

Request: Carol - Conference registration ($4800.00) [TRAINING]
Team Lead escalating to Manager
Result: Approved by Manager - Departmental budget

Request: David - Server infrastructure ($15000.00) [EQUIPMENT]
Team Lead escalating to Manager
Manager escalating to Director
Result: Approved by Director - Strategic initiative

🚀 Get the Complete Implementation

The full code with advanced chain configurations and dynamic handler insertion is available in our Design Patterns Repository.

# Clone and run the complete demo
git clone https://github.com/shift-elevate/design-patterns.git
cd design-patterns
mvn test -Dtest=ChainOfResponsibilityPatternTest

Real World Examples

The Chain of Responsibility pattern is extensively used in real-world applications:

1. Servlet Filters and Middleware

Web frameworks use filter chains to process HTTP requests through multiple handlers. Each filter can authenticate, log, compress, or modify the request before passing it to the next filter. This enables modular request processing where new filters can be added without modifying existing ones.

2. Event Handling in UI Frameworks

GUI frameworks use event bubbling where UI events propagate through a hierarchy of components. A button click event first goes to the button, then its container, then the window, until some handler processes it. This allows flexible event handling at any level of the component tree.

3. Logging Frameworks

Logging systems route messages through handler chains based on severity levels. A DEBUG message might go to a file handler, while an ERROR message triggers file logging, email notification, and alerting systems. Each handler decides whether to process the message based on its configured threshold.

When to Use Chain of Responsibility Pattern

Understanding when to apply the Chain of Responsibility pattern is crucial for making the right architectural decisions. Here's when it shines and when alternatives might be better:

✅ Ideal Scenarios:

• Multiple objects may handle a request, and the handler isn't known in advance.

• You want to issue a request to several objects without specifying the receiver explicitly.

• The set of handlers should be specified dynamically at runtime.

• You want to decouple request senders from receivers.

• Requests need to be processed by multiple handlers in sequence.

❌ Skip It When:

• There's always exactly one handler for each request type.

• The handling logic is simple and unlikely to change.

• You need guaranteed request handling (chains can leave requests unhandled).

• Performance is critical and chain traversal overhead is unacceptable.

Next Steps: Apply Chain of Responsibility Pattern in Your Project

Ready to implement the Chain of Responsibility pattern in your own projects? Here's a structured approach to get you started:

1. Identify Request Flow: Look for scenarios where requests pass through multiple processing stages (approvals, validations, transformations).

2. Define Abstract Handler: Create an abstract class with common chaining logic and successor management.

3. Create Concrete Handlers: Extend the abstract handler for each processing step with specific logic.

4. Configure the Chain: Set up the chain order based on your business requirements.

5. Add Fallback Handling: Ensure requests that reach the end of the chain are handled appropriately.

The Chain of Responsibility pattern transforms rigid, tightly-coupled request handling into flexible, extensible processing pipelines. By decoupling senders from receivers and enabling dynamic handler configuration, you build systems that adapt to changing business rules while maintaining clean, testable code.

Found this helpful? Share it with a colleague who's struggling with complex approval workflows or request routing logic. Got questions? We'd love to hear from you at [email protected]

We will see how we can refactor using the Replace Magic String with Named Constant technique for better maintainability and configuration management.

Clean Code Reference

❝

⚠️ Code Smell: Hardcoded Strings
✅ Refactoring: Replace Magic String with Named Constant
🎯 Goal: Centralized string management and better maintainability

The Hardcoded Strings code smell occurs when literal string values are scattered throughout code without clear meaning or context. The Replace Magic String with Named Constant refactoring technique replaces these literals with descriptive constants that make the code more maintainable and easier to configure.

The Code Smell: Hardcoded Strings

Hardcoded Strings are one of the most common code smells that reduce code maintainability and make configuration changes difficult. When literal strings appear throughout code without clear context, they make the code harder to understand, modify, and maintain. These strings often represent configuration values, error messages, or business rules that should be centralized.

Symptoms

Impact

Literal strings without clear meaning

Reduced maintainability

Repeated hardcoded strings throughout code

Difficult to configure

Business rules hidden in strings

Higher bug risk

Here's a typical example of Hardcoded Strings:

public class UserService {

    public void createUser(String username, String email, String role) {
        if (!"ADMIN".equals(role) && !"USER".equals(role) && !"MODERATOR".equals(role)) {
            throw new IllegalArgumentException("Invalid role. Must be ADMIN, USER, or MODERATOR");
        }

        User user = new User();
        user.setUsername(username);
        user.setEmail(email);
        user.setRole(role);
        user.setStatus("ACTIVE");

        userRepository.save(user);
        emailService.sendEmail(email, "Welcome to Our Platform",
            "Welcome " + username + "! Your account has been created.");
    }

    public void updateUserStatus(String username, String newStatus) {
        if (!"ACTIVE".equals(newStatus) && !"INACTIVE".equals(newStatus) && !"SUSPENDED".equals(newStatus)) {
            throw new IllegalArgumentException("Invalid status. Must be ACTIVE, INACTIVE, or SUSPENDED");
        }

        User user = userRepository.findByUsername(username);
        user.setStatus(newStatus);
        userRepository.save(user);

        if ("SUSPENDED".equals(newStatus)) {
            emailService.sendEmail(user.getEmail(), "Account Suspended",
                "Your account has been suspended.");
        }
    }
}
public class UserService {

    public void createUser(String username, String email, String role) {
        if (!"ADMIN".equals(role) && !"USER".equals(role) && !"MODERATOR".equals(role)) {
            throw new IllegalArgumentException("Invalid role. Must be ADMIN, USER, or MODERATOR");
        }

        User user = new User();
        user.setUsername(username);
        user.setEmail(email);
        user.setRole(role);
        user.setStatus("ACTIVE");

        userRepository.save(user);
        emailService.sendEmail(email, "Welcome to Our Platform",
            "Welcome " + username + "! Your account has been created.");
    }

    public void updateUserStatus(String username, String newStatus) {
        if (!"ACTIVE".equals(newStatus) && !"INACTIVE".equals(newStatus) && !"SUSPENDED".equals(newStatus)) {
            throw new IllegalArgumentException("Invalid status. Must be ACTIVE, INACTIVE, or SUSPENDED");
        }

        User user = userRepository.findByUsername(username);
        user.setStatus(newStatus);
        userRepository.save(user);

        if ("SUSPENDED".equals(newStatus)) {
            emailService.sendEmail(user.getEmail(), "Account Suspended",
                "Your account has been suspended.");
        }
    }
}

In this example, hardcoded strings like "ADMIN", "USER", "ACTIVE", "SUSPENDED" are scattered throughout the code. This makes the code hard to maintain and prone to typos.

The Refactoring: Replace Magic String with Named Constant

The Replace Magic String with Named Constant refactoring technique replaces literal strings with descriptive constants that clearly communicate their purpose and meaning. This makes the code more maintainable and easier to configure.

Step by Step Refactoring Process:

1. Identify hardcoded strings in the code that lack clear meaning.

2. Determine the purpose of each hardcoded string (configuration, business rule, etc.).

3. Create descriptive constants with meaningful names.

4. Replace hardcoded strings with the named constants.

5. Group related constants in appropriate classes or enums.

Here's the refactored version:

The scattered hardcoded strings have been organized into meaningful constants and enums:

1. UserService - Refactored with named constants

2. UserRole - Enum for typesafe roles

3. UserStatus - Enum for typesafe statuses

UserService - Refactored with Named Constants

public class UserService {

    private static final String ERROR_INVALID_ROLE = "Invalid role. Must be ADMIN, USER, or MODERATOR";

    public void createUser(String username, String email, String role) {
        if (!UserRole.isValid(role)) {
            throw new IllegalArgumentException(ERROR_INVALID_ROLE);
        }

        User user = new User();
        user.setUsername(username);
        user.setEmail(email);
        user.setRole(role);
        user.setStatus(UserStatus.ACTIVE.getValue());

        userRepository.save(user);
        emailService.sendEmail(email, "Welcome to Our Platform",
            "Welcome " + username + "! Your account has been created.");
    }

    public void updateUserStatus(String username, String newStatus) {
        UserStatus status = UserStatus.fromString(newStatus);

        User user = userRepository.findByUsername(username);
        user.setStatus(status.getValue());
        userRepository.save(user);

        if (status == UserStatus.SUSPENDED) {
            emailService.sendEmail(user.getEmail(), "Account Suspended",
                "Your account has been suspended.");
        }
    }
}

UserRole - Enum for Typesafe Roles

public enum UserRole {
    ADMIN, USER, MODERATOR;

    public String getValue() {
        return name();
    }

    public static boolean isValid(String role) {
        for (UserRole r : values()) {
            if (r.name().equals(role)) return true;
        }
        return false;
    }
}

UserStatus - Enum for Typesafe Statuses

public enum UserStatus {
    ACTIVE, INACTIVE, SUSPENDED;

    public String getValue() {
        return name();
    }

    public static UserStatus fromString(String status) {
        for (UserStatus s : values()) {
            if (s.name().equals(status)) return s;
        }
        throw new IllegalArgumentException("Invalid status: " + status);
    }
}

Usage Example - Putting It All Together

Notice how the refactored version transforms scattered hardcoded strings into centralized enums. UserRole.ADMIN replaces every occurrence of "ADMIN", and UserStatus.ACTIVE replaces every "ACTIVE" string. This eliminates typo risks and makes the code self-documenting.

When you use UserStatus.SUSPENDED instead of "SUSPENDED", it's immediately clear what you're working with. Compare this to the original scattered strings where typos like "SUSPENED" could easily slip through and cause hard-to-debug issues.

public class UserManagementDemo {
    public static void main(String[] args) {
        UserService userService = new UserService();

        // Create a new user with typesafe role
        userService.createUser("johndoe", "[email protected]", UserRole.USER.getValue());

        // Update status using enum
        userService.updateUserStatus("johndoe", UserStatus.SUSPENDED.getValue());
    }
}

Expected Output:

Email sent to [email protected]: Welcome to Our Platform
Email sent to [email protected]: Account Suspended

Benefits of Replace Magic String with Named Constant

Benefit

Description

Improved Maintainability

Constants with descriptive names make the code self-documenting and easier to modify without searching through the entire codebase.

Reduced Typos

Using constants instead of hardcoded strings eliminates the risk of typos and makes the code more reliable.

Centralized Configuration

String values are centralized, making it easier to change configuration values and maintain consistency.

When to Apply Replace Magic String with Named Constant Refactoring

• Literal strings that represent configuration values or business rules.

• Repeated hardcoded strings throughout the codebase.

• Error messages and user-facing text that should be consistent.

• Status values, role names, or other enumerated string values.

• When you want to make string values configurable or easier to maintain.

Apply Replace Magic String with Named Constant refactoring to one set of hardcoded strings in your current project today. Start with the strings that represent the most important business rules or configuration values.

Repository & Resources

Complete Code Examples: Clean Code Repository

Find the complete implementation of Hardcoded Strings refactoring and other clean code techniques in our dedicated repository. Each example includes:

• Before and after code comparisons

• Unit tests demonstrating the improvements

Found this helpful? Share it with a colleague who's struggling with Hardcoded Strings. Got questions? We'd love to hear from you at [email protected]

Picture this: You're building a photo gallery application that displays high-resolution images. Your initial approach seems logical: load all images when the gallery opens so users can browse smoothly.

Then your beta testers start complaining. The app takes forever to load. Users on mobile devices watch their data allowance disappear. Some users experience crashes on older devices. You check the analytics and discover users typically view only a handful of images before leaving, yet you're eagerly loading every single high-resolution image in the entire gallery.

You try to optimize by reducing image quality, but the product team pushes back: "Our users expect crisp, high-quality photos. That's our competitive advantage." You're stuck between loading everything upfront or compromising on quality.

The Proxy pattern solves this by providing a lightweight stand-in for expensive objects, controlling when and how they're actually loaded.

Understanding the Proxy Pattern

The Proxy pattern provides a surrogate or placeholder for another object to control access to it. The proxy acts as an intermediary, presenting the same interface as the real object while adding functionality like lazy loading, access control, caching, or logging.

Think of it like viewing images on a modern photo sharing app: instead of loading every full-resolution image immediately (which would be slow), the app shows lightweight thumbnails first. Only when you tap an image does it load the full resolution version. The thumbnail is a proxy for the real high-resolution image.

This pattern promotes Resource Efficiency, Controlled Access, and Performance Optimization while maintaining the same interface as the real object.

Proxy Pattern Components

Core Components

• Subject Interface: Defines the common interface for both RealSubject and Proxy.

• RealSubject: The real object that the proxy represents (expensive to create/access).

• Proxy: Maintains a reference to RealSubject and controls access to it.

Subject Interface

public interface Image {
    void display();
    void loadFullResolution();
    ImageMetadata getMetadata();
}

Supporting Classes

public class ImageMetadata {
    private String filename;
    private String format;
    private long fileSize;

    public ImageMetadata(String filename, String format, long fileSize) {
        this.filename = filename;
        this.format = format;
        this.fileSize = fileSize;
    }

    public String getFilename() { return filename; }
    public String getFormat() { return format; }
    public long getFileSize() { return fileSize; }

    @Override
    public String toString() {
        return String.format("%s [%s] - %.2f MB",
                filename, format, fileSize / (1024.0 * 1024.0));
    }
}

public class ThumbnailImage {
    private String filename;
    private byte[] thumbnailData;

    public ThumbnailImage(String filename, ImageMetadata metadata) {
        this.filename = filename;
        loadThumbnail();
    }

    private void loadThumbnail() {
        System.out.println("Loading thumbnail for: " + filename);
        this.thumbnailData = new byte[102400];
        System.out.println("Thumbnail loaded: " + filename + " (100 KB)");
    }

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

RealSubject

public class HighResolutionImage implements Image {
    private byte[] imageData;
    private ImageMetadata metadata;
    private boolean isLoaded;

    public HighResolutionImage(ImageMetadata metadata) {
        this.metadata = metadata;
        this.isLoaded = false;
        loadFromDisk();
    }

    private void loadFromDisk() {
        System.out.println("Loading high-resolution image: " + metadata.getFilename());
        long startTime = System.currentTimeMillis();

        try {
            Thread.sleep(2000);
            this.imageData = new byte[(int) metadata.getFileSize()];
            this.isLoaded = true;

            long loadTime = System.currentTimeMillis() - startTime;
            System.out.println(String.format("High-res image loaded: %s (%.2f MB) in %d ms",
                    metadata.getFilename(), metadata.getFileSize() / (1024.0 * 1024.0), loadTime));
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
        }
    }

    @Override
    public void display() {
        if (isLoaded) {
            System.out.println("Displaying high-resolution image: " + metadata.getFilename());
        } else {
            System.out.println("Image not loaded yet: " + metadata.getFilename());
        }
    }

    @Override
    public void loadFullResolution() {
        if (!isLoaded) {
            loadFromDisk();
        }
    }

    @Override
    public ImageMetadata getMetadata() {
        return metadata;
    }
}

Proxy

public class ImageProxy implements Image {
    private HighResolutionImage realImage;
    private ThumbnailImage thumbnail;
    private ImageMetadata metadata;
    private boolean isFullResolutionLoaded;

    public ImageProxy(ImageMetadata metadata) {
        this.metadata = metadata;
        this.isFullResolutionLoaded = false;
        this.thumbnail = new ThumbnailImage(metadata.getFilename(), metadata);
    }

    @Override
    public void display() {
        if (!isFullResolutionLoaded) {
            System.out.println("Displaying thumbnail preview for: " + metadata.getFilename());
            thumbnail.display();
        } else {
            realImage.display();
        }
    }

    @Override
    public void loadFullResolution() {
        if (realImage == null) {
            System.out.println("User requested full resolution for: " + metadata.getFilename());
            realImage = new HighResolutionImage(metadata);
            isFullResolutionLoaded = true;
        } else {
            System.out.println("Full resolution already loaded for: " + metadata.getFilename());
        }
    }

    @Override
    public ImageMetadata getMetadata() {
        return metadata;
    }

    public boolean isFullResolutionLoaded() {
        return isFullResolutionLoaded;
    }
}

Client

public class PhotoGallery {
    private List<Image> images;
    private String galleryName;

    public PhotoGallery(String galleryName) {
        this.galleryName = galleryName;
        this.images = new ArrayList<>();
    }

    public void addImage(Image image) {
        images.add(image);
    }

    public void displayGallery() {
        System.out.println("\n=== " + galleryName + " ===");
        for (int i = 0; i < images.size(); i++) {
            System.out.println("Image " + (i + 1) + ":");
            images.get(i).display();
        }
    }

    public void viewImage(int index) {
        System.out.println("\n=== Viewing Image " + (index + 1) + " ===");
        Image image = images.get(index);
        System.out.println("Metadata: " + image.getMetadata().toString());
        image.loadFullResolution();
        image.display();
    }

    public void showStatistics() {
        int loadedCount = 0;
        for (Image image : images) {
            if (image instanceof ImageProxy && ((ImageProxy) image).isFullResolutionLoaded()) {
                loadedCount++;
            }
        }
        System.out.println("\n=== Statistics ===");
        System.out.println("Total: " + images.size() + " | Loaded: " + loadedCount +
                         " | Memory saved: " + (images.size() - loadedCount) * 100 / images.size() + "%");
    }
}

public class ImageGalleryDemo {
    public static void main(String[] args) {
        System.out.println("=== Photo Gallery with Proxy Pattern ===\n");

        PhotoGallery gallery = new PhotoGallery("Vacation Photos");

        gallery.addImage(new ImageProxy(
                new ImageMetadata("sunset_beach.jpg", "JPEG", 10485760)));
        gallery.addImage(new ImageProxy(
                new ImageMetadata("mountain_peak.jpg", "JPEG", 12582912)));
        gallery.addImage(new ImageProxy(
                new ImageMetadata("city_skyline.jpg", "JPEG", 11534336)));

        System.out.println("\nGallery loaded! Only thumbnails in memory.\n");

        gallery.displayGallery();
        gallery.viewImage(1);
        gallery.viewImage(1);
        gallery.showStatistics();
    }
}

Expected Output:

=== Photo Gallery with Proxy Pattern ===

Loading thumbnail for: sunset_beach.jpg
Thumbnail loaded: sunset_beach.jpg (100 KB)
Loading thumbnail for: mountain_peak.jpg
Thumbnail loaded: mountain_peak.jpg (100 KB)
Loading thumbnail for: city_skyline.jpg
Thumbnail loaded: city_skyline.jpg (100 KB)

Gallery loaded! Only thumbnails in memory.

=== Vacation Photos ===
Image 1:
Displaying thumbnail preview for: sunset_beach.jpg
Displaying thumbnail: sunset_beach.jpg
Image 2:
Displaying thumbnail preview for: mountain_peak.jpg
Displaying thumbnail: mountain_peak.jpg
Image 3:
Displaying thumbnail preview for: city_skyline.jpg
Displaying thumbnail: city_skyline.jpg

=== Viewing Image 2 ===
Metadata: mountain_peak.jpg [JPEG] - 12.00 MB
User requested full resolution for: mountain_peak.jpg
Loading high-resolution image: mountain_peak.jpg
High-res image loaded: mountain_peak.jpg (12.00 MB) in 2001 ms
Displaying high-resolution image: mountain_peak.jpg

=== Viewing Image 2 ===
Metadata: mountain_peak.jpg [JPEG] - 12.00 MB
Full resolution already loaded for: mountain_peak.jpg
Displaying high-resolution image: mountain_peak.jpg

=== Statistics ===
Total: 3 | Loaded: 1 | Memory saved: 66%

🚀 Get the Complete Implementation

The full code with advanced proxy implementations is available in our Design Patterns Repository.

# Clone and run the complete demo
git clone https://github.com/shift-elevate/design-patterns.git
cd design-patterns
mvn test -Dtest=ProxyPatternTest

Real World Examples

The Proxy pattern is extensively used in real world applications:

1. Database Lazy Loading

Object-Relational Mapping frameworks use proxy objects for lazy loading of database entities. When you fetch a parent entity, related child entities are represented by proxy objects that only load from the database when actually accessed, avoiding the N+1 query problem and improving performance.

2. Aspect-Oriented Programming

Modern application frameworks use dynamic proxies to add cross-cutting concerns like transaction management, security, and logging to business objects. The proxy intercepts method calls and adds behavior before or after the actual method execution without modifying the original code.

3. Content Delivery Networks

Content delivery networks act as caching proxies for web content, storing copies of images, videos, and static files closer to users geographically. When a user requests content, the proxy serves the cached version if available, only fetching from the origin server when necessary, dramatically reducing latency and bandwidth costs.

When to Use the Proxy Pattern

Understanding when to apply the Proxy pattern is crucial for making the right architectural decisions. Here's when it shines and when alternatives might be better:

✅ Ideal Scenarios:

• You need to delay expensive object creation until actually needed.

• You want to control access to an object based on permissions.

• You need to represent remote objects locally.

• You want to cache results of expensive operations.

• You need to add reference counting or resource management.

❌ Skip It When:

• The object being proxied is already lightweight and fast to create.

• The added indirection and complexity outweigh the benefits.

• You need direct access to the object's internal state.

• The proxy layer would add unnecessary performance overhead for your use case.

Next Steps: Apply Proxy Pattern in Your Project

Ready to implement the Proxy pattern in your own projects? Here's a structured approach to get you started:

1. Identify Expensive Operations: Look for areas where object creation, resource loading, or method calls are costly in terms of time, memory, or network bandwidth.

2. Define Common Interface: Create an interface that both the real object and proxy will implement.

3. Implement Real Subject: Build the actual implementation with the expensive or protected functionality.

4. Create Proxy Class: Implement a proxy that controls access to the real subject.

5. Add Proxy Logic: Implement lazy loading, caching, access control, or logging as needed.

6. Test Performance Impact: Measure the actual benefits in terms of load time, memory usage, and user experience.

The Proxy pattern transforms resource-intensive applications into efficient, responsive systems. By controlling when and how expensive objects are created and accessed, you build applications that start faster, use less memory, and provide better user experiences while maintaining clean, maintainable code.

Found this helpful? Share it with a colleague who's struggling with slow-loading resources or memory-intensive applications. Got questions? We'd love to hear from you at [email protected]

Picture this: You're building a navigation system for a GPS application that needs to calculate routes using different strategies: fastest route using highways, shortest route by distance, and eco-friendly route for fuel efficiency. Your initial approach seems logical: use conditional logic to select the appropriate calculation method.

Then business requirements evolve. The product team wants to add bicycle routes, avoid tolls, prefer scenic roads, and incorporate real-time traffic patterns. Your route calculation method becomes a massive switch statement that violates the Open Closed Principle and breaks every time you add a new routing strategy.

Suddenly, you're dealing with code like this:

public Route calculateRoute(Location start, Location end, String routeType) {
    if (routeType.equals("FASTEST")) {
        return calculateFastestRoute(start, end);
    } else if (routeType.equals("SHORTEST")) {
        return calculateShortestRoute(start, end);
    } else if (routeType.equals("ECO")) {
        return calculateEcoRoute(start, end);
    } else if (routeType.equals("SCENIC")) {
        // Scenic route logic
    } else if (routeType.equals("BICYCLE")) {
        // Bicycle-friendly route logic
    }
    // ... endless conditions
}

Sound familiar? The Strategy pattern solves this challenge by encapsulating algorithms in separate strategy objects, making them interchangeable at runtime.

Understanding the Strategy Pattern

The Strategy pattern defines a family of algorithms, encapsulates each one, and makes them interchangeable. It lets the algorithm vary independently from clients that use it, enabling runtime algorithm selection.

Think of it like choosing different navigation modes on Google Maps: whether you select the fastest route, avoid highways, or optimize for fuel efficiency, the navigation system remains the same. Each routing method is a different strategy that implements the same interface, but with different internal logic.

This pattern promotes Algorithm Flexibility, Open Closed Principle, and Single Responsibility while enabling dynamic behaviour selection at runtime.

Strategy Pattern Components

Core Components

• Strategy Interface: Defines the common interface for all concrete strategies

• Supporting Classes: Helper classes used by strategies (Location, Route)

• Concrete Strategies: Implement specific algorithms using the strategy interface

• Context Class: Uses a strategy to execute algorithms and can switch strategies at runtime

Complete Java Implementation

Let's build a navigation route planning system that demonstrates the Strategy pattern's power in managing different routing algorithms.

Strategy Interface

public interface RouteStrategy {
    Route calculateRoute(Location start, Location destination);
    String getStrategyName();
}

Supporting Classes

public class Location {
    private String name;
    private double latitude;
    private double longitude;

    public Location(String name, double latitude, double longitude) {
        this.name = name;
        this.latitude = latitude;
        this.longitude = longitude;
    }

    public String getName() { return name; }
    public double getLatitude() { return latitude; }
    public double getLongitude() { return longitude; }

    @Override
    public String toString() {
        return name;
    }
}

public class Route {
    private Location start;
    private Location destination;
    private double distance;
    private int estimatedTime;
    private double fuelCost;
    private String description;

    public Route(Location start, Location destination, double distance,
                int estimatedTime, double fuelCost, String description) {
        this.start = start;
        this.destination = destination;
        this.distance = distance;
        this.estimatedTime = estimatedTime;
        this.fuelCost = fuelCost;
        this.description = description;
    }

    public Location getStart() { return start; }
    public Location getDestination() { return destination; }
    public double getDistance() { return distance; }
    public int getEstimatedTime() { return estimatedTime; }
    public double getFuelCost() { return fuelCost; }
    public String getDescription() { return description; }

    @Override
    public String toString() {
        return String.format("Route: %s → %s\n" +
                           "  %s\n" +
                           "  Distance: %.1f km\n" +
                           "  Time: %d minutes\n" +
                           "  Fuel Cost: $%.2f",
                start.getName(), destination.getName(),
                description, distance, estimatedTime, fuelCost);
    }
}

Concrete Strategies

public class FastestRouteStrategy implements RouteStrategy {

    @Override
    public Route calculateRoute(Location start, Location destination) {
        double distance = calculateDistance(start, destination) * 1.15;
        int estimatedTime = 32;
        double fuelCost = 6.50;

        String description = "Via Highway 101 (fastest route with minimal traffic)";

        return new Route(start, destination, distance, estimatedTime, fuelCost, description);
    }

    @Override
    public String getStrategyName() {
        return "Fastest Route (via highways)";
    }

    private double calculateDistance(Location start, Location destination) {
        double latDiff = destination.getLatitude() - start.getLatitude();
        double lonDiff = destination.getLongitude() - start.getLongitude();
        return Math.sqrt(latDiff * latDiff + lonDiff * lonDiff) * 111;
    }
}

public class ShortestRouteStrategy implements RouteStrategy {

    @Override
    public Route calculateRoute(Location start, Location destination) {
        double distance = calculateDistance(start, destination);
        int estimatedTime = 55;
        double fuelCost = 5.80;

        String description = "Via City Center (shortest distance route)";

        return new Route(start, destination, distance, estimatedTime, fuelCost, description);
    }

    @Override
    public String getStrategyName() {
        return "Shortest Route (via city center)";
    }

    private double calculateDistance(Location start, Location destination) {
        double latDiff = destination.getLatitude() - start.getLatitude();
        double lonDiff = destination.getLongitude() - start.getLongitude();
        return Math.sqrt(latDiff * latDiff + lonDiff * lonDiff) * 111;
    }
}

public class EcoFriendlyRouteStrategy implements RouteStrategy {

    @Override
    public Route calculateRoute(Location start, Location destination) {
        double distance = calculateDistance(start, destination) * 1.05;
        int estimatedTime = 42;
        double fuelCost = 4.90;

        String description = "Via Suburban Roads (optimized for fuel efficiency)";

        return new Route(start, destination, distance, estimatedTime, fuelCost, description);
    }

    @Override
    public String getStrategyName() {
        return "Eco-Friendly Route (fuel optimized)";
    }

    private double calculateDistance(Location start, Location destination) {
        double latDiff = destination.getLatitude() - start.getLatitude();
        double lonDiff = destination.getLongitude() - start.getLongitude();
        return Math.sqrt(latDiff * latDiff + lonDiff * lonDiff) * 111;
    }
}

Context Class

public class NavigationSystem {
    private RouteStrategy routeStrategy;
    private Location currentLocation;

    public NavigationSystem() {
        // Default strategy
        this.routeStrategy = new FastestRouteStrategy();
    }

    public void setRouteStrategy(RouteStrategy strategy) {
        this.routeStrategy = strategy;
        System.out.println("Route strategy changed to: " + strategy.getStrategyName());
    }

    public void setCurrentLocation(Location location) {
        this.currentLocation = location;
    }

    public Route planRoute(Location destination) {
        if (currentLocation == null) {
            throw new IllegalStateException("Current location not set");
        }

        System.out.println("\n=== Planning Route ===");
        System.out.println("Strategy: " + routeStrategy.getStrategyName());

        Route route = routeStrategy.calculateRoute(currentLocation, destination);

        return route;
    }

    public void displayRouteOptions(Location destination) {
        System.out.println("\n=== Available Route Options ===");
        System.out.println("From: " + currentLocation.getName());
        System.out.println("To: " + destination.getName());
        System.out.println();

        RouteStrategy[] strategies = {
            new FastestRouteStrategy(),
            new ShortestRouteStrategy(),
            new EcoFriendlyRouteStrategy()
        };

        for (RouteStrategy strategy : strategies) {
            Route route = strategy.calculateRoute(currentLocation, destination);
            System.out.println(route);
            System.out.println();
        }
    }
}

Client

public class NavigationDemo {
    public static void main(String[] args) {
        System.out.println("=== GPS Navigation System Demo ===\n");

        // Create locations
        Location home = new Location("Home", 37.7749, -122.4194);
        Location office = new Location("Downtown Office", 37.8044, -122.2712);

        // Create navigation system
        NavigationSystem navigation = new NavigationSystem();
        navigation.setCurrentLocation(home);

        // Display all available route options
        navigation.displayRouteOptions(office);

        System.out.println("=".repeat(60));

        // Plan route using fastest strategy (default)
        System.out.println("\n1. Using Fastest Route Strategy:");
        Route fastestRoute = navigation.planRoute(office);
        System.out.println(fastestRoute);

        // Change to shortest distance strategy
        System.out.println("\n2. Using Shortest Route Strategy:");
        navigation.setRouteStrategy(new ShortestRouteStrategy());
        Route shortestRoute = navigation.planRoute(office);
        System.out.println(shortestRoute);

        // Change to eco-friendly strategy
        System.out.println("\n3. Using Eco-Friendly Route Strategy:");
        navigation.setRouteStrategy(new EcoFriendlyRouteStrategy());
        Route ecoRoute = navigation.planRoute(office);
        System.out.println(ecoRoute);
    }
}

Expected Output:

=== GPS Navigation System Demo ===

=== Available Route Options ===
From: Home
To: Downtown Office

Route: Home → Downtown Office
  Via Highway 101 (fastest route with minimal traffic)
  Distance: 19.3 km
  Time: 32 minutes
  Fuel Cost: $6.50

Route: Home → Downtown Office
  Via City Center (shortest distance route)
  Distance: 16.8 km
  Time: 55 minutes
  Fuel Cost: $5.80

Route: Home → Downtown Office
  Via Suburban Roads (optimized for fuel efficiency)
  Distance: 17.6 km
  Time: 42 minutes
  Fuel Cost: $4.90

============================================================

1. Using Fastest Route Strategy:

=== Planning Route ===
Strategy: Fastest Route (via highways)
Route: Home → Downtown Office
  Via Highway 101 (fastest route with minimal traffic)
  Distance: 19.3 km
  Time: 32 minutes
  Fuel Cost: $6.50

2. Using Shortest Route Strategy:
Route strategy changed to: Shortest Route (via city center)

=== Planning Route ===
Strategy: Shortest Route (via city center)
Route: Home → Downtown Office
  Via City Center (shortest distance route)
  Distance: 16.8 km
  Time: 55 minutes
  Fuel Cost: $5.80

3. Using Eco-Friendly Route Strategy:
Route strategy changed to: Eco-Friendly Route (fuel optimized)

=== Planning Route ===
Strategy: Eco-Friendly Route (fuel optimized)
Route: Home → Downtown Office
  Via Suburban Roads (optimized for fuel efficiency)
  Distance: 17.6 km
  Time: 42 minutes
  Fuel Cost: $4.90

🚀 Get the Complete Implementation

The full code with advanced strategy selection and dynamic routing is available in our Design Patterns Repository.

# Clone and run the complete demo
git clone https://github.com/shift-elevate/design-patterns.git
cd design-patterns
mvn test -Dtest=StrategyPatternTest

Real World Examples

The Strategy pattern is extensively used in real-world applications:

1. Payment Processing Systems

Modern payment gateways use Strategy patterns to handle different payment methods (credit cards, digital wallets, bank transfers), with each method implementing the same payment interface but with different processing logic.

2. Data Compression Libraries

Compression libraries use Strategy patterns to support different compression algorithms (ZIP, GZIP, BZIP2), allowing users to select the appropriate algorithm based on speed vs. compression ratio requirements.

3. Machine Learning Frameworks

ML frameworks use Strategy patterns for different algorithms (linear regression, decision trees, neural networks), enabling easy algorithm swapping and comparison without changing the training infrastructure.

When to Use Strategy Pattern

Understanding when to apply the Strategy pattern is crucial for making the right architectural decisions. Here's when it shines and when alternatives might be better:

✅ Ideal Scenarios:

• You have multiple ways to perform a task and want to choose at runtime.

• You want to avoid large conditional statements for algorithm selection.

• You need to add new algorithms without modifying existing code.

• Different algorithms have similar interfaces but different implementations.

❌ Skip It When:

• You only have one or two simple algorithms that rarely change.

• The algorithms are tightly coupled to the context and can't be easily separated.

• Performance overhead of strategy objects is unacceptable.

• The algorithm selection logic is simple and stable.

Next Steps: Apply Strategy Pattern in Your Project

Ready to implement the Strategy pattern in your own projects? Here's a structured approach to get you started:

1. Identify Algorithm Variations: Look for areas where you have multiple ways to accomplish the same task (routing, pricing, sorting, validation).

2. Define Strategy Interface: Create a common interface that all algorithm variations can implement.

3. Implement Concrete Strategies: Build separate classes for each algorithm variation.

4. Create Context Class: Build a class that uses strategies and can switch between them.

5. Add Strategy Selection Logic: Implement logic to choose appropriate strategies based on conditions.

The Strategy pattern transforms rigid algorithmic code into flexible, extensible systems. By encapsulating algorithms in separate strategy objects, you build systems that can adapt to changing requirements while maintaining clean, testable code.

Found this helpful? Share it with a colleague who's struggling with complex algorithm selection logic. Got questions? We'd love to hear from you at [email protected]

We will see how we can refactor using the Extract Class technique to group related data and reduce parameter lists.

Clean Code Reference

❝

⚠️ Code Smell: Data Clumps
✅ Refactoring: Extract Class
🎯 Goal: Group related data and reduce parameter coupling

The Data Clumps code smell occurs when the same group of data items appears together in multiple places throughout the code, but they are not organized into a single object. The Extract Class refactoring technique groups these related data items into a meaningful object, reducing parameter lists and improving code organization.

The Code Smell: Data Clumps

Data Clumps are groups of data that always appear together but are scattered across multiple parameters, method signatures, and classes. This creates tight coupling between methods and makes the code harder to maintain. When you need to add or modify related data, you have to change multiple places in the code.

Symptoms

Impact

Same group of parameters in multiple methods

Tight coupling

Related data scattered across code

Difficult to maintain

Long parameter lists

Poor code organization

Here's a typical example of Data Clumps:

public class PatientManager {

    public void registerPatient(String firstName, String lastName,
                               String phone, String email,
                               String insuranceProvider, String policyNumber) {
        Patient patient = new Patient();
        patient.setFirstName(firstName);
        patient.setLastName(lastName);
        patient.setPhone(phone);
        patient.setEmail(email);
        patient.setInsuranceProvider(insuranceProvider);
        patient.setPolicyNumber(policyNumber);

        savePatient(patient);
    }

    public void updateContactInfo(String firstName, String lastName,
                                 String newPhone, String newEmail) {
        Patient patient = findPatient(firstName, lastName);
        patient.setPhone(newPhone);
        patient.setEmail(newEmail);

        savePatient(patient);
    }

    public void scheduleAppointment(String firstName, String lastName,
                                   String phone, String email,
                                   String appointmentDate, String appointmentType) {
        String message = String.format("Appointment scheduled for %s %s on %s for %s",
                firstName, lastName, appointmentDate, appointmentType);

        sendEmailConfirmation(email, "Appointment Confirmation", message);
        sendSmsConfirmation(phone, message);
    }

    private Patient findPatient(String firstName, String lastName) {
        return new Patient();
    }

    private void savePatient(Patient patient) { }

    private void sendEmailConfirmation(String email, String subject, String message) { }

    private void sendSmsConfirmation(String phone, String message) { }
}

public class Patient {
    private String firstName;
    private String lastName;
    private String phone;
    private String email;
    private String insuranceProvider;
    private String policyNumber;

    public String getFirstName() { return firstName; }
    public void setFirstName(String firstName) { this.firstName = firstName; }
    public String getLastName() { return lastName; }
    public void setLastName(String lastName) { this.lastName = lastName; }
    public String getPhone() { return phone; }
    public void setPhone(String phone) { this.phone = phone; }
    public String getEmail() { return email; }
    public void setEmail(String email) { this.email = email; }
    public String getInsuranceProvider() { return insuranceProvider; }
    public void setInsuranceProvider(String insuranceProvider) { this.insuranceProvider = insuranceProvider; }
    public String getPolicyNumber() { return policyNumber; }
    public void setPolicyNumber(String policyNumber) { this.policyNumber = policyNumber; }
}

In this example, we can see data clumps everywhere: patient demographics (firstName, lastName), contact information (phone, email), insurance details (provider, policyNumber), and appointment information (appointmentDate, appointmentType) appear together in multiple methods. This creates long parameter lists and makes the code hard to maintain.

The Refactoring: Extract Class

The Extract Class refactoring technique groups related data items into meaningful objects, reducing parameter lists and improving code organization. This makes the code more maintainable and reduces coupling between methods.

By creating dedicated classes for patient demographics, contact information, insurance details, and appointments, we transform the scattered primitive parameters into cohesive objects. Each extracted class encapsulates related data and provides meaningful methods, making the code more organized and easier to understand.

Step by Step Refactoring Process:

1. Identify data clumps that appear together in multiple places.

2. Create new classes to represent these data groups.

3. Move related data into the new classes.

4. Update method signatures to use the new objects.

5. Move related behaviour into the new classes.

Here's the refactored version:

The scattered data clumps have been organized into meaningful classes:

1. PatientManager - Simplified service class

2. PatientDemographics - Extracted demographic data

3. ContactInformation - Extracted contact details

4. InsuranceDetails - Extracted insurance data

5. Appointment - Extracted appointment information

6. Patient - Coordinator class

PatientManager - Simplified Service Class

public class PatientManager {

    public void registerPatient(PatientDemographics demographics,
                               ContactInformation contactInfo,
                               InsuranceDetails insurance) {
        Patient patient = new Patient(demographics, contactInfo, insurance);
        savePatient(patient);
    }

    public void updateContactInfo(PatientDemographics demographics,
                                 ContactInformation newContactInfo) {
        Patient patient = findPatient(demographics);
        patient.updateContactInfo(newContactInfo);
        savePatient(patient);
    }

    public void scheduleAppointment(PatientDemographics demographics,
                                   ContactInformation contactInfo,
                                   Appointment appointment) {
        String message = String.format("Appointment scheduled for %s on %s for %s",
                demographics.getFullName(), appointment.getDate(), appointment.getType());

        contactInfo.sendEmailConfirmation("Appointment Confirmation", message);
        contactInfo.sendSmsConfirmation(message);
    }

    private Patient findPatient(PatientDemographics demographics) {
        return new Patient();
    }

    private void savePatient(Patient patient) { }
}

PatientDemographics - Extracted Demographic Data

public class PatientDemographics {
    private final String firstName;
    private final String lastName;

    public PatientDemographics(String firstName, String lastName) {
        this.firstName = firstName;
        this.lastName = lastName;
    }

    public String getFullName() {
        return firstName + " " + lastName;
    }

    public String getFirstName() { return firstName; }
    public String getLastName() { return lastName; }

    @Override
    public String toString() {
        return String.format("Patient{name='%s %s'}", firstName, lastName);
    }
}

ContactInformation - Extracted Contact Details

public class ContactInformation {
    private final String phone;
    private final String email;

    public ContactInformation(String phone, String email) {
        this.phone = phone;
        this.email = email;
    }

    public void sendEmailConfirmation(String subject, String message) {
        System.out.println("Email sent to " + email + ": " + subject);
    }

    public void sendSmsConfirmation(String message) {
        System.out.println("SMS sent to " + phone + ": " + message);
    }

    public String getPhone() { return phone; }
    public String getEmail() { return email; }

    @Override
    public String toString() {
        return String.format("Contact{phone='%s', email='%s'}", phone, email);
    }
}public class ContactInformation {
    private final String phone;
    private final String email;

    public ContactInformation(String phone, String email) {
        this.phone = phone;
        this.email = email;
    }

    public void sendEmailConfirmation(String subject, String message) {
        System.out.println("Email sent to " + email + ": " + subject);
    }

    public void sendSmsConfirmation(String message) {
        System.out.println("SMS sent to " + phone + ": " + message);
    }

    public String getPhone() { return phone; }
    public String getEmail() { return email; }

    @Override
    public String toString() {
        return String.format("Contact{phone='%s', email='%s'}", phone, email);
    }
}

InsuranceDetails - Extracted Insurance Data

public class InsuranceDetails {
    private final String provider;
    private final String policyNumber;

    public InsuranceDetails(String provider, String policyNumber) {
        this.provider = provider;
        this.policyNumber = policyNumber;
    }

    public String getFormattedCoverage() {
        return String.format("%s (Policy: %s)", provider, policyNumber);
    }

    public String getProvider() { return provider; }
    public String getPolicyNumber() { return policyNumber; }

    @Override
    public String toString() {
        return getFormattedCoverage();
    }
}
public class InsuranceDetails {
    private final String provider;
    private final String policyNumber;

    public InsuranceDetails(String provider, String policyNumber) {
        this.provider = provider;
        this.policyNumber = policyNumber;
    }

    public String getFormattedCoverage() {
        return String.format("%s (Policy: %s)", provider, policyNumber);
    }

    public String getProvider() { return provider; }
    public String getPolicyNumber() { return policyNumber; }

    @Override
    public String toString() {
        return getFormattedCoverage();
    }
}

Appointment - Extracted Appointment Information

public class Appointment {
    private final String date;
    private final String type;

    public Appointment(String date, String type) {
        this.date = date;
        this.type = type;
    }

    public String getDate() { return date; }
    public String getType() { return type; }

    @Override
    public String toString() {
        return String.format("Appointment{date='%s', type='%s'}", date, type);
    }
}public class Appointment {
    private final String date;
    private final String type;

    public Appointment(String date, String type) {
        this.date = date;
        this.type = type;
    }

    public String getDate() { return date; }
    public String getType() { return type; }

    @Override
    public String toString() {
        return String.format("Appointment{date='%s', type='%s'}", date, type);
    }
}

Patient - Coordinator Class

public class Patient {
    private final PatientDemographics demographics;
    private ContactInformation contactInfo;
    private final InsuranceDetails insurance;

    public Patient(PatientDemographics demographics,
                  ContactInformation contactInfo,
                  InsuranceDetails insurance) {
        this.demographics = demographics;
        this.contactInfo = contactInfo;
        this.insurance = insurance;
    }

    public void updateContactInfo(ContactInformation newContactInfo) {
        this.contactInfo = newContactInfo;
    }

    public PatientDemographics getDemographics() { return demographics; }
    public ContactInformation getContactInfo() { return contactInfo; }
    public InsuranceDetails getInsurance() { return insurance; }

    @Override
    public String toString() {
        return String.format("Patient{demographics=%s, contact=%s, insurance=%s}",
                demographics, contactInfo, insurance);
    }
}public class Patient {
    private final PatientDemographics demographics;
    private ContactInformation contactInfo;
    private final InsuranceDetails insurance;

    public Patient(PatientDemographics demographics,
                  ContactInformation contactInfo,
                  InsuranceDetails insurance) {
        this.demographics = demographics;
        this.contactInfo = contactInfo;
        this.insurance = insurance;
    }

    public void updateContactInfo(ContactInformation newContactInfo) {
        this.contactInfo = newContactInfo;
    }

    public PatientDemographics getDemographics() { return demographics; }
    public ContactInformation getContactInfo() { return contactInfo; }
    public InsuranceDetails getInsurance() { return insurance; }

    @Override
    public String toString() {
        return String.format("Patient{demographics=%s, contact=%s, insurance=%s}",
                demographics, contactInfo, insurance);
    }
}

Usage Example - Putting It All Together

Notice how the refactored version transforms 8 primitive parameters (firstName, lastName, phone, email, insuranceProvider, policyNumber, appointmentDate, appointmentType) into just 4 meaningful objects. The PatientDemographics object encapsulates demographic data, ContactInformation handles contact details, InsuranceDetails manages insurance data, and Appointment represents appointment information. This not only reduces parameter counts but also makes the code self-documenting.

When you call demographics.getFullName() or insurance.getFormattedCoverage(), it's immediately clear what you're working with. Compare this to the original scattered parameters where they could easily be confused or passed in the wrong order.

public class PatientRegistrationDemo {
    public static void main(String[] args) {
        System.out.println("=== Patient Registration System ===\n");

        PatientDemographics demographics = new PatientDemographics("John", "Doe");
        ContactInformation contactInfo = new ContactInformation("555-123-4567", "[email protected]");
        InsuranceDetails insurance = new InsuranceDetails("Blue Cross Blue Shield", "BCBS123456");

        PatientManager patientManager = new PatientManager();
        patientManager.registerPatient(demographics, contactInfo, insurance);

        System.out.println("\nPatient registered successfully:");
        System.out.println("  Name: " + demographics.getFullName());
        System.out.println("  Email: " + contactInfo.getEmail());
        System.out.println("  Insurance: " + insurance.getFormattedCoverage());

        System.out.println("\n=== Scheduling Appointment ===");
        Appointment appointment = new Appointment("2024-03-15 10:00 AM", "Annual Checkup");
        patientManager.scheduleAppointment(demographics, contactInfo, appointment);

        System.out.println("\n=== Updating Contact Information ===");
        ContactInformation updatedContact = new ContactInformation("555-111-2222", "[email protected]");
        patientManager.updateContactInfo(demographics, updatedContact);
        System.out.println("Contact information updated successfully");
    }
}

Expected Output:

=== Patient Registration System ===

Patient registered successfully:
  Name: John Doe
  Email: [email protected]
  Insurance: Blue Cross Blue Shield (Policy: BCBS123456)

=== Scheduling Appointment ===
Email sent to [email protected]: Appointment Confirmation
SMS sent to 555-123-4567: Appointment scheduled for John Doe on 2024-03-15 10:00 AM for Annual Checkup

=== Updating Contact Information ===
Contact information updated successfully

Benefits of Extract Class for Data Clumps

Benefit

Description

Reduced Parameter Lists

Methods have fewer parameters, making them easier to call and understand.

Better Code Organization

Related data is grouped together, making the code more logical and maintainable.

Reduced Coupling

Changes to related data only require updates in one place, reducing the impact of changes.

Meaningful Methods

Each object provides domain-specific methods like getFullName() or getFormattedCoverage(), making the code more expressive.

When to Apply Extract Class for Data Clumps

• The same group of parameters appears in multiple method signatures.

• Related data items are scattered across multiple classes.

• Long parameter lists that are hard to understand and maintain.

• When you find yourself passing the same set of parameters to multiple methods.

• When related data changes together and should be treated as a unit.

Apply Extract Class refactoring to one set of data clumps in your current project today. Start with the data clumps that appear most frequently across your codebase.

Repository & Resources

Complete Code Examples: Clean Code Repository

Find the complete implementation of Data Clumps refactoring and other clean code techniques in our dedicated repository. Each example includes:

• Before and after code comparisons

• Unit tests demonstrating the improvements

Found this helpful? Share it with a colleague who's struggling with Data Clumps. Got questions? We'd love to hear from you at [email protected]

This pattern is essential for modern microservices architectures where clients need data from multiple services to render a single view. By implementing intelligent aggregation strategies, you can significantly reduce client complexity while maintaining system performance and reliability.

Gateway Aggregation

This guide walks you through the Gateway Aggregation pattern from concept to practical implementation, covering parallel service calls, response aggregation, and handling multiple service requests.

• Understanding the Gateway Aggregation Pattern

• Implementing the Gateway Aggregation Pattern

• When to Use Gateway Aggregation Pattern

• Best Practices

Understanding the Gateway Aggregation Pattern

The Gateway Aggregation pattern uses an API gateway to collect data from multiple backend services and combine them into a single response. This reduces the number of round trips between clients and services, improving performance and simplifying client-side logic.

Core Architecture

Gateway Aggregation Interactions

Key Benefits

• Reduced Client Complexity: Clients make fewer requests and handle less data aggregation logic.

• Improved Performance: Parallel service calls reduce overall response time.

• Reduced Network Overhead: Fewer round trips between clients and services.

• Better Error Handling: Track errors from individual services and return partial results.

• Consistent Data Format: Standardized response format across all aggregated endpoints.

Implementing the Gateway Aggregation Pattern

Let's build a gateway aggregation system that demonstrates the core pattern with parallel service calls and response aggregation.

Implementation Overview

• AggregationGateway: Core gateway managing service calls, aggregation rules, and parallel execution

• Service Clients: Mock implementations for calling backend services

• Configuration Models: Simple data structures for rules, requests, and responses

• E-commerce Example: Practical dashboard aggregation demonstration

Note on Implementation

This implementation uses CompletableFuture for parallel service calls, providing non-blocking aggregation. The gateway executes multiple service calls concurrently and waits for all results before combining them into a single response. For production systems, consider using reactive frameworks like Project Reactor or RxJava for better resource utilization and backpressure handling.

Core Aggregation Gateway Implementation

Gateway Class Structure

The core gateway manages service calls and aggregation rules:

public class AggregationGateway {
    private final Map<String, AggregationRule> aggregationRules = new ConcurrentHashMap<>();
    private final ExecutorService executorService;

    public AggregationGateway() {
        this.executorService = Executors.newFixedThreadPool(20);
    }

    public void registerRule(AggregationRule rule) {
        aggregationRules.put(rule.endpoint(), rule);
    }

    public void shutdown() {
        executorService.shutdown();
    }
}

Processing Requests and Parallel Execution

The gateway processes requests by executing multiple service calls in parallel:

public AggregatedResponse processRequest(String endpoint, Map<String, Object> requestData) {
    AggregationRule rule = aggregationRules.get(endpoint);
    if (rule == null) {
        return new AggregatedResponse(false, "Unknown endpoint: " + endpoint, null);
    }

    // Start all service calls in parallel
    List<CompletableFuture<ServiceResponse>> futures = new ArrayList<>();
    for (ServiceCall call : rule.serviceCalls()) {
        futures.add(CompletableFuture.supplyAsync(() ->
            callService(call, requestData), executorService));
    }

    // Wait for all calls to complete
    try {
        CompletableFuture.allOf(futures.toArray(new CompletableFuture[0]))
            .get(rule.timeoutMs(), TimeUnit.MILLISECONDS);
    } catch (Exception e) {
        System.err.println("Some services timed out");
    }

    // Collect results
    Map<String, Object> aggregatedData = new HashMap<>();
    List<ServiceError> errors = new ArrayList<>();

    for (int i = 0; i < futures.size(); i++) {
        ServiceCall call = rule.serviceCalls().get(i);
        try {
            ServiceResponse response = futures.get(i).get(100, TimeUnit.MILLISECONDS);
            if (response.success()) {
                aggregatedData.put(call.responseKey(), response.data());
            } else {
                errors.add(new ServiceError(call.serviceName(), response.errorMessage()));
            }
        } catch (Exception e) {
            errors.add(new ServiceError(call.serviceName(), "Service unavailable"));
        }
    }

    boolean success = errors.isEmpty();
    return new AggregatedResponse(success,
        success ? "Success" : "Partial success", aggregatedData, errors);
}

private ServiceResponse callService(ServiceCall call, Map<String, Object> requestData) {
    try {
        // Simulate service call with mock data
        Thread.sleep(100 + (long)(Math.random() * 200));

        // Simulate occasional failures
        if (Math.random() < 0.1) {
            return new ServiceResponse(false, call.serviceName(), "Service error", null);
        }

        // Return mock response
        return new ServiceResponse(true, call.serviceName(), null,
            Map.of("service", call.serviceName(), "data", "mock data"));
    } catch (Exception e) {
        return new ServiceResponse(false, call.serviceName(), e.getMessage(), null);
    }
}

Configuration and Response Models

Simple data structures for the gateway:

// Aggregation rule defines which services to call
record AggregationRule(String endpoint, List<ServiceCall> serviceCalls, long timeoutMs) {}

// Individual service call configuration
record ServiceCall(String serviceName, String responseKey) {}

// Aggregated response from gateway
public class AggregatedResponse {
    private final boolean success;
    private final String message;
    private final Map<String, Object> data;
    private final List<ServiceError> errors;

    public AggregatedResponse(boolean success, String message, Map<String, Object> data) {
        this(success, message, data, new ArrayList<>());
    }

    public AggregatedResponse(boolean success, String message, Map<String, Object> data,
                             List<ServiceError> errors) {
        this.success = success;
        this.message = message;
        this.data = data != null ? new HashMap<>(data) : new HashMap<>();
        this.errors = errors != null ? new ArrayList<>(errors) : new ArrayList<>();
    }

    public boolean isSuccess() { return success; }
    public String getMessage() { return message; }
    public Map<String, Object> getData() { return data; }
    public List<ServiceError> getErrors() { return errors; }
}

// Service response and error records
record ServiceResponse(boolean success, String serviceName, String errorMessage, Object data) {}
record ServiceError(String serviceName, String errorMessage) {}

When to Use Gateway Aggregation Pattern

Understanding when to apply the Gateway Aggregation pattern is crucial for making the right architectural decisions. Here's when it shines and when alternatives might be better:

✅ Ideal Scenarios:

• Clients need data from multiple services to render a single view (dashboards, profiles, etc.).

• You want to reduce network round trips and latency for mobile or low-bandwidth clients.

• Different client types need different data aggregations from the same backend services.

• You need to simplify client-side logic by moving complexity to the gateway.

• You want to provide backward compatibility while refactoring monoliths to microservices.

❌ Skip It When:

• You only have simple single-service requests with no aggregation needs.

• Services have vastly different SLAs making aggregation unreliable.

• Real-time consistency across all services is critical and aggregation adds unacceptable latency.

• The added complexity of maintaining aggregation rules doesn't justify the client-side simplification.

Best Practices

Set Appropriate Timeouts: Critical services need shorter timeouts, while non-critical services can tolerate longer ones.

Handle Partial Failures: Return partial results when some services fail. If notifications fail, still return user profile and orders.

Use Parallel Execution: Execute independent service calls concurrently. Use sequential calls only when services have dependencies.

Keep It Simple: Start with basic aggregation and parallel execution. Focus on the core pattern before adding complexity.

Found this helpful? Share it with a colleague who's struggling with client complexity in their microservices architecture. Got questions? We'd love to hear from you at [email protected]

Picture this: You're building an air traffic control system where multiple aircraft need to coordinate landings and takeoffs. Your initial approach seems logical: aircraft communicate directly with each other to avoid collisions.

But as the airport grows, you realize the chaos: each aircraft needs to know about every other aircraft, constantly checking positions, coordinating runway usage, and negotiating priorities. Adding a new aircraft means every existing aircraft's logic needs updating. It's a tangled web of dependencies where planes are tightly coupled to each other.

The Mediator pattern solves this complexity by introducing a control tower that centralizes all communication, promoting loose coupling and making the system easier to understand and maintain.

Understanding the Mediator Pattern

The Mediator pattern defines an object that encapsulates how a set of objects interact. Instead of objects referring to each other directly, they communicate through the mediator, which acts as a central hub for all interactions.

Think of it like an air traffic control tower: instead of pilots communicating directly with each other (which would be chaotic), they all communicate through the control tower, which coordinates and manages all interactions safely and efficiently.

This pattern promotes Loose Coupling, Centralized Control, and Simplified Communication while reducing the complexity of object interactions.

Without Mediator: Components communicate directly with each other, creating tight coupling. Each component needs to know about every other component, leading to complex dependencies and difficult maintenance.

With Mediator: Components communicate through a central mediator. The mediator coordinates all interactions, and components only need to know about the mediator, not each other.

Mediator Pattern Components

Core Components

• Mediator Interface: Defines the communication interface for coordinating operations.

• Concrete Mediator: Implements the mediator interface and coordinates all component interactions.

• Aircraft Component: Communicates with the tower for landing, takeoff, and position reporting.

• Ground Control Component: Receives notifications from the tower about aircraft activities.

Complete Java Implementation

Let's build an air traffic control system that demonstrates the Mediator pattern's power in preventing direct communication chaos.

Mediator Interface

public interface ControlTower {
    void requestLanding(Aircraft aircraft);
    void requestTakeoff(Aircraft aircraft);
    void reportPosition(Aircraft aircraft, String position);
    void registerAircraft(Aircraft aircraft);
    void notifyGroundControl(GroundControl groundControl);
}

Concrete Mediator

public class AirTrafficControlTower implements ControlTower {
    private List<Aircraft> aircrafts = new ArrayList<>();
    private GroundControl groundControl;
    private boolean runwayAvailable = true;

    @Override
    public void registerAircraft(Aircraft aircraft) {
        aircrafts.add(aircraft);
    }

    @Override
    public void notifyGroundControl(GroundControl groundControl) {
        this.groundControl = groundControl;
    }

    @Override
    public void requestLanding(Aircraft aircraft) {
        if (runwayAvailable) {
            runwayAvailable = false;
            System.out.println("Tower: " + aircraft.getName() + " cleared for landing");

            // Notify other aircraft to hold
            for (Aircraft other : aircrafts) {
                if (other != aircraft) {
                    other.receiveMessage("Hold position, " + aircraft.getName() + " is landing");
                }
            }

            // Notify ground control
            if (groundControl != null) {
                groundControl.receiveNotification(aircraft.getName() + " is landing");
            }
        } else {
            aircraft.receiveMessage("Runway occupied, please hold");
        }
    }

    @Override
    public void requestTakeoff(Aircraft aircraft) {
        if (runwayAvailable) {
            runwayAvailable = false;
            System.out.println("Tower: " + aircraft.getName() + " cleared for takeoff");
        } else {
            aircraft.receiveMessage("Runway occupied, hold for takeoff");
        }
    }

    @Override
    public void reportPosition(Aircraft aircraft, String position) {
        System.out.println("Tower: " + aircraft.getName() + " reported at " + position);
        runwayAvailable = true;

        // Notify ground control about aircraft position
        if (groundControl != null) {
            groundControl.receiveNotification(aircraft.getName() + " at " + position);
        }
    }
}

Aircraft Component

public class Aircraft {
    private String name;
    private ControlTower tower;

    public Aircraft(String name, ControlTower tower) {
        this.name = name;
        this.tower = tower;
        tower.registerAircraft(this);
    }

    public void requestLanding() {
        System.out.println(name + ": Requesting landing clearance");
        tower.requestLanding(this);
    }

    public void requestTakeoff() {
        System.out.println(name + ": Requesting takeoff clearance");
        tower.requestTakeoff(this);
    }

    public void reportPosition(String position) {
        System.out.println(name + ": Reporting position - " + position);
        tower.reportPosition(this, position);
    }

    public void receiveMessage(String message) {
        System.out.println(name + " received: " + message);
    }

    public String getName() {
        return name;
    }
}

Ground Control Component

public class GroundControl {
    private String name;

    public GroundControl(String name) {
        this.name = name;
    }

    public void receiveNotification(String message) {
        System.out.println(name + " notified: " + message);
    }
}

Client

public class AirTrafficControllerDemo {
    public static void main(String[] args) {
        // Create control tower (mediator)
        ControlTower tower = new AirTrafficControlTower();

        // Create and set ground control
        GroundControl groundControl = new GroundControl("Ground Control");
        tower.notifyGroundControl(groundControl);

        // Create aircraft
        Aircraft flight1 = new Aircraft("Flight 101", tower);
        Aircraft flight2 = new Aircraft("Flight 202", tower);

        System.out.println("=== Air Traffic Control Demo ===\n");

        // Flight 1 requests landing
        flight1.requestLanding();

        System.out.println();

        // Flight 2 tries to land while runway is occupied
        flight2.requestLanding();

        System.out.println();

        // Flight 1 reports landed
        flight1.reportPosition("Gate A");

        System.out.println();

        // Now Flight 2 can land
        flight2.requestLanding();
    }
}

Expected Output:

=== Air Traffic Control Demo ===

Flight 101: Requesting landing clearance
Tower: Flight 101 cleared for landing
Flight 202 received: Hold position, Flight 101 is landing
Ground Control notified: Flight 101 is landing

Flight 202: Requesting landing clearance
Flight 202 received: Runway occupied, please hold

Flight 101: Reporting position - Gate A
Tower: Flight 101 reported at Gate A
Ground Control notified: Flight 101 at Gate A

Flight 202: Requesting landing clearance
Tower: Flight 202 cleared for landing
Flight 101 received: Hold position, Flight 202 is landing
Ground Control notified: Flight 202 is landing

🚀 Get the Complete Implementation

The full code with advanced mediator implementations and complex interaction scenarios is available in our Design Patterns Repository.

# Clone and run the complete demo
git clone https://github.com/shift-elevate/design-patterns.git
cd design-patterns
mvn test -Dtest=MediatorPatternTest

Real World Examples

The Mediator pattern is extensively used in real world applications:

1. GUI Frameworks

Modern GUI frameworks use the Mediator pattern extensively for component communication. Instead of UI components directly communicating with each other, they communicate through a central mediator that manages events, state changes, and component interactions.

2. Chat Applications

Chat applications use the Mediator pattern to manage communication between users. The chat server acts as a mediator, receiving messages from one user and distributing them to all other users in the chat room.

3. Workflow Management Systems

Business process management systems use the Mediator pattern to coordinate different workflow steps, ensuring that each step communicates through a central workflow engine rather than directly with other steps.

When to Use the Mediator Pattern

Understanding when to apply the Mediator pattern is crucial for making the right architectural decisions. Here's when it shines and when alternatives might be better:

✅ Ideal Scenarios:

• You have a set of objects that communicate in well defined but complex ways.

• You want to avoid tight coupling between objects that interact.

• You need to reuse objects in different contexts without changing their communication logic.

• You want to centralize control over how objects interact.

❌ Skip It When:

• The communication between objects is simple and doesn't benefit from centralization.

• You have a small number of objects with minimal interactions.

Next Steps: Apply Mediator Pattern in Your Project

Ready to implement the Mediator pattern in your own projects? Here's a structured approach to get you started:

1. Identify Complex Interactions: Look for areas where multiple objects need to communicate with each other.

2. Define Communication Protocol: Create a mediator interface that defines how objects should interact.

3. Implement Central Mediator: Build a concrete mediator that handles all object interactions.

4. Refactor Components: Modify existing objects to communicate through the mediator.

5. Test Interaction Scenarios: Ensure all communication flows work correctly through the mediator.

The Mediator pattern transforms complex, tightly coupled object interactions into clean, maintainable systems. By centralizing communication through a mediator, you build systems that are easier to understand, modify, and extend.

Found this helpful? Share it with a colleague who's struggling with complex object interactions. Got questions? We'd love to hear from you at [email protected]

We will see how we can refactor using the Extract Class technique for better maintainability and single responsibility.

Clean Code Reference

❝

⚠️ Code Smell: Large Class
✅ Refactoring: Extract Class
🎯 Goal: Single Responsibility Principle and focused classes

The Large Class code smell occurs when a class becomes too large and takes on too many responsibilities, violating the Single Responsibility Principle. The Extract Class refactoring technique breaks down large classes into smaller, focused classes that each have a single, well-defined responsibility.

The Code Smell: Large Class

Large Class is one of the most common code smells that indicates a violation of the Single Responsibility Principle. When a class grows too large, it becomes difficult to understand, test, and maintain. Large classes often contain multiple unrelated responsibilities, making them fragile and prone to bugs.

Symptoms

Impact

Too many fields and methods

Difficult to understand

Multiple unrelated responsibilities

Hard to test and maintain

Frequent changes affecting many methods

Higher bug risk

Here's a typical example of Large Class:

public class CustomerManager {
    // Customer data fields
    private String customerId;
    private String firstName;
    private String lastName;
    private String email;
    private String phone;
    private String address;
    private String city;
    private String state;
    private String zipCode;
    private String country;
    
    // Account management fields
    private double accountBalance;
    private String accountStatus;
    private Date accountCreatedDate;
    private Date lastLoginDate;
    private int loyaltyPoints;

    // Notification preferences
    private boolean emailNotifications;
    private boolean smsNotifications;
    private boolean pushNotifications;
    private String preferredLanguage;
    
    // What does this massive class do? Everything!
    
    // Customer data methods
    public void updatePersonalInfo(String firstName, String lastName, String email) {
        this.firstName = firstName;
        this.lastName = lastName;
        this.email = email;
        validateEmail(email);
        logPersonalInfoUpdate();
    }
    
    public void updateAddress(String address, String city, String state, String zipCode, String country) {
        this.address = address;
        this.city = city;
        this.state = state;
        this.zipCode = zipCode;
        this.country = country;
        validateAddress();
        logAddressUpdate();
    }
    
    // Account management methods
    public void processPayment(double amount) {
        if (accountBalance >= amount) {
            accountBalance -= amount;
            updateLoyaltyPoints(amount);
            logTransaction(amount);
            sendPaymentConfirmation();
        } else {
            throw new InsufficientFundsException("Insufficient account balance");
        }
    }
    
    public void addFunds(double amount) {
        accountBalance += amount;
        logTransaction(amount);
        sendBalanceUpdateNotification();
    }
    
    public void updateAccountStatus(String status) {
        this.accountStatus = status;
        logStatusChange(status);
        if ("SUSPENDED".equals(status)) {
            sendAccountSuspensionNotification();
        }
    }

    // Notification methods
    public void updateNotificationPreferences(boolean email, boolean sms, boolean push) {
        this.emailNotifications = email;
        this.smsNotifications = sms;
        this.pushNotifications = push;
        logPreferenceUpdate();
    }
    
    public void sendNotification(String message, String type) {
        if ("EMAIL".equals(type) && emailNotifications) {
            sendEmailNotification(message);
        } else if ("SMS".equals(type) && smsNotifications) {
            sendSMSNotification(message);
        } else if ("PUSH".equals(type) && pushNotifications) {
            sendPushNotification(message);
        }
    }
    
    // Private helper methods (too many!)
    private void validateEmail(String email) { /* validation logic */ }
    private void validateAddress() { /* validation logic */ }
    private void logPersonalInfoUpdate() { /* logging logic */ }
    private void logAddressUpdate() { /* logging logic */ }
    private void logTransaction(double amount) { /* logging logic */ }
    private void logStatusChange(String status) { /* logging logic */ }
    private void logPreferenceUpdate() { /* logging logic */ }
    private void updateLoyaltyPoints(double amount) { /* loyalty logic */ }
    private void sendPaymentConfirmation() { /* notification logic */ }
    private void sendBalanceUpdateNotification() { /* notification logic */ }
    private void sendAccountSuspensionNotification() { /* notification logic */ }
    private void sendEmailNotification(String message) { /* email logic */ }
    private void sendSMSNotification(String message) { /* SMS logic */ }
    private void sendPushNotification(String message) { /* push logic */ }
}

In this example, the CustomerManager class is trying to do everything: manage customer data, handle account operations, and manage notifications. This violates the Single Responsibility Principle and makes the class difficult to understand, test, and maintain.

The Refactoring: Extract Class

The Extract Class refactoring technique breaks down large classes into smaller, focused classes that each have a single, well-defined responsibility. This improves code organization, testability, and maintainability.

Step by Step Refactoring Process:

1. Identify distinct responsibilities within the large class.

2. Group related fields and methods that belong together.

3. Create new classes for each identified responsibility.

4. Move fields and methods to their appropriate classes.

5. Update the original class to use the new classes through composition.

Here's the refactored version:

The large class has been broken down into four focused classes:

1. CustomerManager - Main coordinator class

2. CustomerProfile - Manages customer personal information

3. AccountManager - Handles account operations

4. NotificationManager - Manages notification preferences and sending

1. CustomerManager - Main Coordinator Class

// Main class now focuses on coordinating other classes
public class CustomerManager {
    private CustomerProfile customerProfile;
    private AccountManager accountManager;
    private NotificationManager notificationManager;

    public CustomerManager(String customerId) {
        this.customerProfile = new CustomerProfile(customerId);
        this.accountManager = new AccountManager();
        this.notificationManager = new NotificationManager();
    }

    public void updatePersonalInfo(String firstName, String lastName, String email) {
        customerProfile.updatePersonalInfo(firstName, lastName, email);
    }

    public void updateAddress(String address, String city, String state, String zipCode, String country) {
        customerProfile.updateAddress(address, city, state, zipCode, country);
    }

    public void processPayment(double amount) {
        accountManager.processPayment(amount);
        notificationManager.sendPaymentConfirmation();
    }
}

2. CustomerProfile - Manages Customer Personal Information

// Focused class for customer profile data
public class CustomerProfile {
    private String customerId;
    private String firstName;
    private String lastName;
    private String email;
    private String phone;
    private String address;
    private String city;
    private String state;
    private String zipCode;
    private String country;
    
    public CustomerProfile(String customerId) {
        this.customerId = customerId;
    }
    
    public void updatePersonalInfo(String firstName, String lastName, String email) {
        this.firstName = firstName;
        this.lastName = lastName;
        this.email = email;
        validateEmail(email);
        logPersonalInfoUpdate();
    }
    
    public void updateAddress(String address, String city, String state, String zipCode, String country) {
        this.address = address;
        this.city = city;
        this.state = state;
        this.zipCode = zipCode;
        this.country = country;
        validateAddress();
        logAddressUpdate();
    }
    
    private void validateEmail(String email) { /* validation logic */ }
    private void validateAddress() { /* validation logic */ }
    private void logPersonalInfoUpdate() { /* logging logic */ }
    private void logAddressUpdate() { /* logging logic */ }
    
    // Getters and other profile-related methods
}

3. AccountManager - Handles Account Operations

// Focused class for account operations
public class AccountManager {
    private double accountBalance;
    private String accountStatus;
    private Date accountCreatedDate;
    private Date lastLoginDate;
    private int loyaltyPoints;
    
    public void processPayment(double amount) {
        if (accountBalance >= amount) {
            accountBalance -= amount;
            logTransaction(amount);
        } else {
            throw new InsufficientFundsException("Insufficient account balance");
        }
    }
    
    public void addFunds(double amount) {
        accountBalance += amount;
        logTransaction(amount);
    }
    
    public void updateAccountStatus(String status) {
        this.accountStatus = status;
        logStatusChange(status);
    }
    
    public void updateLoyaltyPoints(double amount) {
        loyaltyPoints += (int) (amount * 0.1); // 10% of amount as points
    }
    
    private void logTransaction(double amount) { /* logging logic */ }
    private void logStatusChange(String status) { /* logging logic */ }
    
    // Getters and other account-related methods
}

4. NotificationManager - Manages Notification Preferences and Sending

// Focused class for notifications
public class NotificationManager {
    private boolean emailNotifications;
    private boolean smsNotifications;
    private boolean pushNotifications;
    private String preferredLanguage;
    
    public NotificationManager() {
        this.emailNotifications = true;
        this.smsNotifications = false;
        this.pushNotifications = true;
        this.preferredLanguage = "EN";
    }
    
    public void updateNotificationPreferences(boolean email, boolean sms, boolean push) {
        this.emailNotifications = email;
        this.smsNotifications = sms;
        this.pushNotifications = push;
        logPreferenceUpdate();
    }
    
    public void sendNotification(String message, String type) {
        if ("EMAIL".equals(type) && emailNotifications) {
            sendEmailNotification(message);
        } else if ("SMS".equals(type) && smsNotifications) {
            sendSMSNotification(message);
        } else if ("PUSH".equals(type) && pushNotifications) {
            sendPushNotification(message);
        }
    }
    
    public void sendPaymentConfirmation() {
        sendNotification("Payment processed successfully", "EMAIL");
    }

    private void logPreferenceUpdate() { /* logging logic */ }
    private void sendEmailNotification(String message) { /* email logic */ }
    private void sendSMSNotification(String message) { /* SMS logic */ }
    private void sendPushNotification(String message) { /* push logic */ }
}

Usage Example - Putting It All Together

public class Main {
    public static void main(String[] args) {
        // Create CustomerManager with refactored structure
        CustomerManager customerManager = new CustomerManager("CUST002");

        // Same operations, but now delegated to appropriate classes
        customerManager.updatePersonalInfo("Jane", "Smith", "[email protected]");
        customerManager.updateAddress("456 Oak Ave", "Chicago", "IL", "60601", "USA");

        customerManager.addFunds(750.0);
        customerManager.processPayment(200.0);

        customerManager.addOrder("ORDER003", 120.0);
        customerManager.addOrder("ORDER004", 80.0);

        customerManager.updateNotificationPreferences(true, true, false);

        System.out.println("Account Balance: $" + customerManager.getAccountBalance());
        System.out.println("Loyalty Points: " + customerManager.getLoyaltyPoints());
    }
}

Expected Output:

Personal info updated for customer: CUST002
Address updated for customer: CUST002
Transaction logged: $750.0
Email sent: Account balance updated
Transaction logged: $200.0
Email sent: Payment processed successfully
Email sent: Order ORDER003 confirmed
Email sent: Order ORDER004 confirmed
Notification preferences updated
Account Balance: $550.0
Loyalty Points: 20

Benefits of Extract Class

Benefit

Description

Single Responsibility

Each class now has a single, well-defined responsibility, making them easier to understand and maintain.

Improved Testability

Smaller, focused classes are easier to test in isolation with fewer dependencies and edge cases.

Better Reusability

Extracted classes can be reused in other contexts without bringing unnecessary dependencies.

When to Apply Extract Class Refactoring

• When classes have too many fields and methods (typically more than 20-30 methods).

• When classes have multiple reasons to change (violating Single Responsibility Principle).

• When classes contain groups of related methods that could be logically separated.

• When classes are difficult to understand due to their size and complexity.

• When classes have low cohesion where methods don't work together toward a common purpose.

Apply Extract Class refactoring to one large class in your current project today. Start with the class that has the most obvious distinct responsibilities.

Repository & Resources

Complete Code Examples: Clean Code Repository

Find the complete implementation of Large Class refactoring and other clean code techniques in our dedicated repository. Each example includes:

• Before and after code comparisons

• Unit tests demonstrating the improvements

Found this helpful? Share it with a colleague who's struggling with Large Classes. Got questions? We'd love to hear from you at [email protected]

This pattern is essential for building resilient microservices architectures where service dependencies can fail independently. By implementing intelligent circuit protection, you can maintain system stability even when individual services experience issues.

This guide walks you through the Circuit Breaker pattern from concept to production ready implementation, covering state management, fallback strategies, and real world deployment patterns.

• Understanding the Circuit Breaker Pattern

• Implementing the Circuit Breaker Pattern

• When to Use Circuit Breaker Pattern

• Production Deployment Considerations

Understanding the Circuit Breaker Pattern

The Circuit Breaker pattern monitors the health of external services and automatically prevents calls to failing services. It operates in three distinct states, each serving a specific purpose in maintaining system resilience.

Circuit Breaker States

Circuit Breaker States

Key Benefits

• Prevents Cascading Failures: Stops unhealthy services from affecting the entire system

• Fast Failure Detection: Immediately identifies and isolates failing services

• Automatic Recovery: Tests service health and automatically recovers when services are restored

• Resource Protection: Prevents resource exhaustion from repeated failed calls

• Graceful Degradation: Provides fallback mechanisms during service outages

Implementing the Circuit Breaker Pattern

Let's build a comprehensive circuit breaker implementation that handles various failure scenarios and provides monitoring capabilities.

Implementation Overview

• Circuit Breaker Class: Simple circuit breaker with three states and failure tracking

• Shipment Service Example: Real-world shipment booking with fallback handling

• Supporting Classes: Basic data models for demonstration

Circuit Breaker Implementation

Define the Circuit States

public enum CircuitState {
    CLOSED,     // Normal operation - requests pass through
    OPEN,       // Too many failures - requests are blocked
    HALF_OPEN   // Testing if service recovered
}

Create a Response Model

public class ShipmentResponse {
    private final boolean success;
    private final String message;
    private final String trackingNumber;

    public ShipmentResponse(boolean success, String message, String trackingNumber) {
        this.success = success;
        this.message = message;
        this.trackingNumber = trackingNumber;
    }
}

Create the Circuit Breaker

public class CircuitBreaker {
    private final int failureThreshold;        // Max failures before opening
    private final long timeoutDuration;        // Wait time before testing recovery
    private int failureCount = 0;
    private CircuitState state = CircuitState.CLOSED;
    private long lastFailureTime = 0;

    public CircuitBreaker(int failureThreshold, long timeoutDuration) {
        this.failureThreshold = failureThreshold;
        this.timeoutDuration = timeoutDuration;
    }

    public ShipmentResponse executeShipment(ShipmentOperation operation) throws Exception {
        // Check if circuit is OPEN
        if (state == CircuitState.OPEN) {
            if (shouldAttemptReset()) {
                state = CircuitState.HALF_OPEN;
            } else {
                throw new CircuitBreakerOpenException("Service unavailable");
            }
        }

        try {
            ShipmentResponse result = operation.process();
            onSuccess();
            return result;
        } catch (Exception e) {
            onFailure();
            throw e;
        }
    }

    private boolean shouldAttemptReset() {
        return System.currentTimeMillis() - lastFailureTime > timeoutDuration;
    }

    private void onSuccess() {
        if (state == CircuitState.HALF_OPEN) {
            // Service recovered - close the circuit
            failureCount = 0;
            state = CircuitState.CLOSED;
        }
    }

    private void onFailure() {
        failureCount++;
        lastFailureTime = System.currentTimeMillis();

        if (failureCount >= failureThreshold) {
            state = CircuitState.OPEN;
        }
    }

    public CircuitState getState() {
        return state;
    }
}

// Functional interface for shipment operations
interface ShipmentOperation {
    ShipmentResponse process() throws Exception;
}

class CircuitBreakerOpenException extends Exception {
    public CircuitBreakerOpenException(String message) {
        super(message);
    }
}

Practical Example: Shipment Service

Shipment Service with Circuit Breaker

public class ShipmentService {
    private final CircuitBreaker circuitBreaker;
    private final ShipmentProvider shipmentProvider;

    public ShipmentService() {
        // Circuit opens after 5 failures, waits 30 seconds before retry
        this.circuitBreaker = new CircuitBreaker(5, 30000);
        this.shipmentProvider = new ShipmentProvider();
    }

    public ShipmentResponse createShipment(String orderId, String destination, double weight) {
        try {
            // Execute shipment through circuit breaker
            ShipmentResponse response = circuitBreaker.executeShipment(() -> {
                return shipmentProvider.createShipment(orderId, destination, weight);
            });
            return response;
        } catch (CircuitBreakerOpenException e) {
            // Circuit is open - service unavailable
            return new ShipmentResponse(false,
                "Shipment service temporarily unavailable. Please try again later.",
                null);
        } catch (Exception e) {
            // Shipment failed
            return new ShipmentResponse(false,
                "Shipment creation failed: " + e.getMessage(),
                null);
        }
    }
}

Shipment Provider (External Service)

public class ShipmentProvider {
    public ShipmentResponse createShipment(String orderId, String destination, double weight) throws Exception {
        // Simulate network delay
        Thread.sleep(100);

        // Simulate random failures (30% chance)
        if (Math.random() < 0.3) {
            throw new Exception("Shipment provider API timeout");
        }

        // Generate tracking number
        String trackingNumber = "TRK-" + System.currentTimeMillis();
        return new ShipmentResponse(true,
            "Shipment created to " + destination + " (" + weight + " kg)",
            trackingNumber);
    }
}

Putting It All Together

public class Main {
    public static void main(String[] args) {
        ShipmentService shipmentService = new ShipmentService();

        // Create multiple shipments
        for (int i = 1; i <= 10; i++) {
            ShipmentResponse response = shipmentService.createShipment(
                "ORDER-" + i,
                "New York, NY",
                2.5);

            System.out.println("Shipment " + i + ":");
            System.out.println("  Success: " + response.isSuccess());
            System.out.println("  Message: " + response.getMessage());
            System.out.println("  Tracking Number: " + response.getTrackingNumber());
            System.out.println();

            try {
                Thread.sleep(500); // Wait between requests
            } catch (InterruptedException e) {
                e.printStackTrace();
            }
        }
    }
}

Example Output:

Shipment 1:
  Success: true
  Message: Shipment created to New York, NY (2.5 kg)
  Tracking Number: TRK-1234567890123

Shipment 2:
  Success: false
  Message: Shipment creation failed: Shipment provider API timeout
  Tracking Number: null

Shipment 3:
  Success: false
  Message: Shipment creation failed: Shipment provider API timeout
  Tracking Number: null

Shipment 4:
  Success: true
  Message: Shipment created to New York, NY (2.5 kg)
  Tracking Number: TRK-1234567890456

Shipment 5:
  Success: false
  Message: Shipment creation failed: Shipment provider API timeout
  Tracking Number: null

Shipment 6:
  Success: false
  Message: Shipment service temporarily unavailable. Please try again later.
  Tracking Number: null

... (circuit stays open for 30 seconds)

When to Use Circuit Breaker Pattern

Understanding when to apply the Circuit Breaker pattern is crucial for making the right architectural decisions. Here's when it shines and when alternatives might be better:

✅ Ideal Scenarios:

• Your application depends on external services that can fail or become slow.

• You need to prevent cascading failures across microservices.

• You want to fail fast instead of waiting for timeouts on failing services.

• You need to protect critical operations from resource exhaustion.

• You're building distributed systems with multiple service dependencies.

• You want automatic recovery testing when services become healthy again.

❌ Skip It When:

• Your application has no external dependencies or service calls.

• The overhead of circuit breaker management outweighs benefits.

• You need guaranteed delivery for every single request (use queues instead).

• Your services have predictable, stable behaviour with no failure scenarios.

• The added complexity doesn't justify the resilience benefits for your use case.

Production Deployment Considerations

1. Thread Safety for Concurrent Access

For production applications handling concurrent requests, use thread safe variables (AtomicInteger, AtomicLong) instead of regular primitives to prevent race conditions when multiple threads access the circuit breaker simultaneously.

2. Configuration and Monitoring

Choose appropriate failure thresholds and timeout durations based on service criticality, and add comprehensive logging to track circuit state changes, failure counts, and recovery events for diagnosing issues in production.

3. Fallback Strategies

When the circuit is open, provide meaningful fallback responses such as cached data, default values, or user-friendly error messages instead of just throwing exceptions to maintain graceful degradation.

The Circuit Breaker pattern is fundamental to building resilient distributed systems. By implementing intelligent circuit protection with proper monitoring and fallback strategies, you can prevent cascading failures and maintain system stability even when individual services experience issues.

Found this helpful? Share it with a colleague who's struggling with cascading failures in their microservices architecture. Got questions? We'd love to hear from you at [email protected]

We will see how we can refactor using the Replace Primitive with Object technique for better domain modeling and type safety.

❝

⚠️ Code Smell: Primitive Obsession
✅ Refactoring: Replace Primitive with Object
🎯 Goal: Rich domain models with meaningful types

The Primitive Obsession code smell occurs when primitive types (strings, numbers, booleans) are used to represent domain concepts instead of creating dedicated objects. The Replace Primitive with Object refactoring technique replaces these primitives with meaningful objects that better represent the domain and provide type safety.

The Code Smell: Primitive Obsession

Primitive Obsession is a subtle but important code smell that reduces the expressiveness of your domain model. When you use primitive types to represent domain concepts, you lose the opportunity to encapsulate related behaviour and make your code more self-documenting. This leads to scattered validation logic and makes the code harder to understand and maintain.

Symptoms

Impact

Primitive types used for domain concepts

Reduced expressiveness

Scattered validation logic

Poor domain modeling

Type confusion and errors

Higher bug risk

Here's a typical example of Primitive Obsession:

public class User {
    private String email;
    private String phoneNumber;
    private String zipCode;
    private double salary;
    private String status;

    public User(String email, String phoneNumber, String zipCode,
                double salary, String status) {
        this.email = email;
        this.phoneNumber = phoneNumber;
        this.zipCode = zipCode;
        this.salary = salary;
        this.status = status;
    }

    public boolean isValidEmail() {
        return email != null && email.contains("@") && email.contains(".");
    }

    public boolean isValidPhoneNumber() {
        return phoneNumber != null && phoneNumber.matches("\\+?[1-9]\\d{1,14}");
    }

    public boolean isValidZipCode() {
        return zipCode != null && zipCode.matches("\\d{5}(-\\d{4})?");
    }

    public boolean isActive() {
        return "ACTIVE".equals(status);
    }
}

In this example, the User class uses primitive types like String for email, phone number, zip code, and status, and double for salary. This creates several problems: validation logic is scattered, there's no type safety, and the domain concepts are not clearly expressed.

The Refactoring: Replace Primitive with Object

The Replace Primitive with Object refactoring technique creates dedicated objects to represent domain concepts, encapsulating related behaviour and providing type safety. This makes the code more expressive and easier to maintain.

Step by Step Refactoring Process:

1. Identify primitive types that represent domain concepts.

2. Create dedicated classes for each domain concept.

3. Move validation logic into the new classes.

4. Replace primitive fields with the new objects.

5. Update methods to work with the new objects.

Here's the refactored version:

// User class now uses meaningful objects
public class User {
    private Email email;
    private PhoneNumber phoneNumber;
    private ZipCode zipCode;
    private Money salary;
    private UserStatus status;

    public User(Email email, PhoneNumber phoneNumber, ZipCode zipCode,
                Money salary, UserStatus status) {
        this.email = email;
        this.phoneNumber = phoneNumber;
        this.zipCode = zipCode;
        this.salary = salary;
        this.status = status;
    }

    public boolean isActive() {
        return status.isActive();
    }
}

// Dedicated class for email with validation
public class Email {
    private final String value;

    public Email(String email) {
        if (!isValid(email)) {
            throw new IllegalArgumentException("Invalid email format: " + email);
        }
        this.value = email;
    }

    private boolean isValid(String email) {
        return email != null && email.contains("@") && email.contains(".");
    }

    public String getValue() {
        return value;
    }

    public String getDomain() {
        return value.substring(value.indexOf("@") + 1);
    }
}

// Dedicated class for phone numbers
public class PhoneNumber {
    private final String value;

    public PhoneNumber(String phoneNumber) {
        if (!isValid(phoneNumber)) {
            throw new IllegalArgumentException("Invalid phone number format: " + phoneNumber);
        }
        this.value = phoneNumber;
    }

    private boolean isValid(String phoneNumber) {
        return phoneNumber != null && phoneNumber.matches("\\+?[1-9]\\d{1,14}");
    }

    public String getValue() {
        return value;
    }

    public String getCountryCode() {
        if (value.startsWith("+")) {
            return value.substring(1, 3);
        }
        return "US"; // Default assumption
    }
}

// Dedicated class for zip codes
public class ZipCode {
    private final String value;

    public ZipCode(String zipCode) {
        if (!isValid(zipCode)) {
            throw new IllegalArgumentException("Invalid zip code format: " + zipCode);
        }
        this.value = zipCode;
    }

    private boolean isValid(String zipCode) {
        return zipCode != null && zipCode.matches("\\d{5}(-\\d{4})?");
    }

    public String getValue() {
        return value;
    }
}

// Dedicated class for money
public class Money {
    private final double amount;

    public Money(double amount) {
        if (amount < 0) {
            throw new IllegalArgumentException("Amount cannot be negative");
        }
        this.amount = amount;
    }

    public double getAmount() {
        return amount;
    }

    public String getFormattedAmount() {
        return String.format("$%.2f", amount);
    }
}

// Enum for user status
public enum UserStatus {
    ACTIVE, INACTIVE, SUSPENDED, PENDING;
    
    public boolean isActive() {
        return this == ACTIVE;
    }
}

Benefits of Replace Primitive with Object

Benefit

Description

Rich Domain Model

Objects represent domain concepts clearly, making the code more expressive and self-documenting.

Type Safety

Compile-time type checking prevents errors and makes the code more robust.

Encapsulated behaviour

Related validation and business logic is encapsulated within the appropriate objects.

When to Apply Replace Primitive with Object Refactoring

• Primitive types used to represent domain concepts (email, phone, money, etc.).

• Scattered validation logic for the same primitive type.

• Multiple parameters of the same primitive type that could be confused.

• Business logic that operates on primitive values.

• When you want to make your domain model more expressive and type-safe.

Repository & Resources

Complete Code Examples: Clean Code Repository

Find the complete implementation of Primitive Obsession refactoring and other clean code techniques in our dedicated repository. Each example includes:

• Before and after code comparisons

• Unit tests demonstrating the improvements

Found this helpful? Share it with a colleague who's struggling with Primitive Obsession. Got questions? We'd love to hear from you at [email protected]

Picture this: You're building a music playlist application that needs to support different types of collections: regular playlists, shuffled playlists, and recently played tracks. Your initial approach seems logical: create different methods for each collection type to access their elements.

But then requirements expand: "We need to support playlists with different sorting orders, filtered playlists, and playlists that combine multiple sources. Also, users want to be able to skip forward, go backward, and jump to specific positions in any playlist type."

Suddenly, you're creating different traversal methods for each collection type, making your code inconsistent and hard to maintain. Adding new collection types means creating new traversal logic, and clients need to know the specific implementation details of each collection. Sound familiar?

The Iterator pattern solves this by providing a way to access the elements of an aggregate object sequentially without exposing its underlying representation.

Understanding the Iterator Pattern

The Iterator pattern provides a way to access the elements of an aggregate object sequentially without exposing its underlying representation. It encapsulates the traversal logic and provides a consistent interface for iterating over different types of collections.

Think of it like a universal remote control for different types of media players: whether you're playing a CD, streaming music, or listening to a radio station, the remote provides the same buttons (play, pause, next, previous) even though the underlying mechanisms are completely different.

This pattern promotes Encapsulation, Consistency, and Flexibility while hiding the complexity of different collection implementations.

Iterator Pattern Components

Core Components

• Iterator Interface: Defines the interface for accessing and traversing elements

• Concrete Iterator: Implements the iterator interface and keeps track of the current position

• Aggregate Interface: Defines the interface for creating an iterator object

• Concrete Aggregate: Implements the aggregate interface and returns an appropriate iterator

Complete Java Implementation

Let's build a music playlist system that demonstrates the Iterator pattern's power in providing consistent collection traversal.

Iterator Interface

public interface SongIterator {
    boolean hasNext();
    Song next();
    Song current();
    void reset();
}

public class Song {
    private String title;
    private String artist;
    private String genre;

    public Song(String title, String artist, String genre) {
        this.title = title;
        this.artist = artist;
        this.genre = genre;
    }

    public String getTitle() { return title; }
    public String getArtist() { return artist; }
    public String getGenre() { return genre; }

    @Override
    public String toString() {
        return String.format("%s by %s [%s]", title, artist, genre);
    }
}

Aggregate Interface

public interface Playlist {
    SongIterator createIterator();
    void addSong(Song song);
    void removeSong(Song song);
    String getPlaylistName();
    int getSongCount();
}

Concrete Iterator

public class ShuffledPlaylistIterator implements SongIterator {
    private List<Song> songs;
    private int currentIndex;
    
    public ShuffledPlaylistIterator(List<Song> songs) {
        this.songs = new ArrayList<>(songs);
        shuffleSongs();
        this.currentIndex = 0;
    }
    
    private void shuffleSongs() {
        Collections.shuffle(songs);
    }
    
    @Override
    public boolean hasNext() {
        return currentIndex < songs.size();
    }
    
    @Override
    public Song next() {
        if (hasNext()) {
            return songs.get(currentIndex++);
        }
        return null;
    }
    
    @Override
    public Song current() {
        if (currentIndex > 0 && currentIndex <= songs.size()) {
            return songs.get(currentIndex - 1);
        }
        return null;
    }
    
    @Override
    public void reset() {
        shuffleSongs(); // Reshuffle on reset
        currentIndex = 0;
    }
}

public class FilteredPlaylistIterator implements SongIterator {
    private List<Song> filteredSongs;
    private int currentIndex;
    
    public FilteredPlaylistIterator(List<Song> songs, String filterGenre) {
        this.filteredSongs = songs.stream()
            .filter(song -> song.getGenre().equalsIgnoreCase(filterGenre))
            .collect(Collectors.toList());
        this.currentIndex = 0;
    }
    
    @Override
    public boolean hasNext() {
        return currentIndex < filteredSongs.size();
    }
    
    @Override
    public Song next() {
        if (hasNext()) {
            return filteredSongs.get(currentIndex++);
        }
        return null;
    }
    
    @Override
    public Song current() {
        if (currentIndex > 0 && currentIndex <= filteredSongs.size()) {
            return filteredSongs.get(currentIndex - 1);
        }
        return null;
    }
    
    @Override
    public void reset() {
        currentIndex = 0;
    }
}

Concrete Aggregate

public class ShuffledPlaylist implements Playlist {
    private String name;
    private List<Song> songs;
    
    public ShuffledPlaylist(String name) {
        this.name = name;
        this.songs = new ArrayList<>();
    }
    
    @Override
    public SongIterator createIterator() {
        return new ShuffledPlaylistIterator(songs);
    }
    
    @Override
    public void addSong(Song song) {
        songs.add(song);
    }
    
    @Override
    public void removeSong(Song song) {
        songs.remove(song);
    }
    
    @Override
    public String getPlaylistName() {
        return name;
    }
    
    @Override
    public int getSongCount() {
        return songs.size();
    }
}

public class FilteredPlaylist implements Playlist {
    private String name;
    private List<Song> songs;
    private String filterGenre;
    
    public FilteredPlaylist(String name, String filterGenre) {
        this.name = name;
        this.songs = new ArrayList<>();
        this.filterGenre = filterGenre;
    }
    
    @Override
    public SongIterator createIterator() {
        return new FilteredPlaylistIterator(songs, filterGenre);
    }
    
    @Override
    public void addSong(Song song) {
        songs.add(song);
    }
    
    @Override
    public void removeSong(Song song) {
        songs.remove(song);
    }
    
    @Override
    public String getPlaylistName() {
        return name + " (Filtered: " + filterGenre + ")";
    }
    
    @Override
    public int getSongCount() {
        return (int) songs.stream()
            .filter(song -> song.getGenre().equalsIgnoreCase(filterGenre))
            .count();
    }
}

Client

public class MusicPlayer {
    private Playlist currentPlaylist;
    private SongIterator iterator;
    private int songsPlayed;

    public void loadPlaylist(Playlist playlist) {
        this.currentPlaylist = playlist;
        this.iterator = playlist.createIterator();
        this.songsPlayed = 0;
        System.out.println("Loaded playlist: " + playlist.getPlaylistName());
        System.out.println("Total songs: " + playlist.getSongCount());
    }

    public void playNext() {
        if (iterator != null && iterator.hasNext()) {
            Song song = iterator.next();
            songsPlayed++;
            System.out.println("Now playing: " + song);
            System.out.println("Progress: " + songsPlayed + "/" + currentPlaylist.getSongCount());
        } else {
            System.out.println("End of playlist reached");
        }
    }

    public void showCurrentSong() {
        if (iterator != null) {
            Song current = iterator.current();
            if (current != null) {
                System.out.println("Current song: " + current);
            } else {
                System.out.println("No song currently playing");
            }
        }
    }

    public void resetPlaylist() {
        if (iterator != null) {
            iterator.reset();
            songsPlayed = 0;
            System.out.println("Playlist reset to beginning");
        }
    }

    public void showPlaylistInfo() {
        if (currentPlaylist != null) {
            System.out.println("Playlist: " + currentPlaylist.getPlaylistName());
            System.out.println("Songs: " + currentPlaylist.getSongCount());
        }
    }
}

public class MusicPlayerDemo {
    public static void main(String[] args) {
        // Create sample songs
        List<Song> sampleSongs = Arrays.asList(
            new Song("Bohemian Rhapsody", "Queen", "Rock"),
            new Song("Imagine", "John Lennon", "Pop"),
            new Song("Hotel California", "Eagles", "Rock")
        );

        MusicPlayer player = new MusicPlayer();

        System.out.println("=== Music Player Iterator Pattern Demo ===\n");

        // Test Shuffled Playlist
        System.out.println("1. Shuffled Playlist:");
        System.out.println("====================");
        ShuffledPlaylist shuffledPlaylist = new ShuffledPlaylist("Shuffled Mix");
        sampleSongs.forEach(shuffledPlaylist::addSong);

        player.loadPlaylist(shuffledPlaylist);
        player.playNext();
        player.playNext();
        player.showCurrentSong();

        // Test Filtered Playlist
        System.out.println("\n2. Filtered Playlist (Rock only):");
        System.out.println("=================================");
        FilteredPlaylist rockPlaylist = new FilteredPlaylist("Rock Collection", "Rock");
        sampleSongs.forEach(rockPlaylist::addSong);

        player.loadPlaylist(rockPlaylist);
        player.playNext();
        player.playNext();

        // Test reset functionality
        System.out.println("\n3. Reset and Replay:");
        System.out.println("===================");
        player.resetPlaylist();
        player.playNext();
    }
}

Expected Output:

=== Music Player Iterator Pattern Demo ===

1. Shuffled Playlist:
====================
Loaded playlist: Shuffled Mix
Total songs: 3
Now playing: Hotel California by Eagles [Rock]
Progress: 1/3
Now playing: Imagine by John Lennon [Pop]
Progress: 2/3
Current song: Imagine by John Lennon [Pop]

2. Filtered Playlist (Rock only):
=================================
Loaded playlist: Rock Collection (Filtered: Rock)
Total songs: 2
Now playing: Bohemian Rhapsody by Queen [Rock]
Progress: 1/2
Now playing: Hotel California by Eagles [Rock]
Progress: 2/2

3. Reset and Replay:
===================
Playlist reset to beginning
Now playing: Bohemian Rhapsody by Queen [Rock]
Progress: 1/2

🚀 Get the Complete Implementation

The full code with advanced iterator implementations and collection management is available in our Design Patterns Repository.

# Clone and run the complete demo
git clone https://github.com/shift-elevate/design-patterns.git
cd design-patterns
mvn test -Dtest=IteratorPatternTest

Real World Examples

The Iterator pattern is extensively used in real world applications:

1. Java Collections Framework

Java's Collections Framework uses the Iterator pattern extensively. The Iterator interface provides a consistent way to traverse different types of collections (ArrayList, LinkedList, HashSet, etc.) without exposing their internal structure.

2. Database Result Sets

Database APIs use the Iterator pattern for result sets, allowing applications to traverse query results without knowing the specific database implementation or result set structure.

3. File System Traversal

File system APIs use the Iterator pattern to traverse directories and files, providing a consistent interface regardless of the underlying file system implementation.

When to Use the Iterator Pattern

Understanding when to apply the Iterator pattern is crucial for making the right architectural decisions. Here's when it shines and when alternatives might be better:

✅ Ideal Scenarios:

• You need to traverse different types of collections in a uniform way.

• You want to hide the complexity of different collection implementations from clients.

• You need to support multiple traversal algorithms for the same collection.

• You want to provide a consistent interface for accessing collection elements.

❌ Skip It When:

• The collection is simple and unlikely to change.

• You need random access to collection elements.

• The overhead of creating iterator objects is too high for your use case.

Next Steps: Apply Iterator Pattern in Your Project

Ready to implement the Iterator pattern in your own projects? Here's a structured approach to get you started:

1. Identify Collection Types: Look for areas where you have different types of collections that need to be traversed.

2. Define Iterator Interface: Create a common interface for traversing all collection types.

3. Implement Concrete Iterators: Build specific iterators for each collection type.

4. Create Aggregate Interface: Define an interface for creating appropriate iterators.

5. Test Consistent Traversal: Ensure all collection types can be traversed using the same interface.

The Iterator pattern transforms inconsistent collection access into uniform, maintainable traversal mechanisms. By providing a consistent iterator interface, you build systems that are easier to use and extend, regardless of the underlying collection implementation.

Found this helpful? Share it with a colleague who's struggling with inconsistent collection access. Got questions? We'd love to hear from you at [email protected]