HHH-16651 cleaner separation of "fetch method" vs "fetch timing"

Author: gavinking

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

@@ -7,7 +7,7 @@
 package org.hibernate.annotations;
 
 /**
- * Enumerates strategies for fetching an association from the database.
+ * Enumerates methods for fetching an association from the database.
  * <p>
  * The JPA-defined {@link jakarta.persistence.FetchType} enumerates the
  * possibilities for <em>when</em> an association might be fetched. This
@@ -46,7 +46,7 @@ public enum FetchMode {
 	 * when it is almost certain that the associated data will be
 	 * available in the second-level cache.
 	 */
-	SELECT( org.hibernate.FetchMode.SELECT ),
+	SELECT,
 
 	/**
 	 * Use an outer join to load all instances of the related entity
@@ -62,7 +62,7 @@ public enum FetchMode {
 	 * since the associated data is retrieved as part of the initial
 	 * query.
 	 */
-	JOIN( org.hibernate.FetchMode.JOIN ),
+	JOIN,
 
 	/**
 	 * Use a secondary select with a subselect that re-executes an
@@ -84,15 +84,11 @@ public enum FetchMode {
 	 *     re-execution of the initial query within a SQL subselect.
 	 * </ul>
 	 */
-	SUBSELECT( org.hibernate.FetchMode.SELECT );
-
-	private final org.hibernate.FetchMode hibernateFetchMode;
-
-	FetchMode(org.hibernate.FetchMode hibernateFetchMode) {
-		this.hibernateFetchMode = hibernateFetchMode;
-	}
+	SUBSELECT;
 
 	public org.hibernate.FetchMode getHibernateFetchMode() {
-		return hibernateFetchMode;
+		return this == JOIN
+				? org.hibernate.FetchMode.JOIN
+				: org.hibernate.FetchMode.SELECT;
 	}
 }

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

@@ -6,10 +6,13 @@
  */
 package org.hibernate.annotations;
 
+import jakarta.persistence.FetchType;
+
 import java.lang.annotation.Repeatable;
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
+import static jakarta.persistence.FetchType.EAGER;
 import static java.lang.annotation.ElementType.PACKAGE;
 import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
@@ -91,8 +94,11 @@
 	FetchOverride[] fetchOverrides() default {};
 
 	/**
-	 * Overrides the fetching strategy pf a particular association
-	 * in the named fetch profile being defined.
+	 * Overrides the fetching strategy of a particular association in
+	 * the named fetch profile being defined. If {@link #mode} and
+	 * {@link #fetch} are both unspecified, the strategy defaults to
+	 * {@linkplain FetchType#EAGER eager} {@linkplain FetchMode#JOIN join}
+	 * fetching.
 	 */
 	@Target({ TYPE, PACKAGE })
 	@Retention(RUNTIME)
@@ -110,9 +116,15 @@
 		String association();
 
 		/**
-		 * The {@linkplain FetchMode fetching strategy} to apply to
-		 * the association in the fetch profile being defined.
+		 * The {@linkplain FetchMode method} used for fetching the
+		 * association in the fetch profile being defined.
 		 */
 		FetchMode mode() default JOIN;
+
+		/**
+		 * The {@link FetchType timing} of association fetching in
+		 * the fetch profile being defined.
+		 */
+		FetchType fetch() default EAGER;
 	}
 }

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

@@ -12,6 +12,7 @@
 import java.util.Locale;
 import java.util.Map;
 
+import jakarta.persistence.FetchType;
 import org.hibernate.AnnotationException;
 import org.hibernate.MappingException;
 import org.hibernate.annotations.CollectionTypeRegistration;
@@ -22,6 +23,7 @@
 import org.hibernate.annotations.ConverterRegistrations;
 import org.hibernate.annotations.EmbeddableInstantiatorRegistration;
 import org.hibernate.annotations.EmbeddableInstantiatorRegistrations;
+import org.hibernate.annotations.FetchMode;
 import org.hibernate.annotations.FetchProfile;
 import org.hibernate.annotations.FetchProfile.FetchOverride;
 import org.hibernate.annotations.FetchProfiles;
