Annotation Interface Fetch

@Target({FIELD,METHOD}) @Retention(RUNTIME) @Repeatable(Fetch.Fetches.class) public @interface Fetch
Specifies options influencing how an attribute is fetched.
  • By default, the options apply when not overridden by an entity graph. For a load graph, options specified via the @Fetch annotation are overridden when the graph has an attribute node representing the annotated attribute. For a fetch graph, options specified by @Fetch are always considered overridden.
  • When a graph name is specified, the options apply when the attribute is fetched using the named entity graph with the specified name and the named graph contains an attribute node representing the annotated attribute.

In this example, the @Fetch annotation is equivalent to having specified @ManyToMany(fetch=EAGER): 

@Fetch
@ManyToMany
List<Author> authors;

In this example, additional options influencing the mechanics of fetching the associated entity are specified: 

@Fetch(cacheStoreMode=BYPASS, batchSize = 10)
@ManyToMany
List<Author> authors;

In this example, the options only apply when the named entity graph BooksWithAuthors is used: 

@Fetch(cacheStoreMode=BYPASS, batchSize = 10,
       graph = "BooksWithAuthors")
@ManyToMany
List<Author> authors;

Multiple @Fetch annotations may be specified for a single attribute: 

@Fetch // eager by default
@Fetch(cacheStoreMode=BYPASS, batchSize = 10,
       graph = "BooksWithAuthors")
@ManyToMany
List<Author> authors;
At most one such @Fetch annotation may have a missing graph() name.
Since:
4.0
See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static @interface 
    Fetch.Fetches
     

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    int
    batchSize
    A batch size, that is, how many entities should be fetched in each request to the database.
    CacheRetrieveMode
    cacheRetrieveMode
    Specifies whether the persistence provider is permitted to read the associated entity data from the cache.
    CacheStoreMode
    cacheStoreMode
    Specifies whether the persistence provider should cache the associated entity after fetching it from the database.
    String
    graph
    The name of an entity graph.
    QueryHint[]
    hints
    Vendor-specific fetching hints.
    String[]
    subgraph
    The names of one or more entity graphs to be attached as subgraphs of the named entity graph to the attribute node representing the annotated association.
    FetchType
    type
    The fetching policy.

  • Element Details

    • graph

      String graph
      The name of an entity graph.
      • If no entity graph name is specified, the specified fetching options apply when the attribute is fetched without the use of an entity graph.
      • Otherwise, the specified fetching options apply when the attribute is fetched using the entity graph with the specified name. The named graph contains an attribute node representing the annotated attribute.

      At most one @Fetch annotation of a given field or property may have a missing graph name.

      Default:
      ""

    • subgraph

      String[] subgraph
      The names of one or more entity graphs to be attached as subgraphs of the named entity graph to the attribute node representing the annotated association.

      The annotated attribute must be an association.

      Default:
      {}

    • type

      FetchType type
      The fetching policy. Overrides the value specified by the fetch member of the Basic, OneToOne, ManyToOne, OneToMany, ManyToMany, or ElementCollection annotation.
      Default:
      EAGER

    • batchSize

      int batchSize
      A batch size, that is, how many entities should be fetched in each request to the database. This option is always a hint, and might be ignored by the persistence provider.
      Default:
      -1

    • cacheStoreMode

      CacheStoreMode cacheStoreMode
      Specifies whether the persistence provider should cache the associated entity after fetching it from the database.
      Default:
      USE

    • cacheRetrieveMode

      CacheRetrieveMode cacheRetrieveMode
      Specifies whether the persistence provider is permitted to read the associated entity data from the cache.
      Default:
      USE

    • hints

      QueryHint[] hints
      Vendor-specific fetching hints.

      Any hint not recognized by a provider is ignored.

      Default:
      {}