The Builder Pattern

The Builder pattern constructs a complex, usually immutable object step by step through a fluent helper class — replacing confusing multi-argument constructors with readable, named, chainable calls.

Learn The Builder Pattern in our free Java course — a beginner-friendly interactive lesson with worked examples, a practice exercise and a quick reference.

Part of the free Java course at LearnCodingFast — hands-on lessons with examples you run in your browser, plus practice exercises and a quick quiz.

Before You Start

You should know classes, constructors and access modifiers , and ideally the previous lesson on immutability — builders and immutable objects are natural partners.

What You'll Learn

The Big Idea — Ordering a Sandwich

💡 Analogy: A telescoping constructor is like ordering by shouting " one, twelve, true, false, true! " and hoping the kitchen guesses what each value means. A Builder is the sandwich shop counter: you say " start with a footlong, add cheese, add mushrooms, hold the pepperoni ", one clear instruction at a time, and only when you say " that's it " ( build() ) does the kitchen check your order is valid and hand over the finished, sealed sandwich. You configured a mutable order; you received an immutable meal.

Each instruction is named , so nobody confuses cheese for mushrooms — and the order can't go out the door until it passes the final check.

1️⃣ The Problem — Telescoping Constructors

With several optional fields you end up with a ladder of constructors, and call sites become a row of mystery true / false values. Which flag is which? You can't tell without opening the class. Add one option and you add another constructor.

2️⃣ The Solution — a Fluent Builder

Move construction into a static nested Builder . Required values go to the builder's constructor; optional ones get named methods that set a field and return this so calls chain. The product's constructor is private and takes the builder, so objects can only be made the validated way.

3️⃣ Validation in build()

The setters just record values; build() is the one place where the whole object exists, so it's where you validate. Check required fields and cross-field rules there, throwing IllegalStateException if anything is off — an invalid object is then never created.

🧠 Quick Recall

Answer: chaining would break — builder.cheese().mushroom() wouldn't compile because cheese() would return nothing for mushroom() to call. Each fluent method must return this .

Answer: so the only path to an instance is through the builder's build() , which guarantees validation runs and the object is complete. A public constructor would let callers bypass all of that.

Answer: in build() . Only there does the whole object exist, so cross-field rules can be checked. Setters just record intent.

🎯 YOUR TURN — Finish the Burger builder

Complete the nested Builder : a patties(int) setter, a no-arg cheese() flag, and build() — all chainable.

🧩 MINI-CHALLENGE — Config builder with defaults & validation

Build an immutable HttpRequestConfig with a required URL, defaulted method/timeout, and validation in build() .

Common Errors

• ❌ Fluent setters returning void . Chaining won't compile. Fix: every setter must return this .
• ❌ A public product constructor. Callers skip validation. Fix: make it private and build only via the builder.
• ❌ Validating in setters instead of build(). Cross-field rules can't be checked early. Fix: validate in build() .
• ❌ Mutable product fields. Defeats the safety the pattern offers. Fix: make product fields private final .
• ❌ Forgetting to copy mutable inputs. The builder can leak a list reference into the product. Fix: defensively copy in build() (see the immutability lesson).
• ❌ Using a builder for a 1-field class. It's overkill. Fix: a plain constructor or a record is clearer.

Pro Tips

• 💡 Put required fields in the builder's constructor so they can't be forgotten, and give optional ones sensible defaults.
• 💡 Lombok's @Builder generates the whole pattern for you in real projects — but knowing the hand-written version is essential.
• 💡 The JDK uses it: HttpRequest.newBuilder()...build() and Stream.builder() are fluent builders you've already seen.
• 💡 Pair with records: a builder can assemble values and pass them to a record's canonical constructor for the final immutable product.

📋 Quick Reference

Concept

Syntax

Note

nested builder

static final class Builder

Inside the product

entry point

static Builder builder()

Factory method

required field

Builder(int size)

Constructor arg

optional default

int x = 30;

Field initializer

fluent setter

Builder x(v)

Returns this

chaining

.a().b().build()

Reads top to bottom

validation

throw in build()

Single check point

private ctor

private T(Builder b)

Build only via builder

build()

T build()

Returns immutable T

when to use

many optional params

Else use a record

in the wild

HttpRequest.newBuilder()

JDK example

📚 Resources / Keep Learning

• 📘 HttpRequest.Builder — a real JDK builder (docs.oracle.com)
• 📘 Stream.Builder — Java 21 API (docs.oracle.com)
• 📗 dev.java — official tutorials and guides

❓ Frequently Asked Questions

🎉 Lesson Complete!

You can now recognise the telescoping-constructor problem, write a static nested Builder with fluent return this setters, validate in build() , produce an immutable result through a private constructor, and judge when a builder beats a plain constructor or record.

Next up: Dependency Injection — wiring objects together from the outside so your code is decoupled and testable.

Practice quiz

Continue this course

• Previous: Immutability & Defensive Copying
• Next: Dependency Injection

Related lessons

• classes, constructors
• access modifiers