In my two immediately previous posts, I looked at reducing the number of parameters required for a constructor or method invocation via custom types and parameter objects. In this post, I look at use of the builder pattern to reduce the number of parameters required for a constructor with some discussion on how this pattern can even help with non-constructor methods that take too many parameters.
In the Second Edition of Effective Java, Josh Bloch introduces use of the builder pattern in Item #2 for dealing with constructors that require too many parameters. Bloch not only demonstrates how to use the Builder, but explains it advantages over constructors accepting a large number of parameters. I will get to those advantages at the end of this post, but think it's important to point out that Bloch has devoted an entire item in his book to this practice.
To illustrate the advantages of this approach, I'll use the following example Person class. It doesn't have all the methods I would typically add to such a class because I want to focus on its construction.
Person.java (without Builder Pattern)
package dustin.examples;
/**
* Person class used as part of too many parameters demonstration.
*
* @author Dustin
*/
public class Person
{
private final String lastName;
private final String firstName;
private final String middleName;
private final String salutation;
private final String suffix;
private final String streetAddress;
private final String city;
private final String state;
private final boolean isFemale;
private final boolean isEmployed;
private final boolean isHomewOwner;
public Person(
final String newLastName,
final String newFirstName,
final String newMiddleName,
final String newSalutation,
final String newSuffix,
final String newStreetAddress,
final String newCity,
final String newState,
final boolean newIsFemale,
final boolean newIsEmployed,
final boolean newIsHomeOwner)
{
this.lastName = newLastName;
this.firstName = newFirstName;
this.middleName = newMiddleName;
this.salutation = newSalutation;
this.suffix = newSuffix;
this.streetAddress = newStreetAddress;
this.city = newCity;
this.state = newState;
this.isFemale = newIsFemale;
this.isEmployed = newIsEmployed;
this.isHomewOwner = newIsHomeOwner;
}
}
This class's constructor works, but it is difficult for client code to use properly. The Builder pattern can be used to make the constructor easier to use. NetBeans will refactor this for me as I have written about previously. An example of the refactored code is shown next (NetBeans does this by creating all new Builder class).
PersonBuilder.java
package dustin.examples;
public class PersonBuilder
{
private String newLastName;
private String newFirstName;
private String newMiddleName;
private String newSalutation;
private String newSuffix;
private String newStreetAddress;
private String newCity;
private String newState;
private boolean newIsFemale;
private boolean newIsEmployed;
private boolean newIsHomeOwner;
public PersonBuilder()
{
}
public PersonBuilder setNewLastName(String newLastName) {
this.newLastName = newLastName;
return this;
}
public PersonBuilder setNewFirstName(String newFirstName) {
this.newFirstName = newFirstName;
return this;
}
public PersonBuilder setNewMiddleName(String newMiddleName) {
this.newMiddleName = newMiddleName;
return this;
}
public PersonBuilder setNewSalutation(String newSalutation) {
this.newSalutation = newSalutation;
return this;
}
public PersonBuilder setNewSuffix(String newSuffix) {
this.newSuffix = newSuffix;
return this;
}
public PersonBuilder setNewStreetAddress(String newStreetAddress) {
this.newStreetAddress = newStreetAddress;
return this;
}
public PersonBuilder setNewCity(String newCity) {
this.newCity = newCity;
return this;
}
public PersonBuilder setNewState(String newState) {
this.newState = newState;
return this;
}
public PersonBuilder setNewIsFemale(boolean newIsFemale) {
this.newIsFemale = newIsFemale;
return this;
}
public PersonBuilder setNewIsEmployed(boolean newIsEmployed) {
this.newIsEmployed = newIsEmployed;
return this;
}
public PersonBuilder setNewIsHomeOwner(boolean newIsHomeOwner) {
this.newIsHomeOwner = newIsHomeOwner;
return this;
}
public Person createPerson() {
return new Person(newLastName, newFirstName, newMiddleName, newSalutation, newSuffix, newStreetAddress, newCity, newState, newIsFemale, newIsEmployed, newIsHomeOwner);
}
}
I prefer to have my Builder as a nested class inside the class whose object it builds, but the NetBeans automatic generation of a standalone Builder is very easy to use. Another difference between the NetBeans-generated Builder and the Builders I like to write is that my preferred Builder implementations have required fields provided in the Builder's constructor rather than provide a no-arguments constructor. The next code listing shows my Person class from above with a Builder added into it as a nested class.
Person.java with Nested Person.Builder
package dustin.examples;
/**
* Person class used as part of too many parameters demonstration.
*
* @author Dustin
*/
public class Person
{
private final String lastName;
private final String firstName;
private final String middleName;
private final String salutation;
private final String suffix;
private final String streetAddress;
private final String city;
private final String state;
private final boolean isFemale;
private final boolean isEmployed;
private final boolean isHomewOwner;
public Person(
final String newLastName,
final String newFirstName,
final String newMiddleName,
final String newSalutation,
final String newSuffix,
final String newStreetAddress,
final String newCity,
final String newState,
final boolean newIsFemale,
final boolean newIsEmployed,
final boolean newIsHomeOwner)
{
this.lastName = newLastName;
this.firstName = newFirstName;
this.middleName = newMiddleName;
this.salutation = newSalutation;
this.suffix = newSuffix;
this.streetAddress = newStreetAddress;
this.city = newCity;
this.state = newState;
this.isFemale = newIsFemale;
this.isEmployed = newIsEmployed;
this.isHomewOwner = newIsHomeOwner;
}
public static class PersonBuilder
{
private String nestedLastName;
private String nestedFirstName;
private String nestedMiddleName;
private String nestedSalutation;
private String nestedSuffix;
private String nestedStreetAddress;
private String nestedCity;
private String nestedState;
private boolean nestedIsFemale;
private boolean nestedIsEmployed;
private boolean nestedIsHomeOwner;
public PersonBuilder(
final String newFirstName,
final String newCity,
final String newState)
{
this.nestedFirstName = newFirstName;
this.nestedCity = newCity;
this.nestedState = newState;
}
public PersonBuilder lastName(String newLastName)
{
this.nestedLastName = newLastName;
return this;
}
public PersonBuilder firstName(String newFirstName)
{
this.nestedFirstName = newFirstName;
return this;
}
public PersonBuilder middleName(String newMiddleName)
{
this.nestedMiddleName = newMiddleName;
return this;
}
public PersonBuilder salutation(String newSalutation)
{
this.nestedSalutation = newSalutation;
return this;
}
public PersonBuilder suffix(String newSuffix)
{
this.nestedSuffix = newSuffix;
return this;
}
public PersonBuilder streetAddress(String newStreetAddress)
{
this.nestedStreetAddress = newStreetAddress;
return this;
}
public PersonBuilder city(String newCity)
{
this.nestedCity = newCity;
return this;
}
public PersonBuilder state(String newState)
{
this.nestedState = newState;
return this;
}
public PersonBuilder isFemale(boolean newIsFemale)
{
this.nestedIsFemale = newIsFemale;
return this;
}
public PersonBuilder isEmployed(boolean newIsEmployed)
{
this.nestedIsEmployed = newIsEmployed;
return this;
}
public PersonBuilder isHomeOwner(boolean newIsHomeOwner)
{
this.nestedIsHomeOwner = newIsHomeOwner;
return this;
}
public Person createPerson()
{
return new Person(
nestedLastName, nestedFirstName, nestedMiddleName,
nestedSalutation, nestedSuffix,
nestedStreetAddress, nestedCity, nestedState,
nestedIsFemale, nestedIsEmployed, nestedIsHomeOwner);
}
}
}
The Builder can be even nicer when enhanced through use of custom types and parameters objects as outlined in my first two posts on the "too many parameters" problem. This is shown in the next code listing.
Person.java with Nested Builder, Custom Types, and Parameters Object
package dustin.examples;
/**
* Person class used as part of too many parameters demonstration.
*
* @author Dustin
*/
public class Person
{
private final FullName name;
private final Address address;
private final Gender gender;
private final EmploymentStatus employment;
private final HomeownerStatus homeOwnerStatus;
/**
* Parameterized constructor can be private because only my internal builder
* needs to call me to provide an instance to clients.
*
* @param newName Name of this person.
* @param newAddress Address of this person.
* @param newGender Gender of this person.
* @param newEmployment Employment status of this person.
* @param newHomeOwner Home ownership status of this person.
*/
private Person(
final FullName newName, final Address newAddress,
final Gender newGender, final EmploymentStatus newEmployment,
final HomeownerStatus newHomeOwner)
{
this.name = newName;
this.address = newAddress;
this.gender = newGender;
this.employment = newEmployment;
this.homeOwnerStatus = newHomeOwner;
}
public FullName getName()
{
return this.name;
}
public Address getAddress()
{
return this.address;
}
public Gender getGender()
{
return this.gender;
}
public EmploymentStatus getEmployment()
{
return this.employment;
}
public HomeownerStatus getHomeOwnerStatus()
{
return this.homeOwnerStatus;
}
/**
* Builder class as outlined in the Second Edition of Joshua Bloch's
* Effective Java that is used to build a {@link Person} instance.
*/
public static class PersonBuilder
{
private FullName nestedName;
private Address nestedAddress;
private Gender nestedGender;
private EmploymentStatus nestedEmploymentStatus;
private HomeownerStatus nestedHomeOwnerStatus;
public PersonBuilder(
final FullName newFullName,
final Address newAddress)
{
this.nestedName = newFullName;
this.nestedAddress = newAddress;
}
public PersonBuilder name(final FullName newName)
{
this.nestedName = newName;
return this;
}
public PersonBuilder address(final Address newAddress)
{
this.nestedAddress = newAddress;
return this;
}
public PersonBuilder gender(final Gender newGender)
{
this.nestedGender = newGender;
return this;
}
public PersonBuilder employment(final EmploymentStatus newEmploymentStatus)
{
this.nestedEmploymentStatus = newEmploymentStatus;
return this;
}
public PersonBuilder homeOwner(final HomeownerStatus newHomeOwnerStatus)
{
this.nestedHomeOwnerStatus = newHomeOwnerStatus;
return this;
}
public Person createPerson()
{
return new Person(
nestedName, nestedAddress, nestedGender,
nestedEmploymentStatus, nestedHomeOwnerStatus);
}
}
}
The last couple of code listings show how a Builder is typically used - to construct an object. Indeed, the item on the builder (Item #2) in Joshua Bloch's Second Edition of Effective Java is in the chapter on creating (and destroying) object. However, the builder can help indirectly with non-constructor methods by allowing an easier way to build parameters objects that are passed to methods.