Builder Pattern

The Builder pattern solves the problem of creating complex objects with many optional parameters.

The Problem

// Constructor with too many parameters
public User(String name, String email, int age, String phone,
            String address, String city, String state, String zip,
            Role role, List<String> permissions, Date createdAt,
            boolean active) { ... }

// Which parameter is which?
User user = new User("John", "john@email.com", 30, null,
                    "123 Main St", "NYC", "NY", "10001",
                    Role.ADMIN, null, null, true);
// Is null the phone or permissions?

The Solution

User user = new User.Builder()
    .name("John")
    .email("john@email.com")
    .age(30)
    .address("123 Main St")
    .city("NYC")
    .state("NY")
    .zip("10001")
    .role(Role.ADMIN)
    .active(true)
    .build();

Why Builder Matters

1. Readability: Named parameters are self-documenting
2. Flexibility: Only set parameters you need
3. Immutability: Can create immutable objects with builders
4. Validation: Validate during build, not in constructor
5. Reduced errors: No parameter order confusion

A complete Builder implementation with validation and immutability.

Standard Builder

public class User {
    private final String name;       // Required
    private final String email;      // Required
    private final int age;           // Optional
    private final String phone;      // Optional
    private final String address;    // Optional
    
    // Private constructor takes builder
    private User(Builder builder) {
        this.name = builder.name;
        this.email = builder.email;
        this.age = builder.age;
        this.phone = builder.phone;
        this.address = builder.address;
    }
    
    // Getters only (immutable)
    public String getName() { return name; }
    public String getEmail() { return email; }
    public int getAge() { return age; }
    
    // Static nested Builder class
    public static class Builder {
        // Required parameters
        private final String name;
        private final String email;
        
        // Optional parameters with defaults
        private int age = 0;
        private String phone = null;
        private String address = null;
        
        public Builder(String name, String email) {
            this.name = name;
            this.email = email;
        }
        
        public Builder age(int age) {
            this.age = age;
            return this;  // Return this for chaining
        }
        
        public Builder phone(String phone) {
            this.phone = phone;
            return this;
        }
        
        public Builder address(String address) {
            this.address = address;
            return this;
        }
        
        public User build() {
            // Validation
            if (name == null || name.isEmpty()) {
                throw new IllegalStateException("Name is required");
            }
            if (!email.contains("@")) {
                throw new IllegalStateException("Invalid email");
            }
            return new User(this);
        }
    }
}

Usage

User user = new User.Builder("John", "john@email.com")
    .age(30)
    .phone("555-1234")
    .address("123 Main St")
    .build();

Validation in Builder

public User build() {
    // Validate required fields
    Objects.requireNonNull(name, "Name cannot be null");
    Objects.requireNonNull(email, "Email cannot be null");
    
    // Validate business rules
    if (age < 0 || age > 150) {
        throw new IllegalArgumentException("Invalid age: " + age);
    }
    
    if (!email.matches("^[A-Za-z0-9+_.-]+@(.+)$")) {
        throw new IllegalArgumentException("Invalid email format");
    }
    
    return new User(this);
}

Fluent interfaces make builders readable through method chaining.

Fluent Interface Basics

// Each method returns 'this' for chaining
public class QueryBuilder {
    private String table;
    private List<String> conditions = new ArrayList<>();
    private List<String> orderBy = new ArrayList<>();
    private Integer limit;
    
    public QueryBuilder from(String table) {
        this.table = table;
        return this;
    }
    
    public QueryBuilder where(String condition) {
        conditions.add(condition);
        return this;
    }
    
    public QueryBuilder orderBy(String column) {
        orderBy.add(column);
        return this;
    }
    
    public QueryBuilder limit(int limit) {
        this.limit = limit;
        return this;
    }
    
    public String build() {
        StringBuilder sb = new StringBuilder("SELECT * FROM ").append(table);
        if (!conditions.isEmpty()) {
            sb.append(" WHERE ").append(String.join(" AND ", conditions));
        }
        if (!orderBy.isEmpty()) {
            sb.append(" ORDER BY ").append(String.join(", ", orderBy));
        }
        if (limit != null) {
            sb.append(" LIMIT ").append(limit);
        }
        return sb.toString();
    }
}

// Usage
String query = new QueryBuilder()
    .from("users")
    .where("age > 18")
    .where("active = true")
    .orderBy("name")
    .limit(10)
    .build();

Java Standard Library Builders

// StringBuilder
String result = new StringBuilder()
    .append("Hello")
    .append(" ")
    .append("World")
    .toString();

// Stream builder
Stream<String> stream = Stream.<String>builder()
    .add("a")
    .add("b")
    .add("c")
    .build();

// ProcessBuilder
Process process = new ProcessBuilder()
    .command("ls", "-la")
    .directory(new File("/tmp"))
    .redirectErrorStream(true)
    .start();

Fluent Interface with Validation

public class ServerBuilder {
    private String host;
    private int port;
    private Duration timeout;
    private int maxRetries;
    
    public ServerBuilder host(String host) {
        this.host = Objects.requireNonNull(host);
        return this;
    }
    
    public ServerBuilder port(int port) {
        if (port < 1 || port > 65535) {
            throw new IllegalArgumentException("Invalid port");
        }
        this.port = port;
        return this;
    }
    
    public ServerBuilder timeout(Duration timeout) {
        this.timeout = Objects.requireNonNull(timeout);
        return this;
    }
    
    public ServerBuilder maxRetries(int maxRetries) {
        if (maxRetries < 0) {
            throw new IllegalArgumentException("Max retries cannot be negative");
        }
        this.maxRetries = maxRetries;
        return this;
    }
    
    public Server build() {
        // Validate required fields
        Objects.requireNonNull(host, "Host is required");
        if (port == 0) throw new IllegalStateException("Port is required");
        return new Server(this);
    }
}