HHH-15691 add @Cache(includeLazy) and deprecate stringly-typed include member

+ add some javadoc

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

@@ -62,6 +62,8 @@ package org.hibernate;
  * current transaction and/or locking scheme.
  *
  * @author Steve Ebersole
+ *
+ * @see org.hibernate.annotations.Cache
  */
 public interface Cache extends jakarta.persistence.Cache {
 	/**

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

@@ -5,6 +5,7 @@
  * 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;
 
@@ -33,6 +34,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  * cache inherit the cache belonging to the root entity.
  *
  * @see jakarta.persistence.Cacheable
+ * @see org.hibernate.Cache
  *
  * @author Emmanuel Bernard
  */
@@ -51,12 +53,34 @@ public @interface Cache {
 	String region() default "";
 
 	/**
-	 * Specifies which properties are included in the second-level
-	 * cache, either:
+	 * When bytecode enhancement is used, and {@linkplain LazyGroup
+	 * field-level lazy fetching} is enabled, specifies whether lazy
+	 * attributes of the entity are eligible for inclusion in the
+	 * second-level cache, in the case where they happen to be loaded.
+	 * <p>
+	 * By default, a loaded lazy field <em>will</em> be cached when
+	 * second-level caching is enabled. If this is not desirable&mdash;if,
+	 * for example, the field value is extremely large and only rarely
+	 * accessed&mdash;then setting {@code @Cache(includeLazy=false)} will
+	 * prevent it and other lazy fields of the annotated entity from being
+	 * cached, and the lazy fields will always be retrieved directly from
+	 * the database.
+	 *
+	 * @see LazyGroup
+	 */
+	boolean includeLazy() default true;
+
+	/**
+	 * When bytecode enhancement is used, and {@linkplain LazyGroup
+	 * field-level lazy fetching} is enabled, specifies which attributes
+	 * of the entity are included in the second-level cache, either:
 	 * <ul>
 	 * <li>{@code "all"} properties, the default, or
 	 * <li>only {@code "non-lazy"} properties.
 	 * </ul>
+	 *
+	 * @deprecated Use {@link #includeLazy()} for the sake of typesafety.
 	 */
+	@Deprecated
 	String include() default "all";
 }

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

@@ -41,6 +41,8 @@ import java.lang.annotation.RetentionPolicy;
  * projects using Hibernate don't even bother enabling the bytecode enhancer.
  *
  * @author Steve Ebersole
+ *
+ * @see Cache#includeLazy()
  */
 @java.lang.annotation.Target({ElementType.METHOD, ElementType.FIELD})
 @Retention(RetentionPolicy.RUNTIME)

hibernate-core/src/main/java/org/hibernate/cfg/annotations/EntityBinder.java

@@ -1436,6 +1436,9 @@ public class EntityBinder {
 	}
 
 	private static boolean isCacheLazy(Cache effectiveCache, XClass annotatedClass) {
+		if ( !effectiveCache.includeLazy() ) {
+			return false;
+		}
 		switch ( effectiveCache.include().toLowerCase( Locale.ROOT ) ) {
 			case "all":
 				return true;
@@ -1490,6 +1493,11 @@ public class EntityBinder {
 			return region;
 		}
 
+		@Override
+		public boolean includeLazy() {
+			return true;
+		}
+
 		public String include() {
 			return "all";
 		}

hibernate-core/src/test/java/org/hibernate/orm/test/type/LobUnfetchedPropertyTest.java

@@ -131,7 +131,7 @@ public class LobUnfetchedPropertyTest extends BaseCoreFunctionalTestCase {
 	}
 
 	@Entity(name = "FileBlob")
-	@Cache(usage = CacheConcurrencyStrategy.NONSTRICT_READ_WRITE, include = "non-lazy")
+	@Cache(usage = CacheConcurrencyStrategy.NONSTRICT_READ_WRITE, includeLazy = false)
 	public static class FileBlob {
 
 		private int id;
@@ -161,7 +161,7 @@ public class LobUnfetchedPropertyTest extends BaseCoreFunctionalTestCase {
 	}
 
 	@Entity(name = "FileClob")
-	@Cache(usage = CacheConcurrencyStrategy.NONSTRICT_READ_WRITE, include = "non-lazy")
+	@Cache(usage = CacheConcurrencyStrategy.NONSTRICT_READ_WRITE, includeLazy = false)
 	public static class FileClob {
 
 		private int id;
@@ -191,7 +191,7 @@ public class LobUnfetchedPropertyTest extends BaseCoreFunctionalTestCase {
 	}
 
 	@Entity(name = "FileNClob")
-	@Cache(usage = CacheConcurrencyStrategy.NONSTRICT_READ_WRITE, include = "non-lazy")
+	@Cache(usage = CacheConcurrencyStrategy.NONSTRICT_READ_WRITE, includeLazy = false)
 	public static class FileNClob {
 
 		private int id;