java 53 lines · 7 steps

Building immutable objects with the Builder pattern

A final class with a private constructor and a nested Builder produces validated, immutable ShippingAddress instances.

Explained by highlit

Intermediate builder-pattern immutability validation optional fluent-api

1public final class ShippingAddress {
  private final String recipient;
  private final String line1;
  private final String line2;
  private final String city;
  private final String postalCode;
  private final String countryCode;
8 
  private ShippingAddress(Builder builder) {
      this.recipient = builder.recipient;
      this.line1 = builder.line1;
      this.line2 = builder.line2;
      this.city = builder.city;
      this.postalCode = builder.postalCode;
      this.countryCode = builder.countryCode;
  }
17 
  public String recipient() { return recipient; }
  public String line1() { return line1; }
  public Optional<String> line2() { return Optional.ofNullable(line2); }
  public String city() { return city; }
  public String postalCode() { return postalCode; }
  public String countryCode() { return countryCode; }
24 
  public static Builder builder() {
      return new Builder();
  }
28 
  public static final class Builder {
      private String recipient;
      private String line1;
      private String line2;
      private String city;
      private String postalCode;
      private String countryCode;
36 
      public Builder recipient(String recipient) { this.recipient = recipient; return this; }
      public Builder line1(String line1) { this.line1 = line1; return this; }
      public Builder line2(String line2) { this.line2 = line2; return this; }
      public Builder city(String city) { this.city = city; return this; }
      public Builder postalCode(String postalCode) { this.postalCode = postalCode; return this; }
      public Builder countryCode(String countryCode) { this.countryCode = countryCode; return this; }
43 
      public ShippingAddress build() {
          Objects.requireNonNull(recipient, "recipient is required");
          Objects.requireNonNull(line1, "line1 is required");
          Objects.requireNonNull(city, "city is required");
          Objects.requireNonNull(postalCode, "postalCode is required");
          Objects.requireNonNull(countryCode, "countryCode is required");
          return new ShippingAddress(this);
      }
  }
53}

01 / 01

STEP 01

Walkthrough

Space play ←→ step click any line

Three takeaways

1Making fields final and the constructor private guarantees an object can't be mutated or built in an invalid partial state.
2A fluent Builder that returns this lets callers set only the fields they need in any order before a single build call.
3Returning Optional for a nullable field signals its absence in the type itself instead of forcing callers to null-check.

Related explainers

javascript

export function buildPaginationUrl(baseUrl, { page, perPage, filters = {}, sort } = {}) {
  const url = new URL(baseUrl);
  const params = url.searchParams;

Building and parsing pagination URLs

url-parsing query-string pagination

Intermediate 8 steps

java

import java.time.Instant;
import java.time.ZoneId;
import java.time.ZonedDateTime;
import java.time.format.DateTimeFormatter;

Converting timestamps across time zones in Java

date-time time-zones instant

Intermediate 6 steps

python

import re
from email_validator import validate_email, EmailNotValidError
 
_DISPOSABLE_DOMAINS = {

Normalizing signup emails in Python

validation normalization data-cleaning

Intermediate 8 steps

java

package com.example.payments.config;
 
import com.stripe.StripeClient;
import org.springframework.beans.factory.annotation.Value;

Swapping payment gateways by profile in Spring

dependency-injection profiles configuration

Intermediate 6 steps

package validate
 
import (
	"fmt"

Struct validation with reflection in Go

reflection struct-tags validation

Intermediate 7 steps

python

from datetime import datetime
from zoneinfo import ZoneInfo

Timezone-safe datetime handling in Python

timezones datetime normalization

Intermediate 4 steps

Share this explainer

Here's the card — post it anywhere.

Building immutable objects with the Builder pattern — share card

Made with highlit — turn any snippet into a walkthrough like this in about a minute.

Explain your code