John Roest
·3 min read·Design PatternsJava

The Builder Design Pattern

The Builder Design Pattern

The Builder pattern is a creational design pattern for constructing complex objects step by step. It provides a clear, flexible approach when an object has many optional fields or configurations.

Instead of a single constructor with many parameters, the Builder pattern allows each part of an object to be set individually through a chain of method calls. Once all required parts are set, the build() method finalizes the object.

This pattern is appropriate when:

  • An object requires numerous parameters for construction
  • Many of those parameters are optional
  • Multiple valid configurations of the same object exist
  • The object should be immutable after construction

Motivation#

Consider a House object with optional components: walls, a roof, a garage, a swimming pool, a garden, and solar panels.

A naive constructor:

public class House {
    public House(String walls, String roof, boolean hasGarage, boolean hasSwimmingPool, boolean hasGarden, boolean hasSolarPanels) {
        // initialize fields
    }
}

Instantiation:

House house = new House("brick", "tile", true, false, true, false);

This is unreadable. The boolean flags carry no meaning at the call site, and any change to the class propagates to every instantiation across the codebase.

Structure#

The Builder pattern separates construction logic from the object's representation, providing a fluent interface that makes object creation self-documenting.

Participants#

  • Product: The object being built (House)
  • Builder: Defines the methods to configure each part of the product
  • ConcreteBuilder: Implements the builder and returns the final object
  • Director (optional): Encapsulates common construction sequences

Implementation#

Product and Builder#

public class House {
    private final String walls;
    private final String roof;
    private final boolean hasGarage;
    private final boolean hasSwimmingPool;
    private final boolean hasGarden;
    private final boolean hasSolarPanels;

    private House(Builder builder) {
        this.walls = builder.walls;
        this.roof = builder.roof;
        this.hasGarage = builder.hasGarage;
        this.hasSwimmingPool = builder.hasSwimmingPool;
        this.hasGarden = builder.hasGarden;
        this.hasSolarPanels = builder.hasSolarPanels;
    }

    public static class Builder {
        private String walls;
        private String roof;
        private boolean hasGarage;
        private boolean hasSwimmingPool;
        private boolean hasGarden;
        private boolean hasSolarPanels;

        public Builder withWalls(String walls) {
            this.walls = walls;
            return this;
        }

        public Builder withRoof(String roof) {
            this.roof = roof;
            return this;
        }

        public Builder withGarage(boolean hasGarage) {
            this.hasGarage = hasGarage;
            return this;
        }

        public Builder withSwimmingPool(boolean hasSwimmingPool) {
            this.hasSwimmingPool = hasSwimmingPool;
            return this;
        }

        public Builder withGarden(boolean hasGarden) {
            this.hasGarden = hasGarden;
            return this;
        }

        public Builder withSolarPanels(boolean hasSolarPanels) {
            this.hasSolarPanels = hasSolarPanels;
            return this;
        }

        public House build() {
            return new House(this);
        }
    }
}

Usage#

House modernHouse = new House.Builder()
    .withWalls("concrete")
    .withRoof("metal")
    .withGarage(true)
    .withGarden(true)
    .build();

Each step is labeled and self-documenting. The intent is clear without consulting the constructor signature.

Reusing Builders#

A shared base builder allows consistent defaults with targeted customization:

House.Builder baseBuilder = new House.Builder()
    .withWalls("brick")
    .withRoof("shingle");

House baseHouse = baseBuilder.build();

House luxuryHouse = baseBuilder
    .withGarage(true)
    .withSwimmingPool(true)
    .withSolarPanels(true)
    .build();

Director Class#

The Director encapsulates reusable construction sequences:

public class HouseDirector {
    public House constructLuxuryHouse() {
        return new House.Builder()
            .withWalls("marble")
            .withRoof("tile")
            .withGarage(true)
            .withSwimmingPool(true)
            .withGarden(true)
            .withSolarPanels(true)
            .build();
    }

    public House constructSimpleHouse() {
        return new House.Builder()
            .withWalls("wood")
            .withRoof("shingle")
            .build();
    }
}

Advantages#

  • Readability: Each configuration step is labeled and explicit.
  • Maintainability: Adding or removing optional fields requires no constructor overloads and no changes to existing call sites.
  • Immutability: The product can be made fully immutable after build() returns.
  • Testability: Builders simplify the construction of varied test fixtures.

When to Use#

Apply the Builder pattern when a constructor has many parameters, particularly optional ones, and when the constructed object should be immutable. For objects with few fields and no optional configuration, direct instantiation is simpler and preferable.

Conclusion#

The Builder pattern separates construction logic from the object itself. In a statically typed language like Java, where constructor overloads and optional parameters accumulate quickly, this separation pays consistent dividends in readability and maintainability.