How do you design a Builder that works across a class hierarchy so that subclass builder methods can be chained in any order while still returning the correct subtype?

## The problem inheritance creates Suppose `Pizza` is an abstract base with subclasses `NyPizza` and `Calzone`, and you want a Builder for each. A subclass builder must offer both the **parent's** chaining methods (e.g. `addTopping(...)`) and its **own** (e.g. `size(...)` for `NyPizza`). With a naive design, the parent builder's `addTopping` returns the *parent* `Builder` type. So after calling it, the compiler thinks you hold a parent builder and **forbids** calling subclass methods — unless you carefully order every parent call last. Chaining in arbitrary order becomes impossible, and downcasting is ugly and unsafe. ## The simulated self-type idiom Java lacks a true *self type* (a way to say 'the exact runtime type of this'), so Effective Java uses a generic workaround. The abstract parent builder is parameterized by its own subtype: ```java public abstract static class Builder<T extends Builder<T>> { EnumSet<Topping> toppings = EnumSet.noneOf(Topping.class); public T addTopping(Topping t) { toppings.add(Objects.requireNonNull(t)); return self(); // <-- returns the subclass builder type } abstract Pizza build(); // covariant in subclasses protected abstract T self(); // each subclass returns 'this' } ``` Key pieces: - **`<T extends Builder<T>>`** — the *recursive (F-bounded) generic*. It binds `T` to the concrete subclass builder type. Read it as 'T is some builder whose self-type is T.' - **`abstract T self()`** — the simulated self-type hook. Each concrete subclass implements it as `return this;`, which the compiler knows has type `T` because the subclass declares itself as that `T`. - **Every chaining method returns `T`**, not the raw parent `Builder`. So even when you call the *parent's* `addTopping`, the static type you get back is the *subclass* builder, and you can keep chaining subclass methods. - **`abstract Pizza build()`** with a **covariant return type** in each subclass: `NyPizza.Builder.build()` returns `NyPizza`, not just `Pizza`, so callers get the precise product without casting. ## A concrete subclass ```java public static class NyPizza extends Pizza { public static class Builder extends Pizza.Builder<Builder> { private final Size size; public Builder(Size size) { this.size = Objects.requireNonNull(size); } @Override public NyPizza build() { return new NyPizza(this); } // covariant @Override protected Builder self() { return this; } // self-type } private NyPizza(Builder b) { super(b); /* copy size */ } } ``` The parent's constructor takes the parent `Builder<?>` and copies shared fields; the subclass constructor takes its own `Builder` and copies subclass fields after `super(builder)`. ## Why it works (order independence) Because `addTopping` returns `T` = `NyPizza.Builder`, this compiles regardless of order: ```java NyPizza pie = new NyPizza.Builder(SMALL) .addTopping(SAUSAGE) // parent method, but returns NyPizza.Builder .size(LARGE) // wait: size was the ctor arg here; e.g. .addTopping(ONION) .build(); // returns NyPizza ``` You can interleave parent and subclass calls freely; the static type never degrades to the parent builder. ## Terms defined - **Self type:** a type that always refers to the exact class of `this`, even in subclasses. Java has no built-in self type, hence the simulation. - **F-bounded / recursive generic:** a type parameter bounded by an expression that mentions itself, `T extends Builder<T>`. It's the standard trick to approximate a self type. - **Covariant return type:** an overriding method may return a *subtype* of what the overridden method returns (allowed since Java 5). Here each subclass `build()` narrows `Pizza` to its own product type. ## Cost / when to use This is powerful but heavy: recursive generics, an abstract `self()`, covariant builds, and a two-level constructor copy. Use it **only for real builder hierarchies** where subclasses genuinely extend a common parameter set. For flat classes, a plain Builder is simpler and clearer; over-engineering a hierarchy-builder where there's no hierarchy is a smell.