[hibernate-dev] api/doc suggestions

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/7a51b12cbb9a3... 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/hiberna.... 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