examples of a couple of nice ways to use the Session

hibernate-core/src/main/java/org/hibernate/Session.java

@@ -7,11 +7,13 @@
 package org.hibernate;
 
 import java.util.List;
+import java.util.function.Consumer;
 
 import jakarta.persistence.CacheRetrieveMode;
 import jakarta.persistence.CacheStoreMode;
 import jakarta.persistence.PessimisticLockScope;
 import org.hibernate.graph.RootGraph;
+import org.hibernate.jdbc.Work;
 import org.hibernate.query.Query;
 import org.hibernate.stat.SessionStatistics;
 
@@ -113,6 +115,25 @@ import jakarta.persistence.criteria.CriteriaUpdate;
  *     instance from the {@link SessionFactory}.
  * </ul>
  * <p>
+ * An easy way to be sure that session and transaction management is being done correctly
+ * is to {@linkplain SessionFactory#inTransaction(Consumer) let the factory do it}:
+ * <pre>
+ * sessionFactory.inTransaction(session -> {
+ *     //do the work
+ *     ...
+ * });
+ * </pre>
+ * <p>
+ * A session may be used to {@linkplain #doWork(Work) execute JDBC work} using its JDBC
+ * connection and transaction:
+ * <pre>
+ * session.doWork(connection -> {
+ *     try ( PreparedStatement ps = connection.prepareStatement( " ... " ) ) {
+ *         ps.execute();
+ *     }
+ * });
+ * </pre>
+ * <p>
  * A {@code Session} instance is serializable if its entities are serializable.
  * <p>
  * Every {@code Session} is a JPA {@link EntityManager}. Furthermore, when Hibernate is
@@ -136,9 +157,9 @@ public interface Session extends SharedSessionContract, EntityManager {
 	/**
 	 * Force this session to flush. Must be called at the end of a unit of work,
 	 * before the transaction is committed. Depending on the current
-	 * {@link #setHibernateFlushMode(FlushMode)} flush mode}, the session might automatically
-	 * flush when {@link Transaction#commit()} is called, and it is not necessary
-	 * to call this method directly.
+	 * {@linkplain #setHibernateFlushMode(FlushMode) flush mode}, the session might
+	 * automatically flush when {@link Transaction#commit()} is called, and it is not
+	 * necessary to call this method directly.
 	 * <p>
 	 * <em>Flushing</em> is the process of synchronizing the underlying persistent
 	 * store with persistable state held in memory.

hibernate-core/src/main/java/org/hibernate/engine/jdbc/LobCreator.java

@@ -5,6 +5,7 @@
  * See the lgpl.txt file in the root directory or <http://www.gnu.org/licenses/lgpl-2.1.html>.
  */
 package org.hibernate.engine.jdbc;
+
 import java.io.InputStream;
 import java.io.Reader;
 import java.sql.Blob;
@@ -13,9 +14,12 @@ import java.sql.NClob;
 
 /**
  * Contract for creating various LOB references.
- * 
+ *
  * @author Steve Ebersole
  * @author Gail Badner
+ *
+ * @see org.hibernate.type.descriptor.WrapperOptions#getLobCreator()
+ * @see org.hibernate.LobHelper
  */
 public interface LobCreator {
 	/**

hibernate-core/src/main/java/org/hibernate/jdbc/package-info.java

@@ -12,6 +12,16 @@
  * Execution of a unit of work may be requested by calling
  * {@link org.hibernate.SharedSessionContract#doWork(org.hibernate.jdbc.Work)} or
  * {@link org.hibernate.SharedSessionContract#doReturningWork(org.hibernate.jdbc.ReturningWork)}.
+ * <p>
+ * For example:
+ * <pre>
+ * session.doWork(connection -> {
+ *     try ( PreparedStatement ps = connection.prepareStatement( " ... " ) ) {
+ *         ps.execute();
+ *     }
+ * });
+ * </pre>
+ *
  *
  * @see org.hibernate.jdbc.Work
  * @see org.hibernate.jdbc.ReturningWork