Builder Pattern inside vs outside class?

Question

What are the advantages between using the builder pattern within vs outside the class?

Inside class:

public class Person {
    private String name;
    private String eyeColor;
    private String hairColor;

    public Person setName(String name) {
        this.name = name;
        return this;
    }

    public Person setEyeColor(String eyeColor) {
        this.eyeColor = eyeColor;
        return this;
    }

    public Person setHairColor(String hairColor) {
        this.hairColor = hairColor;
        return this;
    }
} 

// Example usage:
Person p = new Person()
                 .setName("Bob")
                 .setHairColor("Black")
                 .setEyeColor("Brown")

Outside class:

public class Person {
    private String name;
    private String eyeColor;
    private String hairColor;

    public Person(String name, String eyeColor, String hairColor) {
        this.name = name;
        this.eyeColor = eyeColor;
        this.hairColor = hairColor; 
    }  
} 

public class PersonBuilder {
    private String name;
    private String eyeColor;
    private String hairColor;

    public Person build() {
        return new Person(name, eyeColor, hairColor);
    }

    public PersonBuilder with(String name) {
        this.name = name;
        return this;
    }

    public PersonBuilder setEyeColor(String eyeColor) {
        this.eyeColor = eyeColor;
        return this;
    }

    public PersonBuilder setHairColor(String hairColor) {
        this.hairColor = hairColor;
        return this;
    }
} 

// Example usage:
Person p = new PersonBuilder()
                 .setName("Bob")
                 .setHairColor("Black")
                 .setEyeColor("Brown")
                 .build();

Answer 1

It depends.

I often combine Builder and Factory patterns so it makes sense to have the Builder as an outside class since the "built" object could be one of many implementations. This has an added benefit of allowing the implementations to be package private or even private inner classes of the Builder.

If you are using the Builder to just make the constructor of a public class more intent revealing or less cluttered than it is really personal preference. One could weigh the pros and cons of having an additional class in the API which could make it confusing for users.

However, I recommend picking one of the options and sticking with it throughout the API. It makes the overall system architecture easier to understand if all Builders are either inner classes or outer classes; don't mix them.

Don't mix inner and Outer Builders like this:

Foo foo = new Foo.Builder(...)

Bar bar = new BarBuilder(...)

Answer 2

The 2nd implementation assure you that you'll get a finished object and thus make it more reliable implementation while the first is unstated untill u finish setting all the fields.

in general you dont want unstated object to be available for use.