Builder Pattern in Java

Introduction

Imagine you're ordering a custom pizza. You don't just say "I want a pizza"—you specify the size, crust type, sauce, cheese, and toppings. Some options are required (size), while others are optional (extra olives). The Builder Pattern is like having a smart pizza chef who helps you construct complex objects step by step, handling all the combinations and validations for you.

It's a creational design pattern that separates the construction of a complex object from its representation, allowing the same construction process to create different representations.

What is the Builder Pattern?

The Builder Pattern solves the problem of creating objects with many optional parameters or complex configuration. Instead of using telescoping constructors (multiple constructors with different parameters) or JavaBeans with setters (which can leave objects in inconsistent states), it provides a fluent way to construct objects.

Key Characteristics:

✅ Step-by-step construction - Build complex objects gradually
✅ Fluent interface - Method chaining for readable code
✅ Immutability - Can create immutable objects
✅ Validation - Can validate parameters before object creation
✅ Multiple representations - Same builder can create different object variations

Code Explanation with Examples

Example 1: The Problem - Telescoping Constructors

// ❌ PROBLEM: Telescoping constructors - confusing and hard to maintain class Pizza { private String size; // Required private String crust; // Required private boolean cheese; // Optional private boolean pepperoni; // Optional private boolean mushrooms; // Optional private boolean onions; // Optional // Multiple constructors for different combinations - MESSY! public Pizza(String size, String crust) { this(size, crust, false, false, false, false); } public Pizza(String size, String crust, boolean cheese) { this(size, crust, cheese, false, false, false); } public Pizza(String size, String crust, boolean cheese, boolean pepperoni) { this(size, crust, cheese, pepperoni, false, false); } public Pizza(String size, String crust, boolean cheese, boolean pepperoni, boolean mushrooms, boolean onions) { this.size = size; this.crust = crust; this.cheese = cheese; this.pepperoni = pepperoni; this.mushrooms = mushrooms; this.onions = onions; } // Getters... } // Usage: Confusing which constructor to use Pizza pizza1 = new Pizza("Large", "Thin"); Pizza pizza2 = new Pizza("Medium", "Thick", true, true, false, true); // Hard to read!

Example 2: Basic Builder Pattern Implementation

// ✅ SOLUTION: Using Builder Pattern class Pizza { // Required parameters private final String size; private final String crust; // Optional parameters private final boolean cheese; private final boolean pepperoni; private final boolean mushrooms; private final boolean onions; // Private constructor - only Builder can create Pizza private Pizza(PizzaBuilder builder) { this.size = builder.size; this.crust = builder.crust; this.cheese = builder.cheese; this.pepperoni = builder.pepperoni; this.mushrooms = builder.mushrooms; this.onions = builder.onions; } // Getters public String getSize() { return size; } public String getCrust() { return crust; } public boolean hasCheese() { return cheese; } public boolean hasPepperoni() { return pepperoni; } public boolean hasMushrooms() { return mushrooms; } public boolean hasOnions() { return onions; } @Override public String toString() { return String.format("Pizza[size=%s, crust=%s, cheese=%s, pepperoni=%s, mushrooms=%s, onions=%s]", size, crust, cheese, pepperoni, mushrooms, onions); } // Static Builder class public static class PizzaBuilder { // Required parameters private final String size; private final String crust; // Optional parameters - initialized to default values private boolean cheese = false; private boolean pepperoni = false; private boolean mushrooms = false; private boolean onions = false; // Builder constructor with required fields public PizzaBuilder(String size, String crust) { this.size = size; this.crust = crust; } // Methods for optional parameters (return Builder for method chaining) public PizzaBuilder withCheese() { this.cheese = true; return this; } public PizzaBuilder withPepperoni() { this.pepperoni = true; return this; } public PizzaBuilder withMushrooms() { this.mushrooms = true; return this; } public PizzaBuilder withOnions() { this.onions = true; return this; } // Build method - creates the actual Pizza object public Pizza build() { return new Pizza(this); } } } // Usage: Clean and readable! public class PizzaDemo { public static void main(String[] args) { // Build different pizza combinations easily Pizza margherita = new Pizza.PizzaBuilder("Large", "Thin") .withCheese() .build(); Pizza supreme = new Pizza.PizzaBuilder("Medium", "Thick") .withCheese() .withPepperoni() .withMushrooms() .withOnions() .build(); Pizza plain = new Pizza.PizzaBuilder("Small", "Regular") .build(); System.out.println(margherita); System.out.println(supreme); System.out.println(plain); } }

