Builder

About 3 min

Intent

Separate the construction of a complex object from its representation so that the same construction process can create different representations.

Explanation

Real-world example

Imagine a character generator for a role-playing game. The easiest option is to let the computer create the character for you. If you want to manually select the character details like profession, gender, hair color, etc. the character generation becomes a step-by-step process that completes when all the selections are ready.

In plain words

Allows you to create different flavors of an object while avoiding constructor pollution. Useful when there could be several flavors of an object. Or when there are a lot of steps involved in creation of an object.

Wikipedia says

The builder pattern is an object creation software design pattern with the intentions of finding a solution to the telescoping constructor antipattern.

Having said that let me add a bit about what telescoping constructor antipattern is. At one point or the other, we have all seen a constructor like below:

public Hero(Profession profession, String name, HairType hairType, HairColor hairColor, Armor armor, Weapon weapon) {
}

As you can see the number of constructor parameters can quickly get out of hand, and it may become difficult to understand the arrangement of parameters. Plus this parameter list could keep on growing if you would want to add more options in the future. This is called telescoping constructor antipattern.

Programmatic Example

The sane alternative is to use the Builder pattern. First of all, we have our hero that we want to create:

public final class Hero {
  private final Profession profession;
  private final String name;
  private final HairType hairType;
  private final HairColor hairColor;
  private final Armor armor;
  private final Weapon weapon;

  private Hero(Builder builder) {
    this.profession = builder.profession;
    this.name = builder.name;
    this.hairColor = builder.hairColor;
    this.hairType = builder.hairType;
    this.weapon = builder.weapon;
    this.armor = builder.armor;
  }
}

Then we have the builder:

  public static class Builder {
    private final Profession profession;
    private final String name;
    private HairType hairType;
    private HairColor hairColor;
    private Armor armor;
    private Weapon weapon;

    public Builder(Profession profession, String name) {
      if (profession == null || name == null) {
        throw new IllegalArgumentException("profession and name can not be null");
      }
      this.profession = profession;
      this.name = name;
    }

    public Builder withHairType(HairType hairType) {
      this.hairType = hairType;
      return this;
    }

    public Builder withHairColor(HairColor hairColor) {
      this.hairColor = hairColor;
      return this;
    }

    public Builder withArmor(Armor armor) {
      this.armor = armor;
      return this;
    }

    public Builder withWeapon(Weapon weapon) {
      this.weapon = weapon;
      return this;
    }

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

Then it can be used as:

var mage = new Hero.Builder(Profession.MAGE, "Riobard").withHairColor(HairColor.BLACK).withWeapon(Weapon.DAGGER).build();

Class diagram

Applicability

Use the Builder pattern when

The algorithm for creating a complex object should be independent of the parts that make up the object and how they're assembled
The construction process must allow different representations for the object that's constructed
It's particularly useful when a product requires a lot of steps to be created and when these steps need to be executed in a specific sequence

Known Uses

Java.lang.StringBuilder
Java.nio.ByteBuffer as well as similar buffers such as FloatBuffer, IntBuffer, and others
javax.swing.GroupLayout.Group#addComponent()

Consequences

Benefits:

More control over the construction process compared to other creational patterns
Supports constructing objects step-by-step, defer construction steps or run steps recursively
Can construct objects that require a complex assembly of sub-objects. The final product is detached from the parts that make it up, as well as their assembly process
Single Responsibility Principle. You can isolate complex construction code from the business logic of the product

Trade-offs:

The overall complexity of the code can increase since the pattern requires creating multiple new classes

Tutorials

Known uses

java.lang.StringBuilderopen in new window
java.nio.ByteBufferopen in new window as well as similar buffers such as FloatBuffer, IntBuffer and so on.
java.lang.StringBufferopen in new window
All implementations of java.lang.Appendableopen in new window
Apache Camel buildersopen in new window
Apache Commons Option.Builderopen in new window

Step Builderopen in new window is a variation of the Builder pattern that generates a complex object using a step-by-step approach. The Step Builder pattern is a good choice when you need to build an object with a large number of optional parameters, and you want to avoid the telescoping constructor antipattern.