The Java EE 7 Tutorial
43.2 Using Named Entity Graphs
Named entity graphs are created using annotations applied to entity classes or the named-entity-graph
element and its sub-elements in the application's deployment descriptor. The persistence provider will scan for all named entity graphs, defined in both annotations and in XML, within an application. A named entity graph set using an annotation may be overridden using named-entity-graph
.
43.2.1 Applying Named Entity Graph Annotations to Entity Classes
The javax.persistence.NamedEntityGraph
annotation defines a single named entity graph and is applied at the class level. Multiple @NamedEntityGraph
annotations may be defined for a class by adding them within a javax.persistence.NamedEntityGraphs
class-level annotation.
The @NamedEntityGraph
annotation must be applied on the root of the graph of entities. That is, if the EntityManager.find
or query operation has as its root entity the EmailMessage
class, the named entity graph used in the operation must be defined in the EmailMessage
class:
@NamedEntityGraph @Entity public class EmailMessage { @Id String messageId; String subject; String body; String sender; }
In this example, the EmailMessage
class has a @NamedEntityGraph
annotation to define a named entity graph that defaults to the name of the class, EmailMessage
. No fields are included in the @NamedEntityGraph
annotation as attribute nodes, and the fields are not annotated with metadata to set the fetch type, so the only field that will be eagerly fetched in either a load graph or fetch graph is messageId
.
The attributes of a named entity graph are the fields of the entity that should be included in the entity graph. Add the fields to the entity graph by specifying them in the attributeNodes
element of @NamedEntityGraph
with a javax.persistence.NamedAttributeNode
annotation:
@NamedEntityGraph(name="emailEntityGraph", attributeNodes={ @NamedAttributeNode("subject"), @NamedAttributeNode("sender") }) @Entity public class EmailMessage { ... }
In this example, the name of the named entity graph is emailEntityGraph
and includes the subject
and sender
fields.
Multiple @NamedEntityGraph
definitions may be applied to a class by grouping them within a @NamedEntityGraphs
annotation.
In the following example, two entity graphs are defined on the EmailMessage
class. One is for a preview pane, which fetches only the sender, subject, and body of the message. The other is for a full view of the message, including any message attachments:
@NamedEntityGraphs({ @NamedEntityGraph(name="previewEmailEntityGraph", attributeNodes={ @NamedAttributeNode("subject"), @NamedAttributeNode("sender"), @NamedAttributeNode("body") }), @NamedEntityGraph(name="fullEmailEntityGraph", attributeNodes={ @NamedAttributeNode("sender"), @NamedAttributeNode("subject"), @NamedAttributeNode("body"), @NamedAttributeNode("attachments") }) }) @Entity public class EmailMessage { ... }