HHH-15086 Introduce configurable query cache layout

Author: beikov

hibernate-core/src/main/java/org/hibernate/annotations/CacheLayout.java

@@ -0,0 +1,46 @@
+/*
+ * Hibernate, Relational Persistence for Idiomatic Java
+ *
+ * License: GNU Lesser General Public License (LGPL), version 2.1 or later.
+ * See the lgpl.txt file in the root directory or <http://www.gnu.org/licenses/lgpl-2.1.html>.
+ */
+package org.hibernate.annotations;
+
+import org.hibernate.Incubating;
+
+/**
+ * Describes the data layout used for storing an object into the query cache.
+ * <p>
+ * The query cache can either store the full state of an entity or collection,
+ * or store only the identifier and discriminator if needed. Both approaches have pros and cons,
+ * but ultimately it's advisable to us a shallow layout if the chances are high,
+ * that the object will be contained in the second level cache.
+ *
+ * @see QueryCacheLayout
+ * @since 6.5
+ */
+@Incubating
+public enum CacheLayout {
+	/**
+	 * Uses either {@link #SHALLOW} or {@link #FULL},
+	 * depending on whether an entity or collection is second level cacheable.
+	 */
+	AUTO,
+
+	/**
+	 * Uses a cache layout that only stores the identifier of the entity or collection.
+	 * This is useful when the chances for the object being part of the second level cache are very high.
+	 */
+	SHALLOW,
+
+	/**
+	 * Like {@link #SHALLOW} but will also store the entity discriminator.
+	 */
+	SHALLOW_WITH_DISCRIMINATOR,
+
+	/**
+	 * Stores the full state into the query cache.
+	 * This is useful when the chances for the object being part of the second level cache are very low.
+	 */
+	FULL;
+}

hibernate-core/src/main/java/org/hibernate/annotations/QueryCacheLayout.java

@@ -0,0 +1,40 @@
+/*
+ * Hibernate, Relational Persistence for Idiomatic Java
+ *
+ * License: GNU Lesser General Public License (LGPL), version 2.1 or later.
+ * See the lgpl.txt file in the root directory or <http://www.gnu.org/licenses/lgpl-2.1.html>.
+ */
+package org.hibernate.annotations;
+
+import java.lang.annotation.Retention;
+import java.lang.annotation.Target;
+
+import org.hibernate.Incubating;
+
+import static java.lang.annotation.ElementType.FIELD;
+import static java.lang.annotation.ElementType.METHOD;
+import static java.lang.annotation.ElementType.TYPE;
+import static java.lang.annotation.RetentionPolicy.RUNTIME;
+
+/**
+ * Configures the layout for the entity or collection data in a query cache.
+ *
+ * @see CacheLayout
+ * @see jakarta.persistence.Cacheable
+ * @see org.hibernate.Cache
+ * @see org.hibernate.cfg.AvailableSettings#CACHE_REGION_FACTORY
+ * @see org.hibernate.cfg.AvailableSettings#USE_SECOND_LEVEL_CACHE
+ * @see org.hibernate.cfg.AvailableSettings#USE_QUERY_CACHE
+ * @since 6.5
+ *
+ */
+@Target({TYPE, FIELD, METHOD})
+@Retention(RUNTIME)
+@Incubating
+public @interface QueryCacheLayout {
+
+	/**
+	 * The layout of the data for an entity or collection in the query cache.
+	 */
+	CacheLayout layout() default CacheLayout.AUTO;
+}

hibernate-core/src/main/java/org/hibernate/boot/SessionFactoryBuilder.java

@@ -14,6 +14,7 @@
 import org.hibernate.Interceptor;
 import org.hibernate.SessionFactory;
 import org.hibernate.SessionFactoryObserver;
+import org.hibernate.annotations.CacheLayout;
 import org.hibernate.cache.spi.TimestampsCacheFactory;
 import org.hibernate.context.spi.CurrentTenantIdentifierResolver;
 import org.hibernate.jpa.spi.JpaCompliance;
