Interface EntityGraph<T>

Type Parameters:
T - The type of the root entity.
All Superinterfaces:
Graph<T>
public interface EntityGraph<T> extends Graph<T>
An entity graph is a template that captures the boundaries of an operation or query. Every entity graph has a root entity. An instance of EntityGraph is the root node of a graph and represents this entity. The child nodes of the root node represent persistent attributes, embedded objects, or associations to other entities. A node representing an embedded object or an association to an entity might be the root of a subgraph with its own child nodes.

An entity graph is usually used to control the data fetched from the database. The attribute nodes and subgraphs of an entity graph determine the limits of the graph of associated attributes and entities fetched when an operation retrieves an instance or instances of the root entity of the graph.

When used to specify fetching, an entity graph has two possible interpretations:

  • As a load graph, where every node explicitly added to or explicitly removed from the graph overrides the fetching strategy of the attribute which was specified via annotations or XML descriptor, but the graph does not affect the fetching strategy of any attribute which was neither added to nor removed from the graph.
  • As a fetch graph, where the graph completely overrides every fetching strategy specified via annotations or XML descriptor, and every attribute not explicitly added to the graph is treated as FetchType.LAZY.

An entity graph passed as the first argument to EntityHandler.find(EntityGraph, Object, FindOption...), EntityHandler.get(EntityGraph, Object, FindOption...), or TypedQuery.setEntityGraph(EntityGraph) is interpreted as a load graph. 

 // create the root node of an entity graph
 var employeeGraph = Employee_.class_.createEntityGraph();
 // define a subgraph rooted at a @ManyToOne association
 var employerGraph = employeeGraph.addSubgraph(Employee_.employer);
 employerGraph.addAttributeNode(Employer_.industry);
 // define a subgraph rooted at a @OneToMany association
 var projectGraph = employeeGraph.addElementSubgraph(Employee_.projects);
 projectGraph.addAttributeNode(Project_.lead);
 projectGraph.addAttributeNode(Project_.tasks);
 // load an employee, making use of the graph to fetch a tree of
 // associated objects (the graph is interpreted as a load graph)
 Employee employee = entityManager.get(employeeGraph, employeeId);

The persistence provider is always permitted to fetch additional entity state beyond that specified by a fetch graph or load graph. It is required, however, that the persistence provider fetch all state specified by the fetch or load graph.

Since:
2.1
See Also:
API note:
Support for lazy fetching of basic fields and properties varies between persistence providers and even between container environments. Therefore, the behavior of a fetch graph, or of a load graph which explicitly removes a basic attribute, is likely to lack portability.

  • Method Details

    • getName

      String getName()
      Return the name of a named EntityGraph (an entity graph defined by means of the NamedEntityGraph annotation, XML descriptor element, or added by means of the EntityManagerFactory.addNamedEntityGraph(String, EntityGraph) method). Returns null if the EntityGraph is not a named EntityGraph.

    • addTreatedSubgraph

      <S extends T> Subgraph<S> addTreatedSubgraph(Class<S> type)
      Add additional attributes to this entity graph that correspond to attributes of subclasses of the entity type of this EntityGraph. Subclass subgraphs automatically include the specified attributes of superclass subgraphs.
      Parameters:
      type - entity subclass
      Returns:
      subgraph for the subclass
      Throws:
      IllegalArgumentException - if the type is not an entity type
      IllegalStateException - if the EntityGraph has been statically defined