Presentation at JCrete.org

[David Alayachew]

Hello Brian,

Thanks for the clarification, that's helpful!

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

Maybe not this thread specifically, but a LOT of people have been confused
about this. Multiple times on amber-dev even, let alone reddit (before the
whole spez thing). A lot of people (me included) pretty stopped asking
about that example because we never got any definitive responses. Up until
now, I haven't seen a definitive answer as to why that example was left in.
This definitely suffices though.

> 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.

Ok, fair enough. I think the missing detail though is that, you need to
understand JDBC in order for that to answer follow up questions.

I am not very familiar with JDBC. So when I see a template processor called
DB, my first thought is that I can do DB stuff, including updates and
deletes. I was not aware that a ResultSet is more or less the output of a
SELECT. By all means, after doing a decent amount of reading, I understand
that now, but a lot of us never touch JDBC since we spend all our time in
Hibernate/JPA, so this example probably flew over a lot of heads.

I see the nuance in the example now, but I guarantee I am not the only one
who got lost in that example and thought that it was supporting
side-effects *because I saw DB*.

> 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 :)

100%, no question. I would have definitely thought that the JDBC example is
bad, so spelling out what is or isn't useful behaviour would behoove
everyone.

Thank you for the insight!
David Alayachew



On Mon, Jul 24, 2023 at 11:31 AM Brian Goetz <brian.goetz at oracle.com> wrote:

>
>
> > 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 :)
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/amber-dev/attachments/20230724/3b45cf2a/attachment-0001.htm>