Thursday, June 29, 2017

Builder Design pattern in Java - Example Tutorial

Builder design pattern in Java is a creational pattern i.e. used to create objects, similar to factory method design pattern which is also creational design pattern. Before learning any design pattern I suggest find out the problem a particular design pattern solves. Its been well said necessity is mother on invention. learning design pattern without facing problem is not that effective, Instead if you have already faced issues than its much easier to understand design pattern and learn how its solve the issue. In this Java design pattern tutorial we will first see what problem Builder design pattern solves which will give some insight on when to use builder design pattern in Java, which is also a popular design pattern interview question and then we will see example of Builder design pattern and pros and cons of using Builder pattern in Java. 

Btw, In order to best understand design patterns, you need to work out some scenarios, examples, etc. It's best to get this kind of knowledge as part of your work but even if you don't get there, you can supplement them by joining a comprehensive course like Design Patterns in Java and doing some object-oriented software design exercises. 

What problem Builder pattern solves in Java

What is builder design pattern in Java with exampleAs I said earlier Builder pattern is a creational design pattern it means its solves problem related to object creation. Constructors in Java are used to create object and can take parameters required to create object. Problem starts when an Object can be created with lot of parameters, some of them may be mandatory and others may be optional

Consider a class which is used to create Cake, now you need number of item like egg, milk, flour to create cake. many of them are mandatory and some  of them are optional like cherry, fruits etc. If we are going to have overloaded constructor for different kind of cake then there will be many constructor and even worst they will accept many parameter.


1) too many constructors to maintain.
2) error prone because many fields has same type e.g. sugar and and butter are in cups so instead of 2 cup sugar if you pass 2 cup butter, your compiler will not complain but will get a buttery cake with almost no sugar with high cost of wasting butter.

You can partially solve this problem by creating Cake and then adding ingredients but that will impose another problem of leaving Object on inconsistent state during building, ideally cake should not be available until its created. Both of these problem can be solved by using Builder design pattern in Java. Builder design pattern not only improves readability but also reduces chance of error by adding ingredients explicitly and making object available once fully constructed. 

By the way there are many design pattern tutorial already there in Javarevisited like Decorator pattern tutorial and  Observer pattern in Java. If you haven’t read them already then its worth looking.

Example of Builder Design pattern in Java

We will use same example of creating Cake using Builder design pattern in Java. here we have static nested builder class inside Cake which is used to create object.

1. Guidelines for Builder design pattern in Java

1) Make a static nested class called Builder inside the class whose object will be build by Builder. In this example its Cake.

2) Builder class will have exactly same set of fields as original class.
3) Builder class will expose method for adding ingredients e.g. sugar() in this example. each method will return same Builder object. Builder will be enriched with each method call.

4) method will copy all builder field values into actual class and return object of Item class.
5) Item class (class for which we are creating Builder) should have private constructor to create its object from build() method and prevent outsider to access its constructor.

