Hey there, I have a question regarding the builder pattern that I need someone with more experience to clarify for me.

I have this User class that has an inner, public static Builder class that has the same fields as User as well as the corresponding setter methods. Now, the setter methods inside the Builder class return this (the builder instance), and after everything is set, the instance of the builder is passed to Builder.build(this) method that returns a User instance with the fields.

My question is that I can make User setter methods to return this (User object) and render the inner Builder class unnecessary. However, since it is there, I assume there might be some reason why it is so. Anybody any suggestion as to why is one way better than the other?

Thanks in advance.

the instance of the builder is passed to Builder.build(this) method

That sounds like you are passing an instance of Builder to a static method of Builder, which seems very unlikely.

I can think of two answers to your question. My favorite is that objects that never change are easier to use and safer than objects that change. If your program ever has problems, finding those problems will always be made harder by each object that may be changing over its lifetime, especially if multiple threads are involved. Even better than an object that never changes is an object that cannot change because it has methods that could cause it to change if called.

Another answer to your question is that even when an object is allowed to change over time, there are often constraints about what states are legal. You'll probably run into this in practice, but realistic examples are difficult to construct artificially. An unrealistic example would be a class ShapePosition that contains a Point and a Shape, and requires that the Point always be inside the Shape. It would be impossible to construct a ShapePosition by using a no-arguments constructor followed by setPoint, and setShape without causing the ShapePosition to exist briefly in an illegal state, and that means you won't be able to enforce that every ShapePosition must always be legal. Using a builder, you can completely avoid that issue by allowing the builder to be in states that wouldn't be legal for the final object and then checking that the state is legal in the build method.

hey bguild,
no, build method is not a static one. I was just trying to indicate that it is inside Builder. Sorry for the confusion. thanks for your answer. My understanding is that you say that I use a Builder inner class so that I do not have to write setter methods in my User class, and thus make User immposible to change state? Correct? But then, is there any downside to returning User from its setter methods instead of void if I decide to use them (other than making User possible to change state)? My previous assumption was that I only use Builder pattern so that I make possible setter method chaining.

The idea is to ensure that you always get a valid completely initialised object - you keep calling the setters in the builder until your object is fully specified, then, and only then, you call build() and that returns a complete valid object (or throws some kind of "incomplete or invalid" exception).
If you just create a new object then call its setters you cannot guarantee that the object will be complete and valid, or maybe there's exact subclass you need to create depending on the supplied values.

The reason the builder's setters return the builder object is so you can chain calls, as in
myObject = new Builder().setThing(value1).setOther(value2).setAnother(value3).build();

thank you guys very much. I now think I have a better idea of what Builder pattern is useful for. Thank you again.