Javadoc surrounding fetch profiles
This commit is contained in:
parent
f9164fc32f
commit
971a022eb6
|
@ -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;
|
||||
|
||||
|
|
|
@ -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)
|
||||
|
|
|
@ -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();
|
||||
}
|
||||
|
|
|
@ -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
|
||||
*/
|
||||
|
|
|
@ -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.
|
||||
*/
|
||||
|
|
|
@ -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
|
||||
*
|
||||
|
|
Loading…
Reference in New Issue