Effective Java - Why do we need a builder?

Sheng Wu — Mon, 04 Oct 2021 11:05:50 +0000

Why do we need a builder?

Using a constructor or a static factory method has a limit - they don't scale well. If there are many fields in the class, the argument list of a constructor or a static factory method is quite long and we might get the order wrong when calling the method. It is even worse if many fields are optional. A builder class comes in handy.

What is a builder

A builder class is normally a static member class of the class it builds. Instead of making the desired object directly, a client calls the constructor with the required fields and get a builder object. Then the client calls the setter-like methods to set fields. Finally the client calls a parameterless build method to generate the object of interest.

Consider this scenario, we want to cook a recipe and many ingredients are optional.

public class ChickenCongeeRecipe {
    private final int riceWeight;
    private final int waterWeight;
    private final int chickenWeight;
    private final int saltWeight;
    private final int gingerWeight;
    private final int springOnionWeight;

    public static class Builder {
        // required fields
        private final int riceWeight;
        private final int waterWeight;
        private final int chickenWeight;

        // optional fields - default to 0
        private int saltWeight = 0;
        private int gingerWeight = 0;
        private int springOnionWeight = 0;

        public Builder(int riceWeight, int waterWeight, int chickenWeight) {
            this.riceWeight = riceWeight;
            this.waterWeight = waterWeight;
            this.chickenWeight = chickenWeight;
        }

        public Builder saltWeight(int val) {
            saltWeight = val;
            return this;
        }

        public Builder gingerWeight(int val) {
            gingerWeight = val;
            return this;
        }

        public Builder springOnionWeight(int val) {
            springOnionWeight = val;
            return this;
        }

        public ChickenCongeeRecipe build() {
            return new ChickenCongeeRecipe(this);
        }
    }

    private ChickenCongeeRecipe(Builder builder) {
        riceWeight = builder.riceWeight;
        waterWeight = builder.waterWeight;
        chickenWeight = builder.chickenWeight;
        saltWeight = builder.saltWeight;
        gingerWeight = builder.gingerWeight;
        springOnionWeight = builder.springOnionWeight;
    }
}

And a client can create an object using

ChickenCongeeRecipe chickenCongee = new ChickenCongeeRecipe.Builder(100, 800, 50).saltWeight(6).gingerWeight(20).springOnionWeight(20).build();

The object created is typically immutable.

Conclusion

A builder has its downside too. It's more expensive comparing to constructors or static factory methods. It could be a problem in performance-critical applications. To make it worthwhile, the parameter list should probably be bigger than four. Having said that, if we start with constructors and additional fields need to be added in the future, the constructor is going to stick around.

Effective Java - Static factory methods vs Constructors

Sheng Wu — Mon, 27 Sep 2021 11:34:44 +0000

Most of the time when we want to obtain an instance of a class, we call the public constructor. But we can also have a static factory method to simply return an instance of the class. For example:

public static Boolean valueOf(boolean b) {
    return b ? Boolean.TRUE : Boolean.FALSE
}

Advantages of using a static factory method

They have names. It is easier for clients to understand what the method is for. Also normally a class can only have one constructor given one signature. Changing the order of parameter list to get away from this restriction is bad practice. Because static factory methods have names, they don't share this restriction.
Unlike constructors, they are not required to create a new object every time they are invoked. For the example above, it uses the instance created in the class.

public static final Boolean TRUE = new Boolean(true);
public static final Boolean FALSE = new Boolean(false);

Unlike constructors, they can return any subtype of the return type. For example, the interface java.util.Collections has many implementations and most of them are exported via static factory methods. The classes of returned objects are nonpublic, eg. EmptySet. It is exported via a static factory method

public static final Set EMPTY_SET = new EmptySet<>();
public static final <T> Set<T> emptySet() {
     return (Set<T>) EMPTY_SET;
}

Disadvantages of using a static factory method

Classes without public / protected constructors cannot have subclasses.
These methods can be hard to find unlike constructors but there are some common names for static factory methods, e.g from(), and of().

When to use a static factory method

When you need multiple constructors with the same signature.
When objects are expensive to create.
When you want the flexibility to return subtypes.

Conclusion

In general, static factory methods are preferable than constructors. So think about them before using a constructor.

DEV Community: Sheng Wu

Effective Java - Why do we need a builder?

Why do we need a builder?

What is a builder

Conclusion

Effective Java - Static factory methods vs Constructors

Advantages of using a static factory method

Disadvantages of using a static factory method

When to use a static factory method

Conclusion