The New Builder Pattern

The idea

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.

Then I found 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.

The implementation

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.

In Richard Hansen's blog you can find an implementation that seems to be more close to what Josh explains: 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).

In Robbie Vanbrabant's blog there is a variation of this pattern, which avoids the boilerplate code using a base class for the builder and some reflection to build the object from the builder. I don't like the use of an interface for the builder, because that way you can't add a new optional parameter without breaking existing code that uses the builder (if you change the signature of a public interface the classes that use it have to change their code to implement the new methods). ^{Update: This is not a problem at all, as Robbie points out in a comment.} Also, I don't like the use of reflection because it's slower than the normal access to fields, but I do like the way it avoids duplication of fields in the builder.

The implementation I like most is the one found in Mario Hochreiter's blog. The builder is a nested public static class, but it changes the fields of its enclosing class directly, it doesn't use duplicates. It doesn't use reflection and the builder is a class, not an interface. The only problem I see is that, in theory, with a reference to a builder, you can change the state of the object it built, so you don't have the guarantee that the object is immutable. So I would add a check before each "setter" of the builder that would throw an IllegalStateException if the object has been already built and a check before the 'build' method itself to ensure the object is not built more than once. Also, I would make the mandatory parameters final. ^{Update: I have made volatile the non final fields of the class in order to avoid problems of visibility if the reference returned by the method build() is passed to code to be executed in another thread, as Niklas points out in his comment.}

So, with the example of Mario, I would implement this pattern this way:

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();

I have found a similar pattern, called the Essence pattern, described here and 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)...").