public class BuilderPatternExample {
    public static void main(String args[]) {
        //Creating object using Builder pattern in java
        Cake whiteCake = new Cake.Builder().sugar(1).butter(0.5)eggs(2).vanila(2).flour(1.5). bakingpowder(0.75).milk(0.5).build();
        //Cake is ready to eat :)

class Cake {

    private final double sugar;   //cup
    private final double butter;  //cup
    private final int eggs;
    private final int vanila;     //spoon
    private final double flour;   //cup
    private final double bakingpowder; //spoon
    private final double milk;  //cup
    private final int cherry;

    public static class Builder {

        private double sugar;   //cup
        private double butter;  //cup
        private int eggs;
        private int vanila;     //spoon
        private double flour;   //cup
        private double bakingpowder; //spoon
        private double milk;  //cup
        private int cherry;

        //builder methods for setting property
        public Builder sugar(double cup){this.sugar = cup; return this; }
        public Builder butter(double cup){this.butter = cup; return this; }
        public Builder eggs(int number){this.eggs = number; return this; }
        public Builder vanila(int spoon){this.vanila = spoon; return this; }
        public Builder flour(double cup){this.flour = cup; return this; }
        public Builder bakingpowder(double spoon){this.sugar = spoon; return this; }
        public Builder milk(double cup){this.milk = cup; return this; }
        public Builder cherry(int number){this.cherry = number; return this; }
        //return fully build object
        public Cake build() {
            return new Cake(this);

    //private constructor to enforce object creation through builder
    private Cake(Builder builder) {
        this.sugar = builder.sugar;
        this.butter = builder.butter;
        this.eggs = builder.eggs;
        this.vanila = builder.vanila;
        this.flour = builder.flour;
        this.bakingpowder = builder.bakingpowder;
        this.milk = builder.milk;
        this.cherry = builder.cherry;      

    public String toString() {
        return "Cake{" + "sugar=" + sugar + ", butter=" + butter + ", eggs=" + eggs + ", vanila=" + vanila + ", flour=" + flour + ", bakingpowder=" + bakingpowder + ", milk=" + milk + ", cherry=" + cherry + '}';


Cake{sugar=0.75, butter=0.5, eggs=2, vanila=2, flour=1.5, bakingpowder=0.0, milk=0.5, cherry=0}

2. Builder design pattern in Java – Pros and Cons

Live everything Builder pattern also has some disadvantages, but if you look at below, advantages clearly outnumber disadvantages of Builder design pattern. Any way here are few advantages and disadvantage of Builder design pattern for creating objects in Java.

1) more maintainable if number of fields required to create object is more than 4 or 5.
2) less error-prone as user will know what they are passing because of explicit method call.
3) more robust as only fully constructed object will be available to client.

1) verbose and code duplication as Builder needs to copy all fields from Original or Item class.

3. When to use Builder Design pattern in Java

Builder Design pattern is a creational pattern and should be used when number of parameter required in constructor is more than manageable usually 4 or at most 5. Don't confuse with Builder and Factory pattern there is an obvious difference between Builder and Factory pattern, as Factory can be used to create different implementation of same interface but Builder is tied up with its Container class and only returns object of Outer class.

That's all on Builder design pattern in Java. we have seen why we need Builder pattern , what problem it solves, Example of builder design pattern in Java and finally when to use Builder patter with pros and cons. So if you are not using telescoping constructor pattern or have a choice not to use it than Builder pattern is way to go.

Further Learning
Design Pattern Library
From 0 to 1: Design Patterns - 24 That Matter - In Java
Java Design Patterns - The Complete Masterclass

Other Java design pattern tutorials from Javarevisited blog :


yuri said...


Nice article. My doubt if it is possible mix the Builder and Factory Pattern?

Example: Constructing a class from xml config file with factories for selecting adequate implementation to the builder fields


Anonymous said...

Thank you for the tutorial.

My question is: if I write new Cake.Builder().build(); the code will compile and execute but I will lose the benefit of having a fully constructed object, it is similar to call the default constructor. Is there a more elaborate version of this pattern that will check parameters before calling the constructor of do we have to do it on our own ?


Javin Paul said...

@Anonymous, You have raised a valid scenario, If Any object has combination of mandatory and optional parameter than before building, build method can check if those parameters are provided or not and it can throw Exception, similar to IllegalArgumentException.


marcocast said...

@Anonymous and @Javin Paul
What if, instead of throwing exceptions, the API is done as such that the builder dictates which method is possible to call or not?
I described how, using the step builder pattern, in an article here :

Javin @ Must Override super class method Error said...

Hi moshii, totally agree with you , a class diagram will certainly helps to understand design pattern better. Noted and will add a class diagram here. Thanks

Anonymous said...

I see "this" is returned from all builder-parts, but how does that work, the builder is a static class and static classes can't have a "this" reference. So what am I missing.
(I understand the pattern otherwise, it's just the "this" reference I don't get=

Anto Paul said...

This is a variant of Fluent Interface( used in DSL.

There is no need to copy all the fields from Cake to Builder class. Just keep an instance of Cake in Builder class.

chezlesbelges said...

I'm with JohnMunsch, even if your code is valuable, don't call it builder pattern.
The examples on wikipedia are the builder pattern:

In your code; it is a builder, not a pattern.

Pensiero said...

Hey man! this is not the builder pattern! Study GoF please!

Anonymous said...

What's the point in complaining about whether this is strictly a Builder or not? The version here could be called a "Light Builder" that combines Director and Product but still reduces errors and makes code more fluent.My thanks to the author.

Satya said...

This is called Template pattern. You can see the same example in Effective java book.

Satya said...

Sorry, this one is Telescopic pattern not template pattern.

Anonymous said...

another drawback is you can't debug easily.

tehemperorer said...

If there are defaults that are included for every instance of cake that is to be returned, then change the access modifiers of all required methods to private, and include them in the method body of the build() method. That way, whenever build() is invoked, there will be a default object initialized. Also, since those methods are private but included in the build() method, the method chaining is cut back a little, and the invoker doesn't need to know which methods of Builder are required and which aren't.

Anonymous said...

This is really a awesome blog. The example and the explanation is really appreciable. Thanks for providing tutorial on builder design pattern.

Anonymous said...

why like this
public Builder bakingpowder(double spoon){
this.sugar = spoon;
return this;
not like this:

public Builder bakingpowder(double spoon){
this.bakingpowder = spoon;
return this;


Anonymous said...

I really like your technique of the embedded builder object and it's fluent (as in Google's fluent) style of taking parameters and using them to build the final instance of the object. That's neat.

However, this version of the "builder" pattern is pretty different from the builder pattern that you would see in the original Gang of Four book. There they view the pattern as a form of translation between a set of initialization data and several possible outputs for the same data. Their example is reading an RTF file and having different converters produce several different output formats of that same file (ASCII, TeX, etc.).

In your case you're always producing the same output class as a result of the building process, you've just ensuring avoiding inconsistency, making it easier to build the object, etc.

If I were to ask you about the builder pattern from the GoF book I wouldn't see those as being that similar.

Anonymous said...

Hi Javin,

I guess your pattern panned out very well. But I want you to elaborate more on the return types. I feel their use without explanation in this pattern, it seems, both mystery and indulgence- on your part- to me. Your answer will offer a better perspective for a beginner like me.

Thanks and Well appreciated

Unknown said...

Can i remove the member variables in the Builder with a Cake variable and have the builder methods like eggs, butter, milk set the value on the Cake variable? Is it a good approach? Or am I doing something very wrong?

public static class Builder {

private Cake cake;

public Builder() {
cake = new Cake();

public Builder sugar(double cup){cake .sugar = cup; return this; }
public Builder butter(double cup){cake .butter = cup; return this; }
public Builder eggs(int number){cake .eggs = number; return this; }

public Cake build() {
return cake ;


javin paul said...

Hello @Jebin Joshep. If you do that you are not using a Builder pattern, because your Cake object is created even before calling a build() method, also the fluency of code will lost e.g. its not possible to create object with configuration in one line.

In Builder pattern :
Cake whiteCake = new Cake.Builder().sugar(1).butter(0.5). eggs(2).vanila(2).flour(1.5). bakingpowder(0.75).milk(0.5).build();

In our case
Builder myBuilder = new Builder();

Which is not very different than Cake myCake = new Cake(); and then setting values e.g. myCake.sugar(2).eggs(2) etc.

Anonymous said...

What if i use, setters after creating the CAKE object, not getting "leaving Object on inconsistent state during building". What happens if create the CAKE first then i add the ingredients to it. I know in real time it is not possible.

Anonymous said...

why dont we have those setter and build methods inside Cake, why we need static nested class here.

Russell Bateman said...

Nice, but your cake won't rise without backing powder. Check your bakingpowder() method.

javin paul said...

@Unknown, good spot, bakingPowder is never assigned value :-), will correct it. Thanks

Anonymous said...

Joshua Bloch gave this example in his excellent book and mentioned that this pattern is similar to GoF Builder in his excellent book.

And after that, all the bloggers and people who love superficiality of things took Bloch's example, changed it one way and another and presented it as Builder Pattern.

Folks, this is enough. Don't represent this as a Builder Pattern anymore. If you want to give an example on Builder Pattern, please be in line with the book which coined the term "Builder Pattern"

Paul Coombes said...

Nice article and it explained a lot for more.
Surprisd no one noticed the following typo:

public Builder bakingpowder(double spoon){this.sugar = spoon; return this; }

Paul Coombes said...

Oh, they did. Wish I could retract my comment :-(

Post a Comment

Pepperjam Verification