@@ -445,6 +446,19 @@ public interface SessionFactoryBuilder {
 	 */
 	SessionFactoryBuilder applyQueryCacheSupport(boolean enabled);
 
+	/**
+	 * Specifies the default {@link CacheLayout} to use for query cache entries.
+	 *
+	 * @param cacheLayout The cache layout to use.
+	 *
+	 * @return {@code this}, for method chaining
+	 *
+	 * @see org.hibernate.cfg.AvailableSettings#QUERY_CACHE_LAYOUT
+	 * @since 6.5
+	 */
+	@Incubating
+	SessionFactoryBuilder applyQueryCacheLayout(CacheLayout cacheLayout);
+
 	/**
 	 * Specifies a {@link org.hibernate.cache.spi.TimestampsCacheFactory}.
 	 *

hibernate-core/src/main/java/org/hibernate/boot/internal/SessionFactoryBuilderImpl.java

@@ -14,6 +14,7 @@
 import org.hibernate.Interceptor;
 import org.hibernate.SessionFactory;
 import org.hibernate.SessionFactoryObserver;
+import org.hibernate.annotations.CacheLayout;
 import org.hibernate.boot.SessionFactoryBuilder;
 import org.hibernate.boot.TempTableDdlTransactionHandling;
 import org.hibernate.boot.spi.BootstrapContext;
@@ -285,6 +286,12 @@ public SessionFactoryBuilder applyQueryCacheSupport(boolean enabled) {
 		return this;
 	}
 
+	@Override
+	public SessionFactoryBuilder applyQueryCacheLayout(CacheLayout cacheLayout) {
+		this.optionsBuilder.applyQueryCacheLayout( cacheLayout );
+		return this;
+	}
+
 	@Override
 	public SessionFactoryBuilder applyTimestampsCacheFactory(TimestampsCacheFactory factory) {
 		this.optionsBuilder.applyTimestampsCacheFactory( factory );

hibernate-core/src/main/java/org/hibernate/boot/internal/SessionFactoryOptionsBuilder.java

@@ -12,6 +12,7 @@
 import java.util.Collections;
 import java.util.HashMap;
 import java.util.List;
+import java.util.Locale;
 import java.util.Map;
 import java.util.TimeZone;
 import java.util.concurrent.Callable;
@@ -24,6 +25,7 @@
 import org.hibernate.SessionEventListener;
 import org.hibernate.SessionFactoryObserver;
 import org.hibernate.TimeZoneStorageStrategy;
+import org.hibernate.annotations.CacheLayout;
 import org.hibernate.boot.SchemaAutoTooling;
 import org.hibernate.boot.TempTableDdlTransactionHandling;
 import org.hibernate.boot.registry.StandardServiceRegistry;
@@ -126,6 +128,7 @@
 import static org.hibernate.cfg.AvailableSettings.USE_SQL_COMMENTS;
 import static org.hibernate.cfg.AvailableSettings.USE_STRUCTURED_CACHE;
 import static org.hibernate.cfg.AvailableSettings.USE_SUBSELECT_FETCH;
+import static org.hibernate.cfg.CacheSettings.QUERY_CACHE_LAYOUT;
 import static org.hibernate.engine.config.spi.StandardConverters.BOOLEAN;
 import static org.hibernate.internal.CoreLogging.messageLogger;
 import static org.hibernate.internal.log.DeprecationLogger.DEPRECATION_LOGGER;
@@ -228,6 +231,7 @@ public class SessionFactoryOptionsBuilder implements SessionFactoryOptions {
 	// Caching
 	private boolean secondLevelCacheEnabled;
 	private boolean queryCacheEnabled;
+	private CacheLayout queryCacheLayout;
 	private TimestampsCacheFactory timestampsCacheFactory;
 	private String cacheRegionPrefix;
 	private boolean minimalPutsEnabled;
@@ -442,6 +446,11 @@ public SessionFactoryOptionsBuilder(StandardServiceRegistry serviceRegistry, Boo
 		if ( !(regionFactory instanceof NoCachingRegionFactory) ) {
 			this.secondLevelCacheEnabled = configurationService.getSetting( USE_SECOND_LEVEL_CACHE, BOOLEAN, true );
 			this.queryCacheEnabled = configurationService.getSetting( USE_QUERY_CACHE, BOOLEAN, false );
+			this.queryCacheLayout = configurationService.getSetting(
+					QUERY_CACHE_LAYOUT,
+					value -> CacheLayout.valueOf( value.toString().toUpperCase( Locale.ROOT ) ),
+					CacheLayout.FULL
+			);
 			this.timestampsCacheFactory = strategySelector.resolveDefaultableStrategy(
 					TimestampsCacheFactory.class,
 					configurationSettings.get( QUERY_CACHE_FACTORY ),
@@ -467,6 +476,7 @@ public SessionFactoryOptionsBuilder(StandardServiceRegistry serviceRegistry, Boo
 		else {
 			this.secondLevelCacheEnabled = false;
 			this.queryCacheEnabled = false;
+			this.queryCacheLayout = CacheLayout.AUTO;
 			this.timestampsCacheFactory = null;
 			this.cacheRegionPrefix = null;
 			this.minimalPutsEnabled = false;
@@ -1048,6 +1058,11 @@ public boolean isQueryCacheEnabled() {
 		return queryCacheEnabled;
 	}
 
+	@Override
+	public CacheLayout getQueryCacheLayout() {
+		return queryCacheLayout;
+	}
+
 	@Override
 	public TimestampsCacheFactory getTimestampsCacheFactory() {
 		return timestampsCacheFactory;
@@ -1428,6 +1443,10 @@ public void enableQueryCacheSupport(boolean enabled) {
 		this.queryCacheEnabled = enabled;
 	}
 
+	public void applyQueryCacheLayout(CacheLayout queryCacheLayout) {
+		this.queryCacheLayout = queryCacheLayout;
+	}
+
 	public void applyTimestampsCacheFactory(TimestampsCacheFactory factory) {
 		this.timestampsCacheFactory = factory;
 	}

hibernate-core/src/main/java/org/hibernate/boot/model/internal/CollectionBinder.java

@@ -22,6 +22,7 @@
 import org.hibernate.annotations.Bag;
 import org.hibernate.annotations.BatchSize;
 import org.hibernate.annotations.Cache;
+import org.hibernate.annotations.CacheLayout;
 import org.hibernate.annotations.Cascade;
 import org.hibernate.annotations.Check;
 import org.hibernate.annotations.Checks;
@@ -63,6 +64,7 @@
 import org.hibernate.annotations.OptimisticLock;
 import org.hibernate.annotations.Parameter;
 import org.hibernate.annotations.Persister;
+import org.hibernate.annotations.QueryCacheLayout;
 import org.hibernate.annotations.SQLDelete;
 import org.hibernate.annotations.SQLDeleteAll;
 import org.hibernate.annotations.SQLInsert;
@@ -214,6 +216,7 @@ public abstract class CollectionBinder {
 	private String cascadeStrategy;
 	private String cacheConcurrencyStrategy;
 	private String cacheRegionName;
+	private CacheLayout queryCacheLayout;
 	private boolean oneToMany;
 	protected IndexColumn indexColumn;
 	protected OnDeleteAction onDeleteAction;
@@ -288,6 +291,7 @@ public static void bindCollection(
 		collectionBinder.setNaturalSort( property.getAnnotation( SortNatural.class ) );
 		collectionBinder.setComparatorSort( property.getAnnotation( SortComparator.class ) );
 		collectionBinder.setCache( property.getAnnotation( Cache.class ) );
+		collectionBinder.setQueryCacheLayout( property.getAnnotation( QueryCacheLayout.class ) );
 		collectionBinder.setPropertyHolder(propertyHolder);
 
 		collectionBinder.setNotFoundAction( notFoundAction( propertyHolder, inferredData, property, manyToManyAnn ) );
@@ -1251,6 +1255,7 @@ private void bindCache() {
 			collection.setCacheConcurrencyStrategy( cacheConcurrencyStrategy );
 			collection.setCacheRegionName( cacheRegionName );
 		}
+		collection.setQueryCacheLayout( queryCacheLayout );
 	}
 
 	private void bindExplicitTypes() {
@@ -1938,6 +1943,10 @@ public void setCache(Cache cache) {
 		}
 	}
 
+	public void setQueryCacheLayout(QueryCacheLayout queryCacheLayout) {
+		this.queryCacheLayout = queryCacheLayout == null ? null : queryCacheLayout.layout();
+	}
+
 	public void setOneToMany(boolean oneToMany) {
 		this.oneToMany = oneToMany;
 	}

hibernate-core/src/main/java/org/hibernate/boot/model/internal/EntityBinder.java

@@ -23,6 +23,7 @@
 import org.hibernate.annotations.BatchSize;
 import org.hibernate.annotations.Cache;
 import org.hibernate.annotations.CacheConcurrencyStrategy;
+import org.hibernate.annotations.CacheLayout;
 import org.hibernate.annotations.Check;
 import org.hibernate.annotations.Checks;
 import org.hibernate.annotations.DiscriminatorFormula;
@@ -43,6 +44,7 @@
 import org.hibernate.annotations.Polymorphism;
 import org.hibernate.annotations.PolymorphismType;
 import org.hibernate.annotations.Proxy;
+import org.hibernate.annotations.QueryCacheLayout;
 import org.hibernate.annotations.RowId;
 import org.hibernate.annotations.SQLDelete;
 import org.hibernate.annotations.SQLDeleteAll;
@@ -201,6 +203,7 @@ public class EntityBinder {
 	private String cacheRegion;
 	private boolean cacheLazyProperty;
 	private String naturalIdCacheRegion;
+	private CacheLayout queryCacheLayout;
 
 	/**
 	 * Bind an entity class. This can be done in a single pass.
@@ -1271,6 +1274,7 @@ public void bindEntity() {
 		persistentClass.setEntityName( annotatedClass.getName() );
 		persistentClass.setCached( isCached );
 		persistentClass.setLazy( lazy );
+		persistentClass.setQueryCacheLayout( queryCacheLayout );
 		if ( proxyClass != null ) {
 			persistentClass.setProxyInterfaceName( proxyClass.getName() );
 		}
@@ -1599,6 +1603,7 @@ private void bindCache() {
 		cacheConcurrentStrategy = null;
 		cacheRegion = null;
 		cacheLazyProperty = true;
+		queryCacheLayout = null;
 		final SharedCacheMode sharedCacheMode  = context.getBuildingOptions().getSharedCacheMode();
 		if ( persistentClass instanceof RootClass ) {
 			bindRootClassCache( sharedCacheMode, context );
@@ -1643,6 +1648,9 @@ private void bindRootClassCache(SharedCacheMode sharedCacheMode, MetadataBuildin
 		cacheConcurrentStrategy = resolveCacheConcurrencyStrategy( effectiveCache.usage() );
 		cacheRegion = effectiveCache.region();
 		cacheLazyProperty = isCacheLazy( effectiveCache, annotatedClass );
+
+		final QueryCacheLayout queryCache = annotatedClass.getAnnotation( QueryCacheLayout.class );
+		queryCacheLayout = queryCache == null ? null : queryCache.layout();
 	}
 
 	private static boolean isCacheLazy(Cache effectiveCache, XClass annotatedClass) {

hibernate-core/src/main/java/org/hibernate/boot/spi/AbstractDelegatingSessionFactoryBuilder.java

@@ -13,6 +13,7 @@
 import org.hibernate.Interceptor;
 import org.hibernate.SessionFactory;
 import org.hibernate.SessionFactoryObserver;
+import org.hibernate.annotations.CacheLayout;
 import org.hibernate.boot.SessionFactoryBuilder;
 import org.hibernate.boot.TempTableDdlTransactionHandling;
 import org.hibernate.cache.spi.TimestampsCacheFactory;
@@ -245,6 +246,12 @@ public T applyQueryCacheSupport(boolean enabled) {
 		return getThis();
 	}
 
+	@Override
+	public SessionFactoryBuilder applyQueryCacheLayout(CacheLayout cacheLayout) {
+		delegate.applyQueryCacheLayout( cacheLayout );
+		return getThis();
+	}
+
 	@Override
 	public SessionFactoryBuilder applyTimestampsCacheFactory(TimestampsCacheFactory factory) {
 		delegate.applyTimestampsCacheFactory( factory );

hibernate-core/src/main/java/org/hibernate/boot/spi/AbstractDelegatingSessionFactoryOptions.java

@@ -15,6 +15,7 @@
 import org.hibernate.Interceptor;
 import org.hibernate.SessionFactoryObserver;
 import org.hibernate.TimeZoneStorageStrategy;
+import org.hibernate.annotations.CacheLayout;
 import org.hibernate.boot.SchemaAutoTooling;
 import org.hibernate.boot.TempTableDdlTransactionHandling;
 import org.hibernate.boot.registry.StandardServiceRegistry;
@@ -253,6 +254,11 @@ public boolean isQueryCacheEnabled() {
 		return delegate.isQueryCacheEnabled();
 	}
 
+	@Override
+	public CacheLayout getQueryCacheLayout() {
+		return delegate.getQueryCacheLayout();
+	}
+
 	@Override
 	public TimestampsCacheFactory getTimestampsCacheFactory() {
 		return delegate.getTimestampsCacheFactory();

hibernate-core/src/main/java/org/hibernate/boot/spi/SessionFactoryOptions.java

@@ -15,6 +15,7 @@
 import org.hibernate.Interceptor;
 import org.hibernate.SessionFactoryObserver;
 import org.hibernate.TimeZoneStorageStrategy;
+import org.hibernate.annotations.CacheLayout;
 import org.hibernate.boot.SchemaAutoTooling;
 import org.hibernate.boot.TempTableDdlTransactionHandling;
 import org.hibernate.boot.registry.StandardServiceRegistry;
@@ -166,6 +167,9 @@ default boolean isAllowRefreshDetachedEntity() {
 
 	boolean isQueryCacheEnabled();
 
+	@Incubating
+	CacheLayout getQueryCacheLayout();
+
 	TimestampsCacheFactory getTimestampsCacheFactory();
 
 	String getCacheRegionPrefix();