Chapter 14. Construction Builder

Incrementally create an immutable object with a builder that stores constructor arguments in fields.

14.1 How It Works

The basic recipe for a Construction Builder is very simple. You need to create an immutable object, which I’ll call the product, in a gradual manner. So, take each of the constructor arguments of the product and make a field for each one. Add further fields for any other attributes of the product that you’re collecting. Finally, add a method to create and return a new product object assembled from all the data in the Construction Builder.

You may want to add some lifecycle controls to the Construction Builder. Such controls might check if you have enough information already to create the product. You might set a flag once you’ve returned a product to prevent returning it again, or put the created product in a field. You might raise an error if you try to add new attributes to the Construction Builder once you’ve created the product.

Multiple Construction Builders can be combined into deeper structures. They can then produce a group of related objects rather than a single object.

14.2 When to Use It

Construction Builder is useful whenever you need to create an object with multiple immutable fields, but you gather the values for these fields gradually. A Construction Builder gives you a coherent place to put all this data before you actually create the product.

The simplest alternatives to Construction Builder is to capture the information in local variables or in loose fields. This works fine for one or two products, but soon gets confusing if you need to create a bunch of objects at once, such as when you’re parsing.

Another alternative is to create an actual model object, but after you gather data for an immutable attribute, create a new copy of the model object, with that one attribute changed, and replace the old one. This saves you having to write a Construction Builder, but is generally more awkward to do and follow. In particular, it doesn’t work if you have multiple references to the object, or at least it makes it more difficult as you have to replace every reference.

Using Construction Builder is usually the best way to handle this problem, but remember that you only need it when you have immutable fields. If that’s not the case, then just create your product objects directly.

Despite the common word “builder,” I see this pattern as different from Expression Builder. Construction Builder is purely about gradually building up construction arguments; it doesn’t attempt to provide a fluent interface. Expression Builders are focused on providing a fluent interface. Certainly it is not unusual to find cases where a single object is both a Construction Builder and an Expression Builder, but that doesn’t mean they are the same concept.

14.3 Building Simple Flight Data (C#)

Imagine an application that uses some data about flights. The data is only read by the application, so it makes sense for the domain classes to be read-only.

Although the application may only read the flight data, it’s quite possible that it has to gather in such a way that makes it difficult to use constructors to build fully formed objects. In these cases, a simple Construction Builder allows me to gather up the data and build the final object when I have it.