MACRO NEPAL
Builder Pattern in Java
awiskar acharya
October 27, 2025
4:59 pm

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

  1. Make Constructor Private: Prevent direct instantiation
  2. Use Fluent Interface: Return this from setter methods
  3. Validate in Builder: Check parameters before object creation
  4. Use Static Builder Class: Keep builder closely coupled with main class
  5. 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!

Category : JAVA

Leave a Reply

Your email address will not be published. Required fields are marked *


Macro Nepal Helper