@@ -852,7 +854,11 @@ private static void bindFetchProfile(FetchProfile fetchProfile, MetadataBuilding
 		final String name = fetchProfile.name();
 		if ( reuseOrCreateFetchProfile( context, name ) ) {
 			for ( FetchOverride fetch : fetchProfile.fetchOverrides() ) {
-				// TODO: validate which modes are valid where
+				if ( fetch.fetch() == FetchType.LAZY && fetch.mode() == FetchMode.JOIN ) {
+					throw new AnnotationException( "Fetch profile '" + name
+							+ "' has a '@FetchOverride' with 'fetch=LAZY' and 'mode=JOIN'"
+							+ " (join fetching is eager by nature)");
+				}
 				context.getMetadataCollector()
 						.addSecondPass( new FetchOverrideSecondPass( name, fetch, context ) );
 			}

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

@@ -13,7 +13,6 @@
 import org.hibernate.mapping.FetchProfile;
 import org.hibernate.mapping.PersistentClass;
 
-import java.util.Locale;
 import java.util.Map;
 
 /**
@@ -43,9 +42,12 @@ public void doSecondPass(Map<String, PersistentClass> persistentClasses) throws
 		final FetchProfile profile = buildingContext.getMetadataCollector().getFetchProfile( fetchProfileName );
 		// we already know that the FetchProfile exists and is good to use
 		profile.addFetch(
-				fetch.entity().getName(),
-				fetch.association(),
-				fetch.mode().toString().toLowerCase(Locale.ROOT)
+				new FetchProfile.Fetch(
+						fetch.entity().getName(),
+						fetch.association(),
+						fetch.mode(),
+						fetch.fetch()
+				)
 		);
 	}
 }

hibernate-core/src/main/java/org/hibernate/engine/FetchTiming.java

@@ -6,6 +6,8 @@
  */
 package org.hibernate.engine;
 
+import jakarta.persistence.FetchType;
+
 /**
  * Enumeration of values describing <em>when</em> fetching should occur.
  * 
@@ -20,5 +22,16 @@ public enum FetchTiming {
 	/**
 	 * Performing fetching later, when needed.  Also called lazy fetching.
 	 */
-	DELAYED
+	DELAYED;
+
+	public static FetchTiming forType(FetchType type) {
+		switch ( type ) {
+			case EAGER:
+				return IMMEDIATE;
+			case LAZY:
+				return DELAYED;
+			default:
+				throw new IllegalArgumentException( "Unknown FetchType" );
+		}
+	}
 }

hibernate-core/src/main/java/org/hibernate/engine/profile/Fetch.java

@@ -6,26 +6,50 @@
  */
 package org.hibernate.engine.profile;
 
+import org.hibernate.AssertionFailure;
+import org.hibernate.annotations.FetchMode;
+import org.hibernate.engine.FetchStyle;
+import org.hibernate.engine.FetchTiming;
+
 import java.util.Locale;
 
+import static org.hibernate.engine.FetchTiming.IMMEDIATE;
+
 /**
  * Models an individual fetch override within a {@link FetchProfile}.
  *
  * @author Steve Ebersole
  */
 public class Fetch {
 	private final Association association;
-	private final Style style;
+	private final FetchStyle method;
+	private final FetchTiming timing;
 
 	/**
 	 * Constructs a {@link Fetch}.
 	 *
 	 * @param association The association to be fetched
 	 * @param style How to fetch it
+	 *
+	 * @deprecated use {@link #Fetch(Association,FetchStyle,FetchTiming)}
 	 */
+	@Deprecated(forRemoval = true)
 	public Fetch(Association association, Style style) {
 		this.association = association;
-		this.style = style;
+		this.method = style.toFetchStyle();
+		this.timing = IMMEDIATE;
+	}
+
+	/**
+	 * Constructs a {@link Fetch}.
+	 *
+	 * @param association The association to be fetched
+	 * @param method How to fetch it
+	 */
+	public Fetch(Association association, FetchStyle method, FetchTiming timing) {
+		this.association = association;
+		this.method = method;
+		this.timing = timing;
 	}
 
 	/**
@@ -37,14 +61,34 @@ public Association getAssociation() {
 
 	/**
 	 * The fetch style applied to the association.
+	 *
+	 * @deprecated use {@link #getMethod()}
 	 */
+	@Deprecated(forRemoval = true)
 	public Style getStyle() {
-		return style;
+		return Style.fromFetchStyle( method );
+	}
+
+	/**
+	 * The fetch method to be applied to the association.
+	 */
+	public FetchStyle getMethod() {
+		return method;
+	}
+
+	/**
+	 * The fetch timing to be applied to the association.
+	 */
+	public FetchTiming getTiming() {
+		return timing;
 	}
 
 	/**
 	 * The type or style of fetch.
+	 *
+	 * @deprecated Use {@link FetchStyle}
 	 */
+	@Deprecated(forRemoval = true)
 	public enum Style {
 		/**
 		 * Fetch via a join
@@ -59,6 +103,32 @@ public enum Style {
 		 */
 		SUBSELECT;
 
+		public FetchStyle toFetchStyle() {
+			switch (this) {
+				case SELECT:
+					return FetchStyle.SELECT;
+				case SUBSELECT:
+					return FetchStyle.SUBSELECT;
+				case JOIN:
+					return FetchStyle.JOIN;
+				default:
+					throw new AssertionFailure("Unknown Fetch.Style");
+			}
+		}
+
+		static Style fromFetchStyle(FetchStyle fetchStyle) {
+			switch (fetchStyle) {
+				case SELECT:
+					return SELECT;
+				case SUBSELECT:
+					return SUBSELECT;
+				case JOIN:
+					return JOIN;
+				default:
+					throw new IllegalArgumentException("Unhandled FetchStyle");
+			}
+		}
+
 		@Override
 		public String toString() {
 			return name().toLowerCase(Locale.ROOT);
@@ -79,10 +149,23 @@ public static Style parse(String name) {
 			}
 			return JOIN;
 		}
+
+		public static Style forMethod(FetchMode fetchMode) {
+			switch ( fetchMode ) {
+				case JOIN:
+					return JOIN;
+				case SELECT:
+					return SELECT;
+				case SUBSELECT:
+					return SUBSELECT;
+				default:
+					throw new IllegalArgumentException( "Unknown FetchMode" );
+			}
+		}
 	}
 
 	@Override
 	public String toString() {
-		return "Fetch[" + style + "{" + association.getRole() + "}]";
+		return "Fetch[" + method + "{" + association.getRole() + "}]";
 	}
 }

hibernate-core/src/main/java/org/hibernate/engine/profile/FetchProfile.java

@@ -15,6 +15,8 @@
 import org.hibernate.type.BagType;
 import org.hibernate.type.Type;
 
+import static org.hibernate.engine.FetchStyle.JOIN;
+
 /**
  * The runtime representation of a Hibernate
  * {@linkplain org.hibernate.annotations.FetchProfile fetch profile}
@@ -97,7 +99,7 @@ public void addFetch(final Fetch fetch) {
 
 			// couple of things for which to account in the case of collection
 			// join fetches
-			if ( Fetch.Style.JOIN == fetch.getStyle() ) {
+			if ( fetch.getMethod() == JOIN ) {
 				// first, if this is a bag we need to ignore it if we previously
 				// processed collection join fetches
 				if ( associationType instanceof BagType ) {

hibernate-core/src/main/java/org/hibernate/engine/profile/internal/FetchProfileAffectee.java

@@ -6,8 +6,6 @@
  */
 package org.hibernate.engine.profile.internal;
 
-import org.hibernate.engine.profile.Fetch;
-
 /**
  * Commonality between entities and collections as something that can be affected by fetch profiles.
  *
@@ -17,5 +15,5 @@ public interface FetchProfileAffectee {
 	/**
 	 * Register the profile name with the entity/collection
 	 */
-	void registerAffectingFetchProfile(String fetchProfileName, Fetch.Style fetchStyle);
+	void registerAffectingFetchProfile(String fetchProfileName);
 }