Output:

Pizza[size=Large, crust=Thin, cheese=true, pepperoni=false, mushrooms=false, onions=false] Pizza[size=Medium, crust=Thick, cheese=true, pepperoni=true, mushrooms=true, onions=true] Pizza[size=Small, crust=Regular, cheese=false, pepperoni=false, mushrooms=false, onions=false]

Example 3: Advanced Builder with Validation

import java.util.*; // Advanced Builder with validation and complex logic class Computer { private final String cpu; // Required private final int ram; // Required (in GB) private final int storage; // Required (in GB) private final String gpu; // Optional private final boolean bluetooth; // Optional private final List<String> accessories; // Optional private Computer(ComputerBuilder builder) { this.cpu = builder.cpu; this.ram = builder.ram; this.storage = builder.storage; this.gpu = builder.gpu; this.bluetooth = builder.bluetooth; this.accessories = builder.accessories; } // Getters public String getCpu() { return cpu; } public int getRam() { return ram; } public int getStorage() { return storage; } public String getGpu() { return gpu; } public boolean hasBluetooth() { return bluetooth; } public List<String> getAccessories() { return Collections.unmodifiableList(accessories); } @Override public String toString() { return String.format("Computer[CPU=%s, RAM=%dGB, Storage=%dGB, GPU=%s, Bluetooth=%s, Accessories=%s]", cpu, ram, storage, gpu, bluetooth, accessories); } // Builder class public static class ComputerBuilder { private final String cpu; private final int ram; private final int storage; private String gpu = "Integrated"; private boolean bluetooth = false; private List<String> accessories = new ArrayList<>(); public ComputerBuilder(String cpu, int ram, int storage) { // Validation in constructor if (cpu == null || cpu.trim().isEmpty()) { throw new IllegalArgumentException("CPU cannot be null or empty"); } if (ram < 4 || ram > 64) { throw new IllegalArgumentException("RAM must be between 4GB and 64GB"); } if (storage < 128 || storage > 2048) { throw new IllegalArgumentException("Storage must be between 128GB and 2TB"); } this.cpu = cpu; this.ram = ram; this.storage = storage; } public ComputerBuilder withGpu(String gpu) { this.gpu = gpu; return this; } public ComputerBuilder withBluetooth() { this.bluetooth = true; return this; } public ComputerBuilder addAccessory(String accessory) { this.accessories.add(accessory); return this; } public Computer build() { // Additional validation before building if (gpu == null) { throw new IllegalStateException("GPU cannot be null"); } return new Computer(this); } } } // Usage with validation public class ComputerDemo { public static void main(String[] args) { try { Computer gamingPC = new Computer.ComputerBuilder("Intel i9", 32, 1000) .withGpu("NVIDIA RTX 4080") .withBluetooth() .addAccessory("Gaming Mouse") .addAccessory("Mechanical Keyboard") .build(); Computer officePC = new Computer.ComputerBuilder("Intel i5", 16, 512) .withBluetooth() .addAccessory("Monitor") .build(); System.out.println("Gaming PC: " + gamingPC); System.out.println("Office PC: " + officePC); // This will throw exception due to validation Computer invalidPC = new Computer.ComputerBuilder("", 2, 50).build(); } catch (IllegalArgumentException e) { System.out.println("Validation error: " + e.getMessage()); } } }

Example 4: Real-World Student Object Builder

