Javadoc surrounding fetch profiles

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

@@ -1148,41 +1148,44 @@ public interface Session extends SharedSessionContract, EntityManager {
 	void setReadOnly(Object entityOrProxy, boolean readOnly);
 
 	/**
-	 * Is a particular fetch profile enabled on this session?
+	 * Is the {@link org.hibernate.annotations.FetchProfile fetch profile}
+	 * with the given name enabled in this session?
 	 *
-	 * @param name the name of the profile to be checked.
+	 * @param name the name of the profile
 	 * @return True if fetch profile is enabled; false if not.
 	 *
 	 * @throws UnknownProfileException Indicates that the given name does not
-	 * match any known profile names
+	 *                                 match any known fetch profile names
 	 *
-	 * @see org.hibernate.engine.profile.FetchProfile for discussion of this feature
+	 * @see org.hibernate.annotations.FetchProfile
 	 */
 	boolean isFetchProfileEnabled(String name) throws UnknownProfileException;
 
 	/**
-	 * Enable a particular fetch profile on this session. If the requested
-	 * profile is already enabled, the call has no effect.
+	 * Enable the {@link org.hibernate.annotations.FetchProfile fetch profile}
+	 * with the given name in this session. If the requested fetch profile is
+	 * already enabled, the call has no effect.
 	 *
 	 * @param name the name of the fetch profile to be enabled
 	 *
 	 * @throws UnknownProfileException Indicates that the given name does not
-	 * match any known profile names
+	 *                                 match any known fetch profile names
 	 *
-	 * @see org.hibernate.engine.profile.FetchProfile for discussion of this feature
+	 * @see org.hibernate.annotations.FetchProfile
 	 */
 	void enableFetchProfile(String name) throws UnknownProfileException;
 
 	/**
-	 * Disable a particular fetch profile on this session. If the requested
-	 * profile is already enabled, the call has no effect.
+	 * Disable the {@link org.hibernate.annotations.FetchProfile fetch profile}
+	 * with the given name in this session. If the requested fetch profile is
+	 * not currently enabled, the call has no effect.
 	 *
 	 * @param name the name of the fetch profile to be disabled
 	 *
 	 * @throws UnknownProfileException Indicates that the given name does not
-	 * match any known profile names
+	 *                                 match any known fetch profile names
 	 *
-	 * @see org.hibernate.engine.profile.FetchProfile for discussion of this feature
+	 * @see org.hibernate.annotations.FetchProfile
 	 */
 	void disableFetchProfile(String name) throws UnknownProfileException;
 

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

@@ -12,11 +12,15 @@
 import java.lang.annotation.Target;
 
 /**
- * Specify the fetching strategy used for the annotated association.
+ * Specifies the default fetching strategy for the annotated association.
+ * <p>
+ * The default fetching strategy for the association may be overridden
+ * in a given {@linkplain FetchProfile fetch profile}.
  *
  * @author Emmanuel Bernard
  *
  * @see FetchMode
+ * @see FetchProfile
  */
 @Target({ElementType.METHOD, ElementType.FIELD})
 @Retention(RetentionPolicy.RUNTIME)

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

@@ -15,11 +15,54 @@
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Define the fetching strategy profile.
+ * Defines a fetch profile, by specifying its {@link #name}, together
+ * with a list of {@linkplain #fetchOverrides fetch strategy overrides}.
+ * <p>
+ * A named fetch profile must be explicitly enabled in a given session
+ * by calling {@link org.hibernate.Session#enableFetchProfile(String)}
+ * for it to have any effect at runtime.
+ * <p>
+ * Fetch profiles compete with JPA-defined
+ * {@linkplain jakarta.persistence.NamedEntityGraph named entity graphs},
+ * and so programs which wish to maintain compatibility with alternative
+ * implementations of JPA should prefer {@code @NamedEntityGraph}. The
+ * semantics of these two facilities are not quite identical, however,
+ * since a fetch profile is a list, not a graph.
+ * <p>
+ * Or, if we insist on thinking in terms of graphs:
+ * <ul>
+ * <li>for a fetch profile, the graph is implicit, determined by
+ *     recursively following fetched associations from the root entity,
+ *     and each {@link FetchOverride} in the fetch profile applies the
+ *     same fetching strategy to the overridden association wherever it
+ *     is reached recursively within the graph, whereas
+ * <li>an entity graph is explicit, and simply specifies that each path
+ *     from the root of the graph should be fetched.
+ * </ul>
+ * However, a fetch profile is not by nature rooted at any one particular
+ * entity, and so {@code @FetchProfile} is not required to annotate the
+ * entity classes it affects. It may even occur as a package-level
+ * annotation.
+ * <p>
+ * Instead, the root entity of a fetch graph is determined by the context
+ * in which the fetch profile is active. For example, if a fetch profile
+ * is active when {@link org.hibernate.Session#get(Class, Object)} is
+ * called, then the root entity is the entity with the given {@link Class}.
+ * Given a root entity as input, an active fetch profile contributes to
+ * the determination of the fetch graph.
+ * <p>
+ * A JPA {@link jakarta.persistence.EntityGraph} may be constructed in
+ * Java code at runtime. But this amounts to separate, albeit extremely
+ * limited, query facility that competes with JPA's own {@linkplain
+ * jakarta.persistence.criteria.CriteriaBuilder criteria queries}.
+ * There's no such capability for fetch profiles.
+ *
+ * @see org.hibernate.Session#enableFetchProfile(String)
+ * @see org.hibernate.SessionFactory#containsFetchProfileDefinition(String)
  *
  * @author Hardy Ferentschik
  */
-@Target({ TYPE, PACKAGE })
+@Target({TYPE, PACKAGE})
 @Retention(RUNTIME)
 @Repeatable(FetchProfiles.class)
 public @interface FetchProfile {
@@ -29,28 +72,32 @@
 	String name();
 
 	/**
-	 * The association fetch overrides.
+	 * The list of association fetching strategy overrides.
 	 */
 	FetchOverride[] fetchOverrides();
 
 	/**
-	 * Descriptor for a particular association override.
+	 * Overrides the fetching strategy pf a particular association
+	 * in the named fetch profile being defined.
 	 */
 	@Target({ TYPE, PACKAGE })
 	@Retention(RUNTIME)
 	@interface FetchOverride {
 		/**
-		 * The entity containing the association whose fetch is being overridden.
+		 * The entity containing the association whose default fetch
+		 * strategy is being overridden.
 		 */
 		Class<?> entity();
 
 		/**
-		 * The association whose fetch is being overridden.
+		 * The association whose default fetch strategy is being
+		 * overridden.
 		 */
 		String association();
 
 		/**
-		 * The fetch mode to apply to the association.
+		 * The {@linkplain FetchMode fetching strategy} to apply to
+		 * the association in the fetch profile being defined.
 		 */
 		FetchMode mode();
 	}

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

@@ -7,7 +7,7 @@
 package org.hibernate.engine.profile;
 
 /**
- * Models an individual fetch within a profile.
+ * Models an individual fetch override within a profile.
  *
  * @author Steve Ebersole
  */

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

@@ -15,10 +15,22 @@
 import org.hibernate.type.Type;
 
 /**
- * A 'fetch profile' allows a user to dynamically modify the fetching strategy used for particular associations at
- * runtime, whereas that information was historically only statically defined in the metadata.
- * <p/>
- * This class defines the runtime representation of this data.
+ * The runtime representation of a Hibernate
+ * {@linkplain org.hibernate.annotations.FetchProfile fetch profile}
+ * defined in annotations.
+ * <p>
+ * Fetch profiles compete with JPA-defined
+ * {@linkplain jakarta.persistence.NamedEntityGraph named entity graphs}.
+ * The semantics of these two facilities are not identical, however,
+ * since a fetch profile is a list, not a graph, and is not by nature
+ * rooted at any one particular entity. Instead, given a root entity as
+ * input, an active fetch profile contributes to the determination of
+ * the fetch graph.
+ * <p>
+ * A named fetch profile may be enabled in a given session
+ * by calling {@link org.hibernate.Session#enableFetchProfile(String)}.
+ *
+ * @see org.hibernate.mapping.FetchProfile
  *
  * @author Steve Ebersole
  */
@@ -42,7 +54,7 @@ public FetchProfile(String name) {
 	}
 
 	/**
-	 * Add a fetch to the profile.
+	 * Add a fetch override to the profile.
 	 *
 	 * @param association The association to be fetched
 	 * @param fetchStyleName The name of the fetch style to apply
@@ -53,7 +65,7 @@ public void addFetch(Association association, String fetchStyleName) {
 	}
 
 	/**
-	 * Add a fetch to the profile.
+	 * Add a fetch override to the profile.
 	 *
 	 * @param association The association to be fetched
 	 * @param style The style to apply
@@ -63,7 +75,7 @@ public void addFetch(Association association, Fetch.Style style) {
 	}
 
 	/**
-	 * Add a fetch to the profile.
+	 * Add a fetch override to the profile.
 	 *
 	 * @param fetch The fetch to add.
 	 */

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

@@ -8,10 +8,7 @@
 import java.util.LinkedHashSet;
 
 /**
- * A fetch profile allows a user to dynamically modify the fetching strategy used for particular associations at
- * runtime, whereas that information was historically only statically defined in the metadata.
- * <p/>
- * This class represent the data as it is defined in their metadata.
+ * A mapping model object representing a {@link org.hibernate.annotations.FetchProfile}.
  *
  * @author Steve Ebersole
  *