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.

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 { ... }

Obtaining EntityGraph Instances from Named Entity Graphs

Use the EntityManager.getEntityGraph method, passing in the named entity graph name, to obtain EntityGraph instances for a named entity graph:

EntityGraph<EmailMessage> eg = em.getEntityGraph("emailEntityGraph");