hibernate-core/src/main/java/org/hibernate/engine/spi/LoadQueryInfluencers.java

@@ -26,7 +26,7 @@
 import org.hibernate.persister.entity.EntityPersister;
 
 import static java.util.Collections.emptySet;
-import static org.hibernate.engine.profile.Fetch.Style.SUBSELECT;
+import static org.hibernate.engine.FetchStyle.SUBSELECT;
 
 /**
  * Centralize all options which can influence the SQL query needed to load an
@@ -318,7 +318,7 @@ private boolean isSubselectFetchEnabledInProfile(CollectionPersister persister)
 				final FetchProfile fetchProfile = sessionFactory.getFetchProfile( profile );
 				if ( fetchProfile != null ) {
 					final Fetch fetch = fetchProfile.getFetchByRole( persister.getRole() );
-					if ( fetch != null && fetch.getStyle() == SUBSELECT ) {
+					if ( fetch != null && fetch.getMethod() == SUBSELECT) {
 						return true;
 					}
 				}
@@ -347,7 +347,7 @@ private boolean hasSubselectLoadableCollectionsEnabledInProfile(EntityPersister
 				final FetchProfile fetchProfile = sessionFactory.getFetchProfile( profile );
 				for ( Fetch fetch : fetchProfile.getFetches().values() ) {
 					// TODO: check that it's relevant to this persister??
-					if ( fetch.getStyle() == SUBSELECT ) {
+					if ( fetch.getMethod() == SUBSELECT ) {
 						return true;
 					}
 				}