[hibernate-dev] api/doc suggestions

[Max Rydahl Andersen]

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.

### 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?)


### 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()`


Thanks,
/max
https://xam.dk/about