Annotation Interface NamedEntityGraph

@Repeatable(NamedEntityGraphs.class) @Target(TYPE) @Retention(RUNTIME) public @interface NamedEntityGraph
Declares a named entity graph or subgraph of a named entity graph. This annotation must be applied to the root entity of the graph or subgraph.

The nodes and subgraphs of an entity graph control the limits of the graph of associated attributes and entities fetched when an operation which retrieves an instance or instances of the root entity is executed.

A well-defined entity graph is a tree. The application program is responsible for ensuring that every named entity graph is acyclic. If a named entity graph contains a cycle, the behavior is undefined. A provider may reject the graph at runtime; it may reject it when the persistence unit is initialized; or it may transform the graph into an acyclic graph according to some vendor-specific algorithm. Portable applications must avoid relying on such behavior.

There are two ways to specify the nodes and subgraphs of a named entity graph defined in annotations:

The two approaches may be mixed within the same entity graph definition.

In the first approach, the definition of the named entity graph is distributed across the entity class and its associated classes, with the help of the Fetch annotation. 

@NamedEntityGraph(name = "EmployeeWithProjectTasksAndEmployer")
@Entity // root entity of graph
public class Employee {
    ...
    // fetched attribute node
    @Fetch(graph = "EmployeeWithProjectTasksAndEmployer")
    @ManyToOne(fetch=LAZY) Employer employer;

    // reference to subgraph defined in Project class
    @Fetch(graph = "EmployeeWithProjectTasksAndEmployer"
           subgraph = "EmployeeWithProjectTasksAndEmployer")
    @ManyToMany Set<Project> projects;
}

@NamedEntityGraph(name = "EmployeeWithProjectTasksAndEmployer")
@Entity // root entity of subgraph
public class Project {
    ...
    // reference to subgraph defined in Task class
    @Fetch(graph = "EmployeeWithProjectTasksAndEmployer")
    @OneToMany List<Task> tasks;
}

When a subgraph is declared, there might be multiple entity classes with NamedEntityGraph annotations specifying identical values for the name member. In this scenario, the root entity of the named graph is identified by it being the unique entity class that is not referenced by the subgraph member of any Fetch annotation belonging to the named graph. If there is no such entity class, or if it is not unique, the behavior is undefined. An application must ensure that each named entity graph has a unique root entity.

In the second approach, the definition of the named entity graph is contained entirely within the NamedEntityGraph annotation. 

@NamedEntityGraph(
        name = "EmployeeWithProjectTasksAndEmployer",
        // fetched attributes of Employee
        attributeNodes = {
            @NamedAttributeNode("projects"),
            @NamedAttributeNode(
                    value = "employer", // name of association
                    subgraph = "Projects" // reference to subgraph
            )
        },
        // list of subgraphs of the entity graph
        subgraphs = {
            // subgraph specifying fetched attributes of Project
            @NamedSubgraph(
                    name = "Projects",
                    // fetched attributes of Project
                    attributeNodes = @NamedAttributeNode(
                            value = "tasks", // name of association
                            subgraph = "Tasks" // reference to subgraph
                    )
            ),
            // subgraph specifying fetched attributes of Task
            @NamedSubgraph(
                    name = "Tasks",
                    attributeNodes = ...
            )
        }
)
@Entity // root entity of graph
public class Employee { ... }

A named entity graph defined using annotations is reified at runtime as an instance of EntityGraph, and its child nodes and subgraphs are reified respectively as instances of AttributeNode and Subgraph.

A reference to a named entity graph may be obtained by calling EntityManagerFactory.getNamedEntityGraphs(Class) or EntityHandler.getEntityGraph(String) and may be passed to EntityHandler.find(EntityGraph, Object, FindOption...) or EntityHandler.get(EntityGraph, Object, FindOption...). 

Object employee =
        em.find(em.getEntityGraph("EmployeeWithProjects"),
                employeeId);

Alternatively, a reference to a named entity graph may be obtained from the EntityManagerFactory. 

EntityGraph<Employee> graph =
        emf.getNamedEntityGraphs(Employee.class)
            .get("EmployeeWithProjects")
Employee employee = em.find(graph, employeeId);

Alternatively, a reference to a named entity graph may be obtained from the static metamodel. 

Employee employee =
        em.find(Employee_._EmployeeWithProjects,
                employeeId);
Since:
2.1
See Also:

  • Element Details

    • name

      String name
      (Optional) The name used to identify this entity graph in calls to EntityHandler.getEntityGraph(String). If no name is explicitly specified, the name defaults to the entity name of the annotated root entity.

      Entity graph names must be unique within a given persistence unit. If two @NamedEntityGraph annotations declare the same name, then one must be a subgraph of the other, as specified via the Subgraph annotations.

      Default:
      ""

    • attributeNodes

      NamedAttributeNode[] attributeNodes
      (Optional) A list of attributes of the entity that are included in this graph.
      API note:
      Alternatively, use AttributeNode
      Default:
      {}

    • includeAllAttributes

      boolean includeAllAttributes
      (Optional) Includes every attribute of the annotated entity class as an attribute node in the NamedEntityGraph without the need to explicitly list them. Included attributes can still be fully specified by an attribute node referencing a subgraph.
      Default:
      false

    • subgraphs

      NamedSubgraph[] subgraphs
      (Optional) A list of subgraphs that are included in the entity graph. These are referenced by name from NamedAttributeNode annotations.
      See Also:
      API note:
      Alternatively, use Subgraph
      Default:
      {}

    • subclassSubgraphs

      NamedSubgraph[] subclassSubgraphs
      (Optional) A list of subgraphs that will add additional attributes for subclasses of the annotated entity class to the entity graph. Specified attributes from superclasses are included in subclasses.
      See Also:
      Default:
      {}