Add a tap method to builders

[melix]

The builder pattern is nice, but it's frequent that you have some
conditional logic which forces you to interrupt the flow, assign
the builder to a temporary variable, do something on the builder,
then resume the fluent API like mode. A trivial example would be:

TypeSpec.Builder typeBuilder = TypeSpec.classBuilder(...)
myMethods.forEach(typeBuilder::addMethod);
return typeBuilder.build()

This commit introduces a tap method on builders which avoids
the need of an intermediate variable by allowing to swich context
in a lambda, and apply the conditional logic (or more programmatic
work) within the lambda.

The code above would be rewritten as:

return TypeSpec.classBuilder(...)
    .tap(c -> methods.forEach(c::addMethod))
    .build()

Which looks more functional style. Of course real world
examples the conditional logic is more complex ;)

[swankjesse]

This reminds me of apply() in Kotlin. Is there another popular Builder API that does this? I’m reluctant to add syntax to JavaPoet because Java isn't expressive.

[melix]

I don't know if there are other popular libraries using this pattern, but I've not seen many exposing builders like Javapoet does. From my point of view, I've been using Javapoet in pure Java for the past couple weeks and I've been annoyed several times that this method is not available. Of course you could say "use Kotlin" but it's a no-go: it would make the library too heavy for what it's doing.