Presentation at JCrete.org

[Brian Goetz]

> One observation I’d make here is that the JEP presents an example in the form of a QueryBuilder template processor to produce a PreparedStatement. Per the Javadoc of Connection, this may well result in a side-effect by sending the query to the server for precompilation / validation.
>
> I think it’s worth having a consistent story to people when presenting the feature - in the JEP example, it would feel a little unwieldy for QueryBuilder to return its own thunky DeferredPreparedStatement, or similar, for the caller to work with.


I'm kind of surprised no one has pointed this out yet :)

The naive interpretation here is "Wait, on one hand you say side effects 
are bad, on the other you given an example with side effects.  
Inconsistant!"  But as always, the reality is more subtle.

The spirit here is that the template processor is a *function*, taking 
some template-shaped ingredients and turning it into a useful *thing*, 
that you can then further use or manipulate.  It should have the effect 
of a factory, whether producing a String or a JsonDocument or a 
ResultSet.  The latter is interesting in that the factory has to make a 
connection to produce the result set, but what the processor is doing is 
*making a result set*.   A constructor or "factory" that produced 
nothing and operated primarily through side-effects would rightly be 
declared to be a poor API.

The ResultSet example is fine, because it's not confusing what is going 
on -- I describe my query with a template, and I get back a ResultSet, 
which is then my responsibility to iterate or not, and close when done.  
It is a factory for result sets.  Whereas the LOG example is not, 
because it it is intrinsically confusing.  "Derive an X from a Y" is 
behavior one can generally intuit purely from the type Function<X,Y> 
(and knowledge of what X and Y are).  "Do an arbitrary side effect" is 
not.  If you want to do arbitrary side effects, write methods whose 
names clearly describe the behavior of the method.

(I think everyone pretty much knows this, but then gets distracted by 
"but performance" or "but its more characters".  Again, we can't save 
people from themselves, but we can set good examples.)

What this whole thread reinforces for me is that we need to have a 
document (like "Programmers Guide to Text Blocks") that spells out the 
principles.  In the meantime, hopefully my words shall suffice :)