Bottom-up vs top-down object building in API

Question

I am trying to identify the pros and cons of two approaches to create an object to return from my generic API. I am thinking the first approach I am sketching out has the advantage of being easier to understand by offshore developers, while the second approach lends itself better to concurrency or more complicated logic on the client side.

Example object model:

class TopLevelResponse {
    String field1;
    String field2;
    MidLevelResponse field3;
    ResponseMisc[] field4;
}

class MidLevelResponse {
    String field1;
    BottomLevelResponse field2;
}

class BottomLevelResponse {
    String field1;
    String[] field2;
}

class ResponseMisc {
    String field1;
    String field2;
}

First top-down case where each branching object is created whenever a child field is initialized:

class MyResponseInitializer {
    TopLevelResponse rsp;
    TopLevelResponse getTopLevelResponse() {
        if (Objects.isNull(rsp)) rsp = new TopLevelResponse();
        return rsp;
    }
    MidLevelResponse getMidLevelResponse() {
       if (Objects.isNull(getTopLevelResponse().getMidLevelResponse())
           getTopLevelResponse().setMidLevelResponse(new MidLevelResponse());
       return getTopLevelResponse().getMidLevelResponse();
    }
    ...
    void setField1(String val) {
        getTopLevelResponse().setField1(val);
    }
    void setField2(String val) ...
    void setMidLevelField1(String val) ...
    ...
} 

And on client side:

...
MyResponseInitializer rspInit = new MyResponseInitializer();
rspInit.setField1("foo");
rspInit.setField2("bar");
rspInit.setMidLevelField1("baz");
...
TopLevelResponse rsp = rspInit.getTopLevelResponse();

Compare to a bottom-up approach like this, where initialization is performed by a series of builders:

static class BottomLevelResponseBuilder(){
     ...
     BottomLevelResponse build()...
}
static class MidLevelResponseBuilder()
...
static class TopLevelResponseBuilder()
...

Which on client side looks like this:

TopLevelResponse rsp = TopLevelResponseBuilder.newInstance()
                           .field1("foo")
                           .field2("bar")                                             
                           .field3(MidLevelResponseBuilder.newInstance()
                                .field1("baz")...
                       ...
                       .build();

What are the pros vs cons of either approach here? Am I right to think that the first approach is better from a defensive programming perspective, since it reduces the risk of rogue implementations by offshore devs? Or that using concurrency to create each branch on a separate thread can pay off especially with more nesting involved in the data model if I use approach 2?

Answer 1

Defensive Code and Rogue implementation by offshore devs - Both the reasons should not be the criteria for choosing/not choosing builder.

When do we generally use builder? When you have a complex object to be created and not all fields are required during instantiation, rather than providing overloaded constructors (which the offshore devs can mess up while using), you provide more inferable static methods to set the fields.

Does this mean you will not provide setters for some/all fields? Not really. Depends on your application and how the values of the fields change. Will this allow for rogue implementations? Regardless of what patterns are used, rogue implementations are always possible, and this can only be caught during design/code reviews or by proactively letting the team know of what has been done for them to notice.

"Using concurrency to create each branch on a separate thread" : Is your Class that heavy that it needs multiple threads to create a single object of that class? You can relook at that actually. Anyway, even in the first case you can have setters called from each thread.

For your use case, go with the builder pattern, and if you are really concerned, you can create private setters so that they are not implemented (which again I don't prefer).

Answer 2

I can see your point about top down vs bottom up but what you're really contrasting here is a half baked Java Bean initializer with the Joshua Bloch Builder (not to be confused with the very different GoF Builder).

Java Beans have a no arg constructor, are serializable, and have setters for each field. These were designed so persistence libraries could use reflection to figure out how to build them. They were never designed for humans. But lazy humans decided it was a workable pattern and started imitating them even when a persistence library wasn't being used.

The Joshua Bloch Builder is designed for humans and offers a lot of features that Java Beans don't have:

• Immutable - the final object can be trusted to stay the same since it's in its final state when it's born. No need for setters.
• Null free - the final object is never in a partially completed state because it isn't constructed until all the fields are known.
• Self consistent - validation can easily consider the whole object, not just the single field being set.

Both patterns simulate named arguments in languages that don't have them (like Java) which humans prefer to long constructors. Both involve considerable boiler plate code to make them work. Both are reasonable to use to construct basic objects. Neither requires a complex object structure to justify them.

The half baked Beans advantage is that it's older and more familiar. That doesn't really mean its better.

So yes I’d prefer a Bloch builder solution if a simple constructor is out of the question. But I’d prefer the builder using code looked like this:

TopLevelResponse fooishResponse(
        TopLevelResponseBuilder top,
        MidLevelResponseBuilder mid
) {
    return top
        .newInstance()
        .field1("foo")
        .field2("bar")                                             
        .field3(mid
            .newInstance()
            .field1("baz")
        )
        .build()
    ;
}

Done this way you are not locked into any particular implementation of the builders. I find this way of laying out the code easy on the eyes.

As for rogue implementations, put the builders in the same package as what they build and make the constructor protected and most people won’t be building this on their own.