import java.time.LocalDate; import java.util.*; class Student { private final String studentId; // Required private final String firstName; // Required private final String lastName; // Required private final LocalDate birthDate; // Required private final String email; // Optional private final String phone; // Optional private final String address; // Optional private final List<String> courses; // Optional private final boolean scholarship; // Optional private final double gpa; // Optional private Student(StudentBuilder builder) { this.studentId = builder.studentId; this.firstName = builder.firstName; this.lastName = builder.lastName; this.birthDate = builder.birthDate; this.email = builder.email; this.phone = builder.phone; this.address = builder.address; this.courses = builder.courses; this.scholarship = builder.scholarship; this.gpa = builder.gpa; } // Getters public String getStudentId() { return studentId; } public String getFirstName() { return firstName; } public String getLastName() { return lastName; } public LocalDate getBirthDate() { return birthDate; } public String getEmail() { return email; } public String getPhone() { return phone; } public String getAddress() { return address; } public List<String> getCourses() { return Collections.unmodifiableList(courses); } public boolean hasScholarship() { return scholarship; } public double getGpa() { return gpa; } @Override public String toString() { return String.format("Student[ID=%s, Name=%s %s, Email=%s, GPA=%.2f, Courses=%s]", studentId, firstName, lastName, email, gpa, courses); } // Builder class public static class StudentBuilder { private final String studentId; private final String firstName; private final String lastName; private final LocalDate birthDate; private String email = "N/A"; private String phone = "N/A"; private String address = "N/A"; private List<String> courses = new ArrayList<>(); private boolean scholarship = false; private double gpa = 0.0; public StudentBuilder(String studentId, String firstName, String lastName, LocalDate birthDate) { this.studentId = studentId; this.firstName = firstName; this.lastName = lastName; this.birthDate = birthDate; } public StudentBuilder withEmail(String email) { this.email = email; return this; } public StudentBuilder withPhone(String phone) { this.phone = phone; return this; } public StudentBuilder withAddress(String address) { this.address = address; return this; } public StudentBuilder addCourse(String course) { this.courses.add(course); return this; } public StudentBuilder withScholarship() { this.scholarship = true; return this; } public StudentBuilder withGpa(double gpa) { if (gpa < 0.0 || gpa > 4.0) { throw new IllegalArgumentException("GPA must be between 0.0 and 4.0"); } this.gpa = gpa; return this; } public Student build() { // Validate email format if (email != null && !email.equals("N/A") && !email.contains("@")) { throw new IllegalStateException("Invalid email format"); } return new Student(this); } } } // Usage public class StudentDemo { public static void main(String[] args) { Student john = new Student.StudentBuilder("S12345", "John", "Doe", LocalDate.of(2000, 5, 15)) .withEmail("[email protected]") .withPhone("123-456-7890") .withGpa(3.8) .withScholarship() .addCourse("Computer Science") .addCourse("Mathematics") .addCourse("Physics") .build(); Student jane = new Student.StudentBuilder("S67890", "Jane", "Smith", LocalDate.of(1999, 8, 22)) .withEmail("[email protected]") .withGpa(3.9) .addCourse("Biology") .addCourse("Chemistry") .build(); System.out.println(john); System.out.println(jane); } }

Example 5: HTTP Request Builder (Real-World Scenario)

import java.util.*; // Real-world example: HTTP Request Builder class HttpRequest { private final String url; private final String method; private final Map<String, String> headers; private final String body; private final int timeout; private final boolean followRedirects; private HttpRequest(HttpRequestBuilder builder) { this.url = builder.url; this.method = builder.method; this.headers = Collections.unmodifiableMap(builder.headers); this.body = builder.body; this.timeout = builder.timeout; this.followRedirects = builder.followRedirects; } // Getters public String getUrl() { return url; } public String getMethod() { return method; } public Map<String, String> getHeaders() { return headers; } public String getBody() { return body; } public int getTimeout() { return timeout; } public boolean shouldFollowRedirects() { return followRedirects; } public void execute() { System.out.println("Executing HTTP Request:"); System.out.println(" URL: " + url); System.out.println(" Method: " + method); System.out.println(" Headers: " + headers); System.out.println(" Body: " + body); System.out.println(" Timeout: " + timeout + "ms"); System.out.println(" Follow Redirects: " + followRedirects); System.out.println("--- Request Sent ---"); } // Builder public static class HttpRequestBuilder { private final String url; private String method = "GET"; private Map<String, String> headers = new HashMap<>(); private String body = ""; private int timeout = 5000; private boolean followRedirects = true; public HttpRequestBuilder(String url) { this.url = url; } public HttpRequestBuilder withMethod(String method) { this.method = method.toUpperCase(); return this; } public HttpRequestBuilder withHeader(String key, String value) { this.headers.put(key, value); return this; } public HttpRequestBuilder withBody(String body) { this.body = body; return this; } public HttpRequestBuilder withTimeout(int timeout) { this.timeout = timeout; return this; } public HttpRequestBuilder dontFollowRedirects() { this.followRedirects = false; return this; } public HttpRequest build() { // Validate required fields if (url == null || url.trim().isEmpty()) { throw new IllegalStateException("URL is required"); } // Set Content-Type header if body is present and not already set if (body != null && !body.isEmpty() && !headers.containsKey("Content-Type")) { headers.put("Content-Type", "application/json"); } return new HttpRequest(this); } } } // Usage public class HttpRequestDemo { public static void main(String[] args) { // GET request HttpRequest getRequest = new HttpRequest.HttpRequestBuilder("https://api.example.com/users") .withMethod("GET") .withHeader("Authorization", "Bearer token123") .withTimeout(10000) .build(); // POST request HttpRequest postRequest = new HttpRequest.HttpRequestBuilder("https://api.example.com/users") .withMethod("POST") .withHeader("Authorization", "Bearer token123") .withBody("{\"name\": \"John\", \"email\": \"[email protected]\"}") .dontFollowRedirects() .build(); getRequest.execute(); System.out.println(); postRequest.execute(); } }

Example 6: Using Lombok @Builder (Production Shortcut)

// Using Lombok library - generates builder automatically // Add this dependency: org.projectlombok:lombok import lombok.Builder; import lombok.ToString; @Builder @ToString class User { private final String username; // Required private final String email; // Required private final String firstName; // Optional private final String lastName; // Optional private final int age; // Optional private final boolean active; // Optional } // Usage with Lombok public class LombokBuilderDemo { public static void main(String[] args) { User user = User.builder() .username("johndoe") .email("[email protected]") .firstName("John") .lastName("Doe") .age(30) .active(true) .build(); System.out.println(user); } }

Builder Pattern Benefits

✅ Advantages:

Readable Code: Method chaining makes object creation self-documenting
Immutability: Can create immutable objects
Flexibility: Easy to add new parameters without breaking existing code
Validation: Centralized validation logic
Multiple Representations: Same builder can create different object variations

✅ vs Other Patterns:

vs Telescoping Constructors: Much more readable and maintainable
vs JavaBeans Setters: Provides immutability and thread-safety
vs Factory Pattern: More control over construction process

When to Use Builder Pattern

✅ Use When:

Object has many optional parameters
Object creation involves complex logic
You want immutable objects
You need different representations of the same construction process
Code readability is important

❌ Avoid When:

Object has only a few parameters
Parameters are always required
Simple object creation without complex logic

Best Practices

Make Constructor Private: Prevent direct instantiation
Use Fluent Interface: Return this from setter methods
Validate in Builder: Check parameters before object creation
Use Static Builder Class: Keep builder closely coupled with main class
Consider Default Values: Initialize optional parameters with sensible defaults

Conclusion

The Builder Pattern is like having a personal assistant for object creation:

✅ Step-by-step construction - Build complex objects gradually
✅ Clean, readable code - Fluent interface with method chaining
✅ Validation and safety - Check parameters before object creation
✅ Immutability - Create thread-safe immutable objects
✅ Flexibility - Easy to extend without breaking existing code

Key Takeaway: Use the Builder Pattern when you need to create objects with many optional parameters or complex construction logic. It makes your code more maintainable, readable, and robust compared to telescoping constructors or JavaBeans pattern.

It's perfect for configuration objects, DTOs (Data Transfer Objects), and any complex domain object that requires flexible construction!