HHH-19737 - Support Envers with StatelessSession

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

@@ -8,6 +8,7 @@
 import java.util.TimeZone;
 import java.util.function.UnaryOperator;
 
+import org.hibernate.engine.creation.CommonBuilder;
 import org.hibernate.resource.jdbc.spi.PhysicalConnectionHandlingMode;
 import org.hibernate.resource.jdbc.spi.StatementInspector;
 
@@ -18,49 +19,21 @@
  *
  * @see SessionFactory#withOptions()
  */
-public interface SessionBuilder {
+public interface SessionBuilder extends CommonBuilder {
 	/**
 	 * Opens a session with the specified options.
 	 *
 	 * @return The session
 	 */
 	Session openSession();
 
-	/**
-	 * Adds a specific interceptor to the session options.
-	 *
-	 * @param interceptor The interceptor to use.
-	 *
-	 * @return {@code this}, for method chaining
-	 */
+	@Override
 	SessionBuilder interceptor(Interceptor interceptor);
 
-	/**
-	 * Signifies that no {@link Interceptor} should be used.
-	 * <p>
-	 * By default, if no {@code Interceptor} is explicitly specified, the
-	 * {@code Interceptor} associated with the {@link SessionFactory} is
-	 * inherited by the new {@link Session}.
-	 * <p>
-	 * Calling {@link #interceptor(Interceptor)} with null has the same effect.
-	 *
-	 * @return {@code this}, for method chaining
-	 */
+	@Override
 	SessionBuilder noInterceptor();
 
-	/**
-	 * Applies the given statement inspection function to the session.
-	 *
-	 * @param operator An operator which accepts a SQL string, returning
-	 *                 a processed SQL string to be used by Hibernate
-	 *                 instead of the given original SQL. Alternatively.
-	 *                 the operator may work by side effect, and simply
-	 *                 return the original SQL.
-	 *
-	 * @return {@code this}, for method chaining
-	 *
-	 * @since 7.0
-	 */
+	@Override
 	SessionBuilder statementInspector(UnaryOperator<String> operator);
 
 	/**
@@ -163,60 +136,13 @@ public interface SessionBuilder {
 	 * @return {@code this}, for method chaining
 	 * @since 6.4
 	 */
+	@Override
 	SessionBuilder tenantIdentifier(Object tenantIdentifier);
 
-	/**
-	 * Specify a {@linkplain Session#isDefaultReadOnly read-only mode}
-	 * for the session. If a session is created in read-only mode, then
-	 * {@link Connection#setReadOnly} is called when a JDBC connection
-	 * is obtained.
-	 * <p>
-	 * Furthermore, if read/write replication is in use, then:
-	 * <ul>
-	 * <li>a read-only session will connect to a read-only replica, but
-	 * <li>a non-read-only session will connect to a writable replica.
-	 * </ul>
-	 * <p>
-	 * When read/write replication is in use, it's strongly recommended
-	 * that the session be created with the {@linkplain #initialCacheMode
-	 * initial cache mode} set to {@link CacheMode#GET}, to avoid writing
-	 * stale data read from a read-only replica to the second-level cache.
-	 * Hibernate cannot possibly guarantee that data read from a read-only
-	 * replica is up to date.
-	 * <p>
-	 * When read/write replication is in use, it's possible that an item
-	 * read from the second-level cache might refer to data which does not
-	 * yet exist in the read-only replica. In this situation, an exception
-	 * occurs when the association is fetched. To completely avoid this
-	 * possibility, the {@linkplain #initialCacheMode initial cache mode}
-	 * must be set to {@link CacheMode#IGNORE}. However, it's also usually
-	 * possible to structure data access code in a way which eliminates
-	 * this possibility.
-	 * <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
-	 * other hand, if a session is created in read-write mode, then it
-	 * may later be switched to read-only mode, but all database access
-	 * is directed to the writable replica.
-	 *
-	 * @return {@code this}, for method chaining
-	 * @since 7.2
-	 *
-	 * @see org.hibernate.engine.jdbc.connections.spi.MultiTenantConnectionProvider#getReadOnlyConnection(Object)
-	 * @see org.hibernate.engine.jdbc.connections.spi.MultiTenantConnectionProvider#releaseReadOnlyConnection(Object, Connection)
-	 */
-	@Incubating
+	@Override
 	SessionBuilder readOnly(boolean readOnly);
 
-	/**
-	 * Specify the initial {@link CacheMode} for the session.
-	 *
-	 * @return {@code this}, for method chaining
-	 * @since 7.2
-	 *
-	 * @see SharedSessionContract#getCacheMode()
-	 */
+	@Override
 	SessionBuilder initialCacheMode(CacheMode cacheMode);
 
 	/**

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

@@ -4,6 +4,7 @@
  */
 package org.hibernate;
 
+import org.hibernate.engine.creation.CommonSharedBuilder;
 import org.hibernate.resource.jdbc.spi.PhysicalConnectionHandlingMode;
 import org.hibernate.resource.jdbc.spi.StatementInspector;
 
@@ -18,20 +19,12 @@
  *
  * @see Session#sessionWithOptions()
  */
-public interface SharedSessionBuilder extends SessionBuilder {
+public interface SharedSessionBuilder extends SessionBuilder, CommonSharedBuilder {
 
-	/**
-	 * Signifies that the connection from the original session should be used to create the new session.
-	 *
-	 * @return {@code this}, for method chaining
-	 */
+	@Override
 	SharedSessionBuilder connection();
 
-	/**
-	 * Signifies the interceptor from the original session should be used to create the new session.
-	 *
-	 * @return {@code this}, for method chaining
-	 */
+	@Override
 	SharedSessionBuilder interceptor();
 
 	/**
@@ -76,7 +69,7 @@ public interface SharedSessionBuilder extends SessionBuilder {
 	SharedSessionBuilder statementInspector(StatementInspector statementInspector);
 
 	@Override
-	SessionBuilder statementInspector(UnaryOperator<String> operator);
+	SharedSessionBuilder statementInspector(UnaryOperator<String> operator);
 
 	@Override @Deprecated
 	SharedSessionBuilder connectionHandlingMode(PhysicalConnectionHandlingMode mode);

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

@@ -26,6 +26,18 @@
  * @author Steve Ebersole
  */
 public interface SharedSessionContract extends QueryProducer, AutoCloseable, Serializable {
+
+	/**
+	 * Obtain a {@link StatelessSession} builder with the ability to copy certain
+	 * information from this session.
+	 *
+	 * @return the session builder
+	 *
+	 * @since 7.2
+	 */
+	@Incubating
+	SharedStatelessSessionBuilder statelessWithOptions();
+
 	/**
 	 * Obtain the tenant identifier associated with this session, as a string.
 	 *

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

@@ -0,0 +1,58 @@
+/*
+ * SPDX-License-Identifier: Apache-2.0
+ * Copyright Red Hat Inc. and Hibernate Authors
+ */
+package org.hibernate;
+
+import org.hibernate.engine.creation.CommonSharedBuilder;
+
+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.
+ *
+ * @see Session#statelessWithOptions()
+ * @see StatelessSession#statelessWithOptions()
+ *
+ * @since 7.2
+ *
+ * @author Steve Ebersole
+ */
+@Incubating
+public interface SharedStatelessSessionBuilder extends CommonSharedBuilder {
+	/**
+	 * Open the stateless session.
+	 */
+	StatelessSession open();
+
+	@Override
+	SharedStatelessSessionBuilder connection();
+
+	@Override
+	SharedStatelessSessionBuilder interceptor();
+
+	@Override
+	SharedStatelessSessionBuilder interceptor(Interceptor interceptor);
+
+	@Override
+	SharedStatelessSessionBuilder noInterceptor();
+
+	SharedStatelessSessionBuilder statementInspector(UnaryOperator<String> operator);
+
+	@Override
+	SharedStatelessSessionBuilder statementInspector();
+
+	@Override
+	SharedStatelessSessionBuilder noStatementInspector();
+
+	@Override
+	SharedStatelessSessionBuilder tenantIdentifier(Object tenantIdentifier);
+
+	@Override
+	SharedStatelessSessionBuilder readOnly(boolean readOnly);
+
+	@Override
+	SharedStatelessSessionBuilder initialCacheMode(CacheMode cacheMode);
+}

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

@@ -7,6 +7,7 @@
 import java.sql.Connection;
 import java.util.function.UnaryOperator;
 
+import org.hibernate.engine.creation.CommonBuilder;
 import org.hibernate.resource.jdbc.spi.StatementInspector;
 
 /**
@@ -16,118 +17,42 @@
  *
  * @see SessionFactory#withStatelessOptions()
  */
-public interface StatelessSessionBuilder {
+public interface StatelessSessionBuilder extends CommonBuilder {
 	/**
 	 * Opens a session with the specified options.
 	 *
 	 * @return The session
 	 */
 	StatelessSession openStatelessSession();
 
-	/**
-	 * Adds a specific connection to the session options.
-	 *
-	 * @param connection The connection to use.
-	 *
-	 * @return {@code this}, for method chaining
-	 */
+	@Override
 	StatelessSessionBuilder connection(Connection connection);
 
-	/**
-	 * Specifies the connection handling modes for the session.
-	 * <p>
-	 * Note that if {@link ConnectionAcquisitionMode#IMMEDIATELY} is specified,
-	 * then the release mode must be {@link ConnectionReleaseMode#ON_CLOSE}.
-	 *
-	 * @return {@code this}, for method chaining
-	 *
-	 * @since 7.2
-	 */
+	@Override
 	StatelessSessionBuilder connectionHandling(ConnectionAcquisitionMode acquisitionMode, ConnectionReleaseMode releaseMode);
 
-	/**
-	 * Define the tenant identifier to be associated with the opened session.
-	 *
-	 * @param tenantIdentifier The tenant identifier.
-	 *
-	 * @return {@code this}, for method chaining
-	 * @deprecated Use {@link #tenantIdentifier(Object)} instead
-	 */
-	@Deprecated(since = "6.4", forRemoval = true)
-	StatelessSessionBuilder tenantIdentifier(String tenantIdentifier);
-
-	/**
-	 * Define the tenant identifier to be associated with the opened session.
-	 *
-	 * @param tenantIdentifier The tenant identifier.
-	 *
-	 * @return {@code this}, for method chaining
-	 * @since 6.4
-	 */
+	@Override
 	StatelessSessionBuilder tenantIdentifier(Object tenantIdentifier);
 
-	/**
-	 * Specify a read-only mode for the stateless session. If a session
-	 * is created in read-only mode, then {@link Connection#setReadOnly}
-	 * is called when a JDBC connection is obtained.
-	 * <p>
-	 * Furthermore, if read/write replication is in use, then:
-	 * <ul>
-	 * <li>a read-only session will connect to a read-only replica, but
-	 * <li>a non-read-only session will connect to a writable replica.
-	 * </ul>
-	 * <p>
-	 * When read/write replication is in use, it's strongly recommended
-	 * that the session be created with the {@linkplain #initialCacheMode
-	 * initial cache mode} set to {@link CacheMode#GET}, to avoid writing
-	 * stale data read from a read-only replica to the second-level cache.
-	 * Hibernate cannot possibly guarantee that data read from a read-only
-	 * replica is up to date. It's also possible for a read-only session to
-	 * <p>
-	 * When read/write replication is in use, it's possible that an item
-	 * read from the second-level cache might refer to data which does not
-	 * yet exist in the read-only replica. In this situation, an exception
-	 * occurs when the association is fetched. To completely avoid this
-	 * possibility, the {@linkplain #initialCacheMode initial cache mode}
-	 * must be set to {@link CacheMode#IGNORE}. However, it's also usually
-	 * possible to structure data access code in a way which eliminates
-	 * this possibility.
-	 *
-	 * @return {@code this}, for method chaining
-	 * @since 7.2
-	 *
-	 * @see org.hibernate.engine.jdbc.connections.spi.MultiTenantConnectionProvider#getReadOnlyConnection(Object)
-	 * @see org.hibernate.engine.jdbc.connections.spi.MultiTenantConnectionProvider#releaseReadOnlyConnection(Object, Connection)
-	 */
-	@Incubating
+	@Incubating	@Override
 	StatelessSessionBuilder readOnly(boolean readOnly);
 
-	/**
-	 * Specify the initial {@link CacheMode} for the session.
-	 *
-	 * @return {@code this}, for method chaining
-	 * @since 7.2
-	 *
-	 * @see SharedSessionContract#getCacheMode()
-	 */
+	@Incubating	@Override
 	StatelessSessionBuilder initialCacheMode(CacheMode cacheMode);
 
+	@Override
+	StatelessSessionBuilder statementInspector(UnaryOperator<String> operator);
+
 	/**
-	 * Applies the given statement inspection function to the session.
+	 * Define the tenant identifier to be associated with the opened session.
 	 *
-	 * @param operator An operator which accepts a SQL string, returning
-	 *                 a processed SQL string to be used by Hibernate
-	 *                 instead of the given original SQL. Alternatively,
-	 *                 the operator may work by side effect and simply
-	 *                 return the original SQL.
+	 * @param tenantIdentifier The tenant identifier.
 	 *
 	 * @return {@code this}, for method chaining
-	 *
-	 * @apiNote This operation exposes the SPI type
-	 *          {@link StatementInspector}
-	 *          and is therefore a layer-breaker.
+	 * @deprecated Use {@link #tenantIdentifier(Object)} instead
 	 */
-	StatelessSessionBuilder statementInspector(UnaryOperator<String> operator);
+	@Deprecated(since = "6.4", forRemoval = true)
+	StatelessSessionBuilder tenantIdentifier(String tenantIdentifier);
 
 	/**
 	 * Applies the given {@link StatementInspector} to the session.