Package org.hibernate.annotations

Annotation Interface FetchProfile

@Target({TYPE,PACKAGE}) @Retention(RUNTIME) @Repeatable(FetchProfiles.class) public @interface FetchProfile
Defines a fetch profile, by specifying its name(), together with a list of fetch strategy overrides. The definition of a single named fetch profile may be split over multiple @FetchProfile annotations which share the same name().

Additional fetch strategy overrides may be added to a named fetch profile by annotating the fetched associations themselves with the @FetchProfileOverride annotation, specifying the name of the fetch profile.

A named fetch profile must be explicitly enabled in a given session by calling Session.enableFetchProfile(String) for it to have any effect at runtime.

Fetch profiles compete with JPA-defined named entity graphs, and so programs which wish to maintain compatibility with alternative implementations of JPA should prefer @NamedEntityGraph. The semantics of these two facilities are not quite identical, however, since a fetch profile is a list, not a graph.

Or, if we insist on thinking in terms of graphs:

  • for a fetch profile, the graph is implicit, determined by recursively following fetched associations from the root entity, and each FetchProfile.FetchOverride in the fetch profile applies the same fetching strategy to the overridden association wherever it is reached recursively within the graph, whereas
  • an entity graph is explicit, and simply specifies that each path from the root of the graph should be fetched.

However, a fetch profile is not by nature rooted at any one particular entity, and so @FetchProfile is not required to annotate the entity classes it affects. It may even occur as a package-level annotation.

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 Session.get(Class, Object) is called, then the root entity is the entity with the given Class. Given a root entity as input, an active fetch profile contributes to the determination of the fetch graph.

A JPA EntityGraph may be constructed in Java code at runtime. But this amounts to a separate, albeit extremely limited, query facility that competes with JPA's own criteria queries. There's no such capability for fetch profiles.

See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static @interface 
    FetchProfile.FetchOverride
    Overrides the fetching strategy for a particular association in the named fetch profile being defined.

  • Required Element Summary

    Required Elements
    Modifier and Type
    Required Element
    Description
    String
    name
    The name of the fetch profile.

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    FetchProfile.FetchOverride[]
    fetchOverrides
    The list of association fetching strategy overrides.