What are Entity Subgraphs?

In JPA, a sub entity graph is used to define "fetch plan" for an entity involving relationship to this entity. Subgraphs are defined by using @NamedSubgraph annotation. This annotation is used within the main @NamedEntityGraph annotation (last tutorial) via the attribute of 'subgraphs' . The reference of a subgraph (by using its name) is used by the 'subgraph' attribute of @NamedSubgraph. Let's understand that by an example.

Example

First we are not going to use @NamedEntityGraph on our entity:

@Entity
@NamedEntityGraph(name = "graph.module.projects.contractors",
      attributeNodes = @NamedAttributeNode(value = "projects", subgraph = "projects.contractors"),
      subgraphs = @NamedSubgraph(name = "projects.contractors",
              attributeNodes = @NamedAttributeNode(value = "contractors")))
public class TradingModule {
  @Id
  @GeneratedValue
  private int id;
  private String name;
  @OneToMany(cascade = CascadeType.ALL, fetch = FetchType.LAZY)
  private Set<Project> projects;
    .............
}

@Entity
public class Project {
  @Id
  @GeneratedValue
  private int id;
  private String name;
  @OneToMany(cascade = CascadeType.ALL, fetch = FetchType.LAZY)
  private Set<Contractor> contractors;
    .............
}

@Entity
public class Contractor {
  @Id
  @GeneratedValue
  private long id;
  private String name;
  private String role;

  public Contractor() {
  }

  public Contractor(String name, String role) {
      this.name = name;
      this.role = role;
  }
    .............
}

Using find() without an Entity Graph

public class ExampleMain {
  private static EntityManagerFactory entityManagerFactory =
          Persistence.createEntityManagerFactory("example-unit");

  public static void main(String[] args) {
      try {
          persistEntity();
          findEntity();
      } finally {
          entityManagerFactory.close();
      }
  }

  public static void persistEntity() {
      TradingModule module = getTradingModule();
      EntityManager em = entityManagerFactory.createEntityManager();
      em.getTransaction().begin();
      em.persist(module);
      em.getTransaction().commit();
      em.close();
  }

  private static void findEntity() {
      EntityManager em = entityManagerFactory.createEntityManager();
      Map<String, Object> properties = new HashMap<>();
      TradingModule module = em.find(TradingModule.class, 1, properties);
      em.close();
      printInitializeState(module);
  }

  private static void printInitializeState(TradingModule module) {
      PersistenceUtil pu = entityManagerFactory.getPersistenceUnitUtil();
      printState("TradingModule", pu.isLoaded(module));
      printState("TradingModule.name", pu.isLoaded(module, "name"));
      printState("TradingModule.projects", pu.isLoaded(module, "projects"));
      if (pu.isLoaded(module, "projects")) {
          for (Project project : module.getProjects()) {
              printState("Project", pu.isLoaded(project));
              printState("Project.name", pu.isLoaded(module, "project.name"));
              printState("Projects.contractors", pu.isLoaded(module, "project.contractors"));
          }
      }
  }

  private static void printState(String msg, boolean loaded) {
      System.out.printf("%25s loaded: %s%n", msg, loaded);
  }

  public static TradingModule getTradingModule() {
      Project project = new Project();
      project.setName("Price/Yield Calculator");
      project.addContractor(new Contractor("Margaret", "Project Manager"));
      project.addContractor(new Contractor("Steven", "Developer"));
      project.addContractor(new Contractor("Claudie", "Business Analyst"));

      TradingModule module = new TradingModule();
      module.setName("Fixed Income");
      module.addProject(project);
      return module;
  }
}

            TradingModule loaded: true
       TradingModule.name loaded: true
   TradingModule.projects loaded: false

Using Entity Graph with javax.persistence.fetchgraph

public class ExampleMain2 {
  private static EntityManagerFactory entityManagerFactory =
          Persistence.createEntityManagerFactory("example-unit");
    .............
  private static void findEntity() {
      EntityManager em = entityManagerFactory.createEntityManager();
      EntityGraph graph = em.getEntityGraph("graph.module.projects.contractors");
      Map<String, Object> properties = new HashMap<>();
      properties.put("javax.persistence.fetchgraph", graph);
      TradingModule module = em.find(TradingModule.class, 1, properties);
      em.close();
      printInitializeState(module);
  }
    .............
}

            TradingModule loaded: true
       TradingModule.name loaded: true
   TradingModule.projects loaded: true
                  Project loaded: true
             Project.name loaded: true
     Projects.contractors loaded: true

Check out the last tutorial, to understand 'fetchgraph' semantics defined by JPA specification and why Hibernate ignores some of the rules.

Example Project

Dependencies and Technologies Used:

• h2 1.4.196: H2 Database Engine.
• hibernate-core 5.2.12.Final: The core O/RM functionality as provided by Hibernate.
  Implements javax.persistence:javax.persistence-api version 2.1
• JDK 1.8
• Maven 3.3.9