Javadoc surrounding fetch profiles

This commit is contained in:
Gavin King 2022-11-06 13:45:49 +01:00
parent f9164fc32f
commit 971a022eb6
6 changed files with 95 additions and 32 deletions

View File

@ -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;

View File

@ -12,11 +12,15 @@ import java.lang.annotation.RetentionPolicy;
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)

View File

@ -15,11 +15,54 @@ import static java.lang.annotation.ElementType.TYPE;
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 @@ public @interface FetchProfile {
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();
}

View File

@ -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
*/

View File

@ -15,10 +15,22 @@ import org.hibernate.type.BagType;
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 class FetchProfile {
}
/**
* 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 class FetchProfile {
}
/**
* 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 class FetchProfile {
}
/**
* Add a fetch to the profile.
* Add a fetch override to the profile.
*
* @param fetch The fetch to add.
*/

View File

@ -8,10 +8,7 @@ package org.hibernate.mapping;
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
*