Основы графа сущностей

Графы сущностей могут быть созданы аннотациями или в дескрипторе развёртывания статически или стандартными интерфейсами динамически.

Граф сущностей можно использовать с методом EntityManager.find или как часть запроса JPQL или Criteria, указав граф сущностей в качестве подсказки для операции или запроса.

Графы сущностей имеют атрибуты, соответствующие полям, для которых будет использоваться раннее (eager) извлечение во время выполнения find или операции запроса. Поля первичного ключа и версии класса сущностей всегда выбираются и не требуют явного добавления к графу сущностей.

Граф сущностей по умолчанию

По умолчанию все поля объекта сущности извлекаются отложенно (lazy), если только для атрибута fetch метаданных сущности не установлено значение javax.persistence.FetchType.EAGER. Граф сущностей по умолчанию состоит из всех полей сущности, для которых установлено раннее (eager) извлечение.

Например, следующая сущность EmailMessage указывает, что для некоторых полей будет выполняться раннее (eager) извлечение:

@Entity
public class EmailMessage implements Serializable {
    @Id
    String messageId;
    @Basic(fetch=EAGER)
    String subject;
    String body;
    @Basic(fetch=EAGER)
    String sender;
    @OneToMany(mappedBy="message", fetch=LAZY)
    Set<EmailAttachment> attachments;
    ...
}

Граф сущностей по умолчанию для этой сущности будет содержать поля messageId, subject и sender, но не поля body и attachments.

Использование графов сущностей в персистентных операциях

Графы сущностей представляет собой объект интерфейса javax.persistence.EntityGraph и создаётся путём вызова либо EntityManager.getEntityGraph для именованных графов сущностей, либо EntityManager.createEntityGraph для динамических графов сущностей.

Именованный граф сущностей — это граф сущностей, определённый аннотацией @NamedEntityGraph, применяемой к классам сущностей или элементом named-entity-graph в дескрипторе развёртывания приложения. Именованные графы сущностей, определённые в дескрипторе развёртывания, переопределяют любые графы сущностей на основе аннотаций с тем же именем.

Созданный граф сущностей может быть либо графом выборки, либо графом загрузки.

Здесь рассматриваются следующие темы:

Графы выборки
Графы загрузки

Графы выборки

Чтобы указать граф выборки, установите свойство javax.persistence.fetchgraph при выполнении EntityManager.find или операции запроса. Граф выборки состоит только из полей, явно указанных в объекте EntityGraph, и игнорирует настройки графа сущностей по умолчанию.

В следующем примере граф сущностей по умолчанию игнорируется, и в динамически создаваемый граф выборки включается только поле body:

EntityGraph<EmailMessage> eg = em.createEntityGraph(EmailMessage.class);
eg.addAttributeNodes("body");
...
Properties props = new Properties();
props.put("javax.persistence.fetchgraph", eg);
EmailMessage message = em.find(EmailMessage.class, id, props);

Графы загрузки

Чтобы указать граф загрузки, установите свойство javax.persistence.loadgraph при выполнении EntityManager.find или операции запроса. Граф загрузки состоит из полей, явно указанных в объекте EntityGraph, а также любых полей в графе сущностей по умолчанию.

В следующем примере динамически создаваемый граф загрузки содержит все поля в графе сущностей по умолчанию плюс поле body:

EntityGraph<EmailMessage> eg = em.createEntityGraph(EmailMessage.class);
eg.addAttributeNodes("body");
...
Properties props = new Properties();
props.put("javax.persistence.loadgraph", eg);
EmailMessage message = em.find(EmailMessage.class, id, props);