HHH-19708 allow customization of the initial CacheMode via creation options

motivation for this in Javadoc

Author: gavinking

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

@@ -177,6 +177,22 @@ public interface SessionBuilder {
 	 * <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
@@ -193,6 +209,16 @@ public interface SessionBuilder {
 	@Incubating
 	SessionBuilder readOnly(boolean readOnly);
 
+	/**
+	 * Specify the initial {@link CacheMode} for the session.
+	 *
+	 * @return {@code this}, for method chaining
+	 * @since 7.2
+	 *
+	 * @see SharedSessionContract#getCacheMode()
+	 */
+	SessionBuilder initialCacheMode(CacheMode cacheMode);
+
 	/**
 	 * Add one or more {@link SessionEventListener} instances to the list of
 	 * listeners for the new session to be built.

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

@@ -96,6 +96,12 @@ public interface SharedSessionBuilder extends SessionBuilder {
 	@Override
 	SharedSessionBuilder tenantIdentifier(Object tenantIdentifier);
 
+	@Override
+	SharedSessionBuilder readOnly(boolean readOnly);
+
+	@Override
+	SharedSessionBuilder initialCacheMode(CacheMode cacheMode);
+
 	@Override
 	SharedSessionBuilder eventListeners(SessionEventListener... listeners);
 

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

@@ -64,6 +64,22 @@ public interface StatelessSessionBuilder {
 	 * <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
@@ -74,6 +90,16 @@ public interface StatelessSessionBuilder {
 	@Incubating
 	StatelessSessionBuilder readOnly(boolean readOnly);
 
+	/**
+	 * Specify the initial {@link CacheMode} for the session.
+	 *
+	 * @return {@code this}, for method chaining
+	 * @since 7.2
+	 *
+	 * @see SharedSessionContract#getCacheMode()
+	 */
+	StatelessSessionBuilder initialCacheMode(CacheMode cacheMode);
+
 	/**
 	 * Applies the given statement inspection function to the session.
 	 *

hibernate-core/src/main/java/org/hibernate/internal/AbstractSharedSessionContract.java

@@ -186,27 +186,29 @@ public abstract class AbstractSharedSessionContract implements SharedSessionCont
 
 	public AbstractSharedSessionContract(SessionFactoryImpl factory, SessionCreationOptions options) {
 		this.factory = factory;
-		this.factoryOptions = factory.getSessionFactoryOptions();
-		this.jdbcServices = factory.getJdbcServices();
 
+		factoryOptions = factory.getSessionFactoryOptions();
+		jdbcServices = factory.getJdbcServices();
 		cacheTransactionSynchronization = factory.getCache().getRegionFactory().createTransactionContext( this );
+
 		tenantIdentifier = getTenantId( factoryOptions, options );
 		readOnly = options.isReadOnly();
+		cacheMode = options.getInitialCacheMode();
 		interceptor = interpret( options.getInterceptor() );
 		jdbcTimeZone = options.getJdbcTimeZone();
+
 		sessionEventsManager = createSessionEventsManager( factoryOptions, options );
 		entityNameResolver = new CoordinatingEntityNameResolver( factory, interceptor );
 
-		setCriteriaCopyTreeEnabled( factoryOptions.isCriteriaCopyTreeEnabled() );
-		setCriteriaPlanCacheEnabled( factoryOptions.isCriteriaPlanCacheEnabled() );
-		setNativeJdbcParametersIgnored( factoryOptions.getNativeJdbcParametersIgnored() );
-		setCacheMode( factoryOptions.getInitialSessionCacheMode() );
+		criteriaCopyTreeEnabled = factoryOptions.isCriteriaCopyTreeEnabled();
+		criteriaPlanCacheEnabled = factoryOptions.isCriteriaPlanCacheEnabled();
+		nativeJdbcParametersIgnored = factoryOptions.getNativeJdbcParametersIgnored();
 
-		final StatementInspector statementInspector = interpret( options.getStatementInspector() );
+		final var statementInspector = interpret( options.getStatementInspector() );
 
 		isTransactionCoordinatorShared = isTransactionCoordinatorShared( options );
 		if ( isTransactionCoordinatorShared ) {
-			final SharedSessionCreationOptions sharedOptions = (SharedSessionCreationOptions) options;
+			final var sharedOptions = (SharedSessionCreationOptions) options;
 			if ( options.getConnection() != null ) {
 				throw new SessionException( "Cannot simultaneously share transaction context and specify connection" );
 			}

hibernate-core/src/main/java/org/hibernate/internal/SessionCreationOptions.java

@@ -8,6 +8,7 @@
 import java.util.List;
 import java.util.TimeZone;
 
+import org.hibernate.CacheMode;
 import org.hibernate.FlushMode;
 import org.hibernate.Interceptor;
 import org.hibernate.SessionEventListener;
@@ -48,6 +49,8 @@ public interface SessionCreationOptions {
 
 	boolean isReadOnly();
 
+	CacheMode getInitialCacheMode();
+
 	boolean isIdentifierRollbackEnabled();
 
 	TimeZone getJdbcTimeZone();

hibernate-core/src/main/java/org/hibernate/internal/SessionFactoryImpl.java

@@ -26,6 +26,7 @@
 import javax.naming.StringRefAddr;
 
 import jakarta.persistence.TypedQuery;
+import org.hibernate.CacheMode;
 import org.hibernate.ConnectionAcquisitionMode;
 import org.hibernate.ConnectionReleaseMode;
 import org.hibernate.CustomEntityDirtinessStrategy;
@@ -34,6 +35,7 @@
 import org.hibernate.HibernateException;
 import org.hibernate.Interceptor;
 import org.hibernate.Session;
+import org.hibernate.SessionBuilder;
 import org.hibernate.SessionEventListener;
 import org.hibernate.SessionFactory;
 import org.hibernate.SessionFactoryObserver;
@@ -1130,6 +1132,7 @@ public static class SessionBuilderImpl implements SessionBuilderImplementor, Ses
 		private boolean autoClear;
 		private Object tenantIdentifier;
 		private boolean readOnly;
+		private CacheMode cacheMode;
 		private boolean identifierRollback;
 		private TimeZone jdbcTimeZone;
 		private boolean explicitNoInterceptor;
@@ -1148,20 +1151,21 @@ public SessionBuilderImpl(SessionFactoryImpl sessionFactory) {
 			this.sessionFactory = sessionFactory;
 
 			// set up default builder values...
-			final SessionFactoryOptions sessionFactoryOptions = sessionFactory.getSessionFactoryOptions();
-			statementInspector = sessionFactoryOptions.getStatementInspector();
-			connectionHandlingMode = sessionFactoryOptions.getPhysicalConnectionHandlingMode();
-			autoClose = sessionFactoryOptions.isAutoCloseSessionEnabled();
-			defaultBatchFetchSize = sessionFactoryOptions.getDefaultBatchFetchSize();
-			subselectFetchEnabled = sessionFactoryOptions.isSubselectFetchEnabled();
-			identifierRollback = sessionFactoryOptions.isIdentifierRollbackEnabled();
+			final var options = sessionFactory.getSessionFactoryOptions();
+			statementInspector = options.getStatementInspector();
+			connectionHandlingMode = options.getPhysicalConnectionHandlingMode();
+			autoClose = options.isAutoCloseSessionEnabled();
+			defaultBatchFetchSize = options.getDefaultBatchFetchSize();
+			subselectFetchEnabled = options.isSubselectFetchEnabled();
+			identifierRollback = options.isIdentifierRollbackEnabled();
+			cacheMode = options.getInitialSessionCacheMode();
 
 			final var currentTenantIdentifierResolver =
 					sessionFactory.getCurrentTenantIdentifierResolver();
 			if ( currentTenantIdentifierResolver != null ) {
 				tenantIdentifier = currentTenantIdentifierResolver.resolveCurrentTenantIdentifier();
 			}
-			jdbcTimeZone = sessionFactoryOptions.getJdbcTimeZone();
+			jdbcTimeZone = options.getJdbcTimeZone();
 		}
 
 
@@ -1243,6 +1247,11 @@ public boolean isReadOnly() {
 			return readOnly;
 		}
 
+		@Override
+		public CacheMode getInitialCacheMode() {
+			return cacheMode;
+		}
+
 		@Override
 		public boolean isIdentifierRollbackEnabled() {
 			return identifierRollback;
@@ -1353,6 +1362,12 @@ public SessionBuilderImpl readOnly(boolean readOnly) {
 			return this;
 		}
 
+		@Override
+		public SessionBuilder initialCacheMode(CacheMode cacheMode) {
+			this.cacheMode = cacheMode;
+			return this;
+		}
+
 		@Override
 		public SessionBuilderImpl identifierRollback(boolean identifierRollback) {
 			this.identifierRollback = identifierRollback;
@@ -1396,10 +1411,13 @@ public static class StatelessSessionBuilderImpl implements StatelessSessionBuild
 		private Connection connection;
 		private Object tenantIdentifier;
 		private boolean readOnly;
+		private CacheMode cacheMode;
 
 		public StatelessSessionBuilderImpl(SessionFactoryImpl sessionFactory) {
 			this.sessionFactory = sessionFactory;
-			this.statementInspector = sessionFactory.getSessionFactoryOptions().getStatementInspector();
+			final var options = sessionFactory.getSessionFactoryOptions();
+			statementInspector = options.getStatementInspector();
+			cacheMode = options.getInitialSessionCacheMode();
 
 			final var tenantIdentifierResolver = sessionFactory.getCurrentTenantIdentifierResolver();
 			if ( tenantIdentifierResolver != null ) {
@@ -1436,6 +1454,12 @@ public StatelessSessionBuilder readOnly(boolean readOnly) {
 			return this;
 		}
 
+		@Override
+		public StatelessSessionBuilder initialCacheMode(CacheMode cacheMode) {
+			this.cacheMode = cacheMode;
+			return this;
+		}
+
 		@Override @Deprecated
 		public StatelessSessionBuilder statementInspector(StatementInspector statementInspector) {
 			this.statementInspector = statementInspector;
@@ -1516,6 +1540,11 @@ public boolean isReadOnly() {
 			return readOnly;
 		}
 
+		@Override
+		public CacheMode getInitialCacheMode() {
+			return cacheMode;
+		}
+
 		@Override
 		public Object getTenantIdentifierValue() {
 			return tenantIdentifier;

hibernate-core/src/main/java/org/hibernate/internal/SessionImpl.java

@@ -2112,12 +2112,18 @@ public SharedSessionBuilderImpl tenantIdentifier(Object tenantIdentifier) {
 		}
 
 		@Override
-		public SessionFactoryImpl.SessionBuilderImpl readOnly(boolean readOnly) {
+		public SharedSessionBuilderImpl readOnly(boolean readOnly) {
 			super.readOnly( readOnly );
 			readOnlyChanged = true;
 			return this;
 		}
 
+		@Override
+		public SharedSessionBuilderImpl initialCacheMode(CacheMode cacheMode) {
+			super.initialCacheMode( cacheMode );
+			return this;
+		}
+
 		@Override
 		public SharedSessionBuilderImpl interceptor() {
 			super.interceptor( session.getInterceptor() );