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

java

public record AppConfig(
        String host,
        int port,
        String databaseUrl,

Loading typed config from env vars in Java

records configuration environment-variables

Intermediate 6 steps

php

<?php
 
namespace App\Validation;

Building a reusable address form validator in PHP

validation error-accumulation regex

Intermediate 9 steps

java

public class RequestThrottler {
 
    private final Semaphore permits;
    private final long acquireTimeoutMillis;

Bounding concurrency with a Semaphore in Java

concurrency semaphore rate-limiting

Intermediate 6 steps

php

<?php
 
namespace App\Http\Controllers;

A cached autocomplete endpoint in Laravel

caching validation query-ranking

Intermediate 8 steps

java

public List<DailySample> backfillMissingDates(List<DailySample> samples, double fillValue) {
    if (samples.isEmpty()) {
        return List.of();
    }

Backfilling gaps in a daily time series in Java

streams time-series treemap

Intermediate 5 steps

java

public final class Ulid {
 
    private static final char[] ENCODING = "0123456789ABCDEFGHJKMNPQRSTVWXYZ".toCharArray();
    private static final SecureRandom RANDOM = new SecureRandom();