Builder Pattern: Fluent Construction Without Telescoping Constructors

// VIOLATION: telescoping constructors — every combination of optional
// fields needs its own overload, and call sites are unreadable.
class HttpRequest {
    private final String url;
    private final String method;
    private final Map<String, String> headers;
    private final String body;
    private final int timeoutMs;
 
    HttpRequest(String url) { this(url, "GET"); }
    HttpRequest(String url, String method) { this(url, method, Collections.emptyMap()); }
    HttpRequest(String url, String method, Map<String, String> headers) {
        this(url, method, headers, null);
    }
    HttpRequest(String url, String method, Map<String, String> headers, String body) {
        this(url, method, headers, body, 5000);
    }
    HttpRequest(String url, String method, Map<String, String> headers, String body, int timeoutMs) {
        this.url = url; this.method = method; this.headers = headers;
        this.body = body; this.timeoutMs = timeoutMs;
    }
}
 
// Call site: which parameter is which? You need the IDE or the source to know.
HttpRequest req = new HttpRequest("https://api.example.com", "POST", Map.of("X-Id", "1"), "{}", 10000);

// VIOLATION: readable construction, but the object is mutable and can exist
// in an inconsistent, half-built state at any point after construction.
class HttpRequest {
    private String url;              // no `final` — every field is mutable
    private String method = "GET";
    private Map<String, String> headers = new HashMap<>();
    private String body;
    private int timeoutMs = 5000;
 
    // getters and setters for every field...
    void setUrl(String url) { this.url = url; }
    void setMethod(String method) { this.method = method; }
    // ...
}
 
HttpRequest req = new HttpRequest();
req.setMethod("POST");
// req is now in an invalid state — url is null — until setUrl() is ALSO called.
// Nothing in the type system prevents using req in this half-built state,
// and nothing prevents another thread from observing it mid-construction.

// FIXED: fluent builder — readable call sites, mandatory fields enforced
// at build() time, and the resulting object is fully immutable.
final class HttpRequest {
    private final String url;             // mandatory
    private final String method;          // has a sensible default
    private final Map<String, String> headers;
    private final String body;
    private final int timeoutMs;
 
    // Private constructor — only the Builder can call it.
    private HttpRequest(Builder b) {
        this.url = b.url;
        this.method = b.method;
        this.headers = Map.copyOf(b.headers); // defensive copy → truly immutable
        this.body = b.body;
        this.timeoutMs = b.timeoutMs;
    }
 
    public static Builder builder(String url) {
        return new Builder(url);
    }
 
    // getters only — no setters anywhere on HttpRequest itself
    public String getUrl() { return url; }
    public String getMethod() { return method; }
    public Map<String, String> getHeaders() { return headers; }
    public String getBody() { return body; }
    public int getTimeoutMs() { return timeoutMs; }
 
    public static class Builder {
        private final String url;                 // mandatory — passed to Builder's constructor
        private String method = "GET";             // optional, with default
        private final Map<String, String> headers = new HashMap<>();
        private String body;
        private int timeoutMs = 5000;
 
        private Builder(String url) {
            if (url == null || url.isBlank()) {
                throw new IllegalArgumentException("url is mandatory");
            }
            this.url = url;
        }
 
        public Builder method(String method) { this.method = method; return this; }
        public Builder header(String key, String value) { this.headers.put(key, value); return this; }
        public Builder body(String body) { this.body = body; return this; }
        public Builder timeoutMs(int timeoutMs) { this.timeoutMs = timeoutMs; return this; }
 
        public HttpRequest build() {
            return new HttpRequest(this); // validation already happened in the constructor + here if needed
        }
    }
}

// Usage: reads like a sentence, mandatory field is impossible to omit
// (it's a constructor/factory-method parameter, not a fluent call).
HttpRequest req = HttpRequest.builder("https://api.example.com")
    .method("POST")
    .header("X-Id", "1")
    .body("{}")
    .timeoutMs(10_000)
    .build();

// Each interface exposes exactly one next step — the compiler enforces order.
interface UrlStep { MethodStep url(String url); }
interface MethodStep { BuildStep method(String method); }
interface BuildStep {
    BuildStep header(String key, String value);
    HttpRequest build();
}
 
class HttpRequestStepBuilder implements UrlStep, MethodStep, BuildStep {
    private String url;
    private String method;
    private final Map<String, String> headers = new HashMap<>();
 
    private HttpRequestStepBuilder() { }
 
    static UrlStep newBuilder() { return new HttpRequestStepBuilder(); }
 
    public MethodStep url(String url) { this.url = url; return this; }
    public BuildStep method(String method) { this.method = method; return this; }
    public BuildStep header(String key, String value) { headers.put(key, value); return this; }
    public HttpRequest build() { return HttpRequest.builder(url).method(method).build(); }
}
 
// Usage — the compiler physically will not let you call .build() before
// .url(...).method(...): BuildStep's methods aren't visible until then.
HttpRequest req = HttpRequestStepBuilder.newBuilder()
    .url("https://api.example.com")
    .method("POST")
    .header("X-Id", "1")
    .build();

interface MealBuilder {
    void addBread();
    void addProtein();
    void addSide();
    Meal build();
}
 
class VeggieMealBuilder implements MealBuilder {
    private final Meal meal = new Meal();
    public void addBread() { meal.add("whole grain bun"); }
    public void addProtein() { meal.add("grilled tofu"); }
    public void addSide() { meal.add("side salad"); }
    public Meal build() { return meal; }
}
 
class ProteinMealBuilder implements MealBuilder {
    private final Meal meal = new Meal();
    public void addBread() { meal.add("brioche bun"); }
    public void addProtein() { meal.add("double patty"); }
    public void addSide() { meal.add("fries"); }
    public Meal build() { return meal; }
}
 
// Director owns the SEQUENCE — the same sequence produces different
// meals depending on which builder is handed to it.
class MealDirector {
    Meal construct(MealBuilder builder) {
        builder.addBread();
        builder.addProtein();
        builder.addSide();
        return builder.build();
    }
}
 
// Usage:
Meal veggieMeal = new MealDirector().construct(new VeggieMealBuilder());
Meal proteinMeal = new MealDirector().construct(new ProteinMealBuilder());