From d39cf372ec14a6476d67f2853c160af65bb3e33b Mon Sep 17 00:00:00 2001
From: Gavin King <gavin@hibernate.org>
Date: Sat, 13 Sep 2025 10:18:24 +0200
Subject: [PATCH] improve javadoc for session builders

---
 .../java/org/hibernate/SessionBuilder.java    | 20 ++++++++++++-
 .../org/hibernate/SharedSessionBuilder.java   | 30 ++++++++++++++++++-
 .../SharedStatelessSessionBuilder.java        | 29 ++++++++++++++++--
 .../hibernate/StatelessSessionBuilder.java    |  4 ++-
 .../engine/creation/CommonBuilder.java        | 20 ++++++++++++-
 5 files changed, 96 insertions(+), 7 deletions(-)

diff --git a/hibernate-core/src/main/java/org/hibernate/SessionBuilder.java b/hibernate-core/src/main/java/org/hibernate/SessionBuilder.java
index 3cbfaf593111..52491952f407 100644
--- a/hibernate-core/src/main/java/org/hibernate/SessionBuilder.java
+++ b/hibernate-core/src/main/java/org/hibernate/SessionBuilder.java
@@ -13,11 +13,29 @@
 import org.hibernate.resource.jdbc.spi.StatementInspector;
 
 /**
- * Allows creation of a new {@link Session} with specific options.
+ * Allows creation of a new {@link Session} with specific options
+ * overriding the defaults from the {@link SessionFactory}.
+ * <pre>
+ * try (var session =
+ *         sessionFactory.withOptions()
+ *             .tenantIdentifier(tenantId)
+ *             .initialCacheMode(CacheMode.PUT)
+ *             .flushMode(FlushMode.COMMIT)
+ *             .interceptor(new Interceptor() {
+ *                 &#64;Override
+ *                 public void preFlush(Iterator&lt;Object&gt; entities) {
+ *                     ...
+ *                 }
+ *             })
+ *             .openSession()) {
+ *     ...
+ * }
+ * </pre>
  *
  * @author Steve Ebersole
  *
  * @see SessionFactory#withOptions()
+ * @see SharedSessionBuilder
  */
 public interface SessionBuilder extends CommonBuilder {
 	/**
diff --git a/hibernate-core/src/main/java/org/hibernate/SharedSessionBuilder.java b/hibernate-core/src/main/java/org/hibernate/SharedSessionBuilder.java
index aa73b84f171a..b9e05231e58e 100644
--- a/hibernate-core/src/main/java/org/hibernate/SharedSessionBuilder.java
+++ b/hibernate-core/src/main/java/org/hibernate/SharedSessionBuilder.java
@@ -13,11 +13,39 @@
 import java.util.function.UnaryOperator;
 
 /**
- * Specialized {@link SessionBuilder} with access to stuff from another session.
+ * Allows creation of a child {@link Session} which shares some options with
+ * another pre-existing parent session. Each session has its own isolated
+ * persistence context, and entity instances must not be shared between
+ * parent and child sessions.
+ * <p>
+ * When {@linkplain Transaction resource-local} transaction management is used:
+ * <ul>
+ * <li>by default, each session executes with its own dedicated JDBC connection
+ *     and therefore has its own isolated transaction, but
+ * <li>calling the {@link #connection()} method specifies that the connection,
+ *     and therefore also the JDBC transaction, should be shared from parent
+ *     to child.
+ * </ul>
+ * <p>
+ * <pre>
+ * try (var childSession
+ *          = session.sessionWithOptions()
+ *                  .connection() // share the JDBC connection
+ *                  .cacheMode(CacheMode.IGNORE)
+ *                  .openSession()) {
+ *     ...
+ * }
+ * </pre>
+ * <p>
+ * On the other hand, when JTA transaction management is used, all sessions
+ * execute within the same transaction. Typically, connection sharing is
+ * handled automatically by the JTA-enabled {@link javax.sql.DataSource}.
  *
  * @author Steve Ebersole
  *
  * @see Session#sessionWithOptions()
+ * @see StatelessSession#sessionWithOptions()
+ * @see SessionBuilder
  */
 public interface SharedSessionBuilder extends SessionBuilder, CommonSharedBuilder {
 
diff --git a/hibernate-core/src/main/java/org/hibernate/SharedStatelessSessionBuilder.java b/hibernate-core/src/main/java/org/hibernate/SharedStatelessSessionBuilder.java
index 0a6323f9312f..703a748e07cf 100644
--- a/hibernate-core/src/main/java/org/hibernate/SharedStatelessSessionBuilder.java
+++ b/hibernate-core/src/main/java/org/hibernate/SharedStatelessSessionBuilder.java
@@ -11,12 +11,35 @@
 import java.util.function.UnaryOperator;
 
 /**
- * Allows for creation of a {@linkplain StatelessSession stateless session} sharing the
- * underpinnings of another {@linkplain Session stateful} or {@linkplain StatelessSession stateless}
- * session.
+ * Allows creation of a child {@link StatelessSession} which shares some options
+ * with another pre-existing parent session.
+ * <p>
+ * When {@linkplain Transaction resource-local} transaction management is used:
+ * <ul>
+ * <li>by default, each session executes with its own dedicated JDBC connection
+ *     and therefore has its own isolated transaction, but
+ * <li>calling the {@link #connection()} method specifies that the connection,
+ *     and therefore also the JDBC transaction, should be shared from parent
+ *     to child.
+ * </ul>
+ * <p>
+ * <pre>
+ * try (var statelessSession
+ *          = session.statelessWithOptions()
+ *                  .connection() // share the JDBC connection
+ *                  .cacheMode(CacheMode.IGNORE)
+ *                  .openStatelessSession()) {
+ *     ...
+ * }
+ * </pre>
+ * <p>
+ * On the other hand, when JTA transaction management is used, all sessions
+ * execute within the same transaction. Typically, connection sharing is
+ * handled automatically by the JTA-enabled {@link javax.sql.DataSource}.
  *
  * @see Session#statelessWithOptions()
  * @see StatelessSession#statelessWithOptions()
+ * @see SharedSessionBuilder
  *
  * @since 7.2
  *
diff --git a/hibernate-core/src/main/java/org/hibernate/StatelessSessionBuilder.java b/hibernate-core/src/main/java/org/hibernate/StatelessSessionBuilder.java
index 29e1a1ebe008..0e21fa9a74e2 100644
--- a/hibernate-core/src/main/java/org/hibernate/StatelessSessionBuilder.java
+++ b/hibernate-core/src/main/java/org/hibernate/StatelessSessionBuilder.java
@@ -12,11 +12,13 @@
 import org.hibernate.resource.jdbc.spi.StatementInspector;
 
 /**
- * Allows creation of a new {@link StatelessSession} with specific options.
+ * Allows creation of a new {@link StatelessSession} with specific options
+ * overriding the defaults from the {@link SessionFactory}.
  *
  * @author Steve Ebersole
  *
  * @see SessionFactory#withStatelessOptions()
+ * @see SharedStatelessSessionBuilder
  */
 public interface StatelessSessionBuilder extends CommonBuilder {
 	/**
diff --git a/hibernate-core/src/main/java/org/hibernate/engine/creation/CommonBuilder.java b/hibernate-core/src/main/java/org/hibernate/engine/creation/CommonBuilder.java
index 4be9edcefbeb..44c2bc631295 100644
--- a/hibernate-core/src/main/java/org/hibernate/engine/creation/CommonBuilder.java
+++ b/hibernate-core/src/main/java/org/hibernate/engine/creation/CommonBuilder.java
@@ -124,7 +124,15 @@ public interface CommonBuilder {
 	CommonBuilder noStatementInspector();
 
 	/**
-	 * Define the tenant identifier to be associated with the opened session.
+	 * Specify the tenant identifier to be associated with the opened session.
+	 * <pre>
+	 * try (var session =
+	 *         sessionFactory.withOptions()
+	 *             .tenantIdentifier(tenantId)
+	 *             .openSession()) {
+	 *     ...
+	 * }
+	 * </pre>
 	 *
 	 * @param tenantIdentifier The tenant identifier.
 	 *
@@ -160,6 +168,16 @@ public interface CommonBuilder {
 	 * possible to structure data access code in a way which eliminates
 	 * this possibility.
 	 * <p>
+	 * <pre>
+	 * try (var readOnlySession =
+	 *         sessionFactory.withOptions()
+	 *                 .readOnly(true)
+	 *                 .initialCacheMode(CacheMode.IGNORE)
+	 *                 .openSession()) {
+	 *     ...
+	 * }
+	 * </pre>
+	 * <p>
 	 * If a session is created in read-only mode, then it cannot be
 	 * changed to read-write mode, and any call to
 	 * {@link Session#setDefaultReadOnly(boolean)} with fail. On the