[hibernate-dev] api/doc suggestions

[Sanne Grinovero]

Hi Max,

some thoughts inline:

On Sun, 9 Feb 2020 at 08:34, Max Rydahl Andersen <manderse at redhat.com> wrote:
>
> Heya,
>
> While working on Quarkus a few of us (Georgios in cc and I in
> particular) been pondering on doing a guide on best approaches on
> how to access data a bit more raw (i.e. raw sql, stateless season, etc.)
> as we got quite a lot of feedback stating Hibernate/JPA was considered
> complex in comparison to things like Spring Data and JDBC.
>
> When you go look its as if Spring Data and JDBC copied a lot of the
> patterns/access patterns we had in Hibernate before neither of those two
> existed :)
>
> Unfortunately, there are though a few gotchas I think would be great if
> we could somehow improve.
>
> Sanne suggested me to post to this list to start the conversation -
> there might come some more once I get going on writing the full guide;
> but wanted to get it started sooner rather than later.
>
> ### Document simplest programatic configuration
> (This might just be "max is stupid" issue - please tell me :)
>
> Trying to do a simple java main method booting Hibernate I could not
> figure out with the "new" metadata API a simple way to just start
> Hibernate.
>
> What is the equivalent way to do this in new metadata api:
>
> ```
> new Configuration().setProperty("hibernate.dialect",
> "org.hibernate.dialect.H2Dialect")
>                      .setProperty("hibernate.connection.url",
> "jdbc:h2:./sakila")
>                      .setProperty("hibernate.connection.username", "sa")
>                      .buildSessionFactory();
> ```
>
> Just setup dialect, give connection info and get a
> sessionfactory/entitymanager ?
>
> I found apis to start from a file containing those settings; but I
> really just want a programmatic api
> to use in batch script etc. without a need for external files.

Agreed we should explore making the "frameworkless bootstrap" simpler;
booting the ORM today requires some expertise, resulting in people to
rely on other frameworks to do the job.

However, the possible configuration options we have today are
significant; there's good reasons to have them so while an helper
would be welcome, I don't expect we'll want to change or simplify the
existing boot code, as it's working and doing a great job. This would
rather provide a simple, limited alternative.

It will be necessary to clarify that the "simple" alternative is also
very limiting: for example I could see myself volunteering to create
such a little toy, but don't expect it to work in modular
environments, containers, pick up transaction managers, integrate with
DI frameworks, allow for Datasource injection, etc. etc.. Ok?

A consequence of such limitations would be that runtime performance
and efficiency would also be limited; let's be upfront about the
intent in the API documentation.

I can try toy with a POC but can't promise a quick turnaround on this
one; not least I'd need Steve's blessing and review:
 - https://hibernate.atlassian.net/browse/HHH-13862

Please comment on the JIRA or send a PR if you have a more concrete
idea or a draft.


> ### Non-documented Deprecation of `setResultTransformer()` and friends
>
> The [approach of using
> `setResultTransformer`](https://in.relation.to/2006/03/17/hibernate-32-transformers-for-hql-and-sql/)
> we've had "forever" and its exactly what spring data and jdbc are using
> in examples where they say data access are easier.
>
> We want to focus and use this kind of API in our Quarkus guides to
> educate this is available.
>
> Unfortunately in Hibernate 5.2+ that api got marked [as
> deprecated](https://github.com/hibernate/hibernate-orm/blob/7a51b12cbb9a33c4569e8fa8cac0e234c65bd9ba/hibernate-core/src/main/java/org/hibernate/query/Query.java#L1101)
> with no other documentation than a `@todo develop a new approach to
> result transformers`.
>
> The actual only proper reason I could find was mentioned in
> https://vladmihalcea.com/hibernate-resulttransformer/ where its pointed
> out that for now we couldn't do a related functional style api for this
> until Hibernate 6.
>
> The @deprecation makes all code using this in many ides get a strike
> through of that code, making people think it is bad to use when it is
> very much not the case.
>
> Any chance that deprecation can either be removed or at least documented
> to be less scary/more informative ?
> (I'll happily make a PR if can be pointed to the new better api?)

I'll leave this question to others: TBH I don't know the plan here.


> ### doWork missing on stateless session
>
> In similar vein `.connection()` on stateless session is marked as
> deprecated with [no alternative nor actual
> docs/info](https://github.com/hibernate/hibernate-orm/blob/master/hibernate-core/src/main/java/org/hibernate/StatelessSession.java#L169).
>
> on Session the alternative is `doWork`. Any reason why that api isn't
> available on stateless session ?
>
> Here again, the ask is so we can educate and point people to use
> statelessSession rather than dropping Hibernate fully and from that
> api if needed go do `.doWork()` rather than refer to deprecated
> `.connection()`

Makes sense, I believe we should be able to do this quickly:
 - https://hibernate.atlassian.net/browse/HHH-13861

Andrea volunteered to have a look; assigned to him assuming it's
straight forward; if it gets tricky we'll have to wait for Steve's
opinion.

Thanks!
Sanne