+ * try (var session =
+ * sessionFactory.withOptions()
+ * .tenantIdentifier(tenantId)
+ * .initialCacheMode(CacheMode.PUT)
+ * .flushMode(FlushMode.COMMIT)
+ * .interceptor(new Interceptor() {
+ * @Override
+ * public void preFlush(Iterator<Object> entities) {
+ * ...
+ * }
+ * })
+ * .openSession()) {
+ * ...
+ * }
+ *
*
* @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.
+ * + * When {@linkplain Transaction resource-local} transaction management is used: + *
+ *
+ * try (var childSession
+ * = session.sessionWithOptions()
+ * .connection() // share the JDBC connection
+ * .cacheMode(CacheMode.IGNORE)
+ * .openSession()) {
+ * ...
+ * }
+ *
+ * + * 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. + *
+ * When {@linkplain Transaction resource-local} transaction management is used: + *
+ *
+ * try (var statelessSession
+ * = session.statelessWithOptions()
+ * .connection() // share the JDBC connection
+ * .cacheMode(CacheMode.IGNORE)
+ * .openStatelessSession()) {
+ * ...
+ * }
+ *
+ * + * 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. + *
+ * try (var session =
+ * sessionFactory.withOptions()
+ * .tenantIdentifier(tenantId)
+ * .openSession()) {
+ * ...
+ * }
+ *
*
* @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.
* + *
+ * try (var readOnlySession =
+ * sessionFactory.withOptions()
+ * .readOnly(true)
+ * .initialCacheMode(CacheMode.IGNORE)
+ * .openSession()) {
+ * ...
+ * }
+ *
+ * * 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