Annotation Type FetchProfile

  • @Target({TYPE,PACKAGE})
    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:
    FetchProfileOverride, Session.enableFetchProfile(String), SessionFactory.containsFetchProfileDefinition(String)
    • Required Element Summary

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