The new Builder Pattern

I like to create immutable objects, especially after reading Josh Bloch's excellent "Effective Java" book. If an object is immutable, it has only one possible state and it is a stable one, so once you successfully build an object, you don't need to care about state transitions that can make your object unstable or corrupted. And immutable objects can be shared even in a multithreaded application. There are many other pros of immutability (you can read some of them here).

There is a classical way of making immutable objects in Java which consists of making all fields final (and private, of course), using only constructors to modify them (so that the only moment when a field is modified is during its construction) and making the class final (to avoid adding "setter" methods to subclasses). When you only have a couple of fields, that's fine, but when you have many of them you end up with a constructor with many arguments, which is ugly and difficult to use. If you have optional parameters, you can have a constructor with all the parameters and some other shorter constructors that have the mandatory parameters and some optional ones, that invoke the big constructor, like this:

public class Foo {

    private final String mandatoryOne;
    private final String mandatoryTwo;
    private final String optionalOne;
    private final String optionalTwo;
    
    public Foo(String mOne, String mTwo, String optOne, String optTwo){
        this.mandatoryOne = mOne;
        this.mandatoryTwo = mTwo;
        this.optionalOne = optOne;
        this.optionalTwo = optTwo;
    }
    
    public Foo(String mOne, String mTwo, String optOne){
        this(mOne, mTwo, optOne, null);
    }
    ...
}

This can be a bit messy when you add more optional parameters, you end up with a lot of constructors like these and it has a lot of boilerplate code.The use of setters for the optional parameters is not an option, because this leads to non immutable objects (some object can change the state of your object with one of those setter methods).
Some time ago, thinking about this problem, I thought a solution could be to use a Javabean object, with one setter per field (even for the mandatory ones), but with a kind of "seal" method, that would "mark" the object as built and since that moment, an IllegalStateException would be thrown if a setter was called. Nevertheless, I wasn't very satisfied with this approach, because the setter methods that sometimes can be called and sometimes not would be confusing for the caller.

So one solution to this is chained invocation of setters in java. This method is used in the New Builder pattern, explained by Josh Bloch in this PDF presentation, which is different from the original GoF Builder pattern. This pattern uses a public inner static class as a builder. The constructor of the original class is made private, so the only way to build objects is with the inner builder class. The builder has a setter method for each optional parameter and uses a fluent idiom that allows chaining of these method calls. I like this pattern a lot, because it solves the problem elegantly and effectively.

Implementation of the New Builder pattern

In Josh Bloch's presentation there wasn't a detailed implementation of the pattern, although it was very clear the idea and the intention so I have searched for it in the Internet.

Static Builder - the builder is a static nested class of the class from which it has to make instances, the builder's constructor is public (so you invoke the builder with 'new'), and the builder has the same fields as its enclosing class. The 'build()' method copies the content of the builder's fields into a new instance of the enclosing class. What I don't like about this implementation is this duplication of fields (for each field in the original class you have a duplicate field in the builder).

public class ID3Tag {

    private final String title;
    private final String artist;
    private volatile String album;
    private volatile int albumTrack;
    private volatile String comment;
    
    public static class Builder {
    
    private boolean isBuilt = false;
    private ID3Tag id3tag;
    
    public Builder(String title, String artist) {
      id3tag = new ID3Tag(title, artist);
    }
    
    public Builder album(String val) {
      if (isBuilt){
        throw new IllegalStateException("The object cannot be modified after built");
      }
      id3tag.album = val;
      return this;
    }
    
    public Builder albumTrack(int val) {
      if (isBuilt){
        throw new IllegalStateException("The object cannot be modified after built");
      }
      id3tag.albumTrack = val;
      return this;
    }
    
    public Builder comment(String val) {
      if (isBuilt){
        throw new IllegalStateException("The object cannot be modified after built");
      }
      id3tag.comment = val;
      return this;
    }
    // ... a lot more optional parameters
    
    public ID3Tag build() {
          if (isBuilt){
             throw new IllegalStateException("The object cannot be built twice");
          }
          isBuilt = true;
          return id3tag;
        }
        }
        
        private ID3Tag(String title, String artist) {
        this.title = title;
        this.artist = artist;
    }
}

The usage of this class would be:

ID3Tag tag = new ID3Tag.Builder("My Title", "My author")
                   .comment("Great song").build();

There is a similar pattern, called the Essence pattern, here by Dr Herbie. This pattern uses direct access to the fields of the builder (like in a C++ structure) instead of using "setter" methods and it doesn't use "chaining" of modifications like in the New Builder Pattern ("...builder.option1(value1).option2(value2)...").