JPA : Entity Graphs

When an object is retrieved from the datastore by JPA typically not all fields are retrieved
immediately. This is because for efficiency purposes only particular field types are retrieved in the
initial access of the object, and then any other objects are retrieved when accessed (lazy loading).
The group of fields that are loaded is called an entity graph.
There are 3 types of "entity graphs" to consider

Named Entity Graphs : a new feature in JPA 2.1 allowing the user to
define Named Entity Graphs in metadata, via annotations or XML

Unnamed Entity Graphs : a new feature in JPA 2.1 allowing the user to
define Entity Graphs via the JPA API at runtime

Default Entity Graph

JPA provides an initial entity graph, comprising the fields that will be retrieved when an object
is retrieved if the user does nothing to define the required behaviour. You define this "default"
by setting the fetch attribute in metadata for each field/property.

Named Entity Graphs

You can predefine Named Entity Graphs in metadata which can then be used at runtime
when retrieving objects from the datastore (via find/query).
For example, if we have the following class

class MyClass
{
String name;
HashSet coll;
MyOtherClass other;
}

and we want to have the option of the other field loaded whenever we load objects of this
class, we define our annotations as

Here we have made use of the EntityManager.find method and provided the property
javax.persistence.loadgraph to be our EntityGraph. This means that it will fetch
all fields in the default EntityGraph, plus all fields in the includeOther
EntityGraph. If we had provided the property javax.persistence.fetchgraph set to our
EntityGraph it would have fetched just the fields defined in that EntityGraph.

Note that you can also make use of EntityGraphs when using the JPA Query API, specifying
the same properties above but as query hints.

Unnamed Entity Graphs

You can define Entity Graphs at runtime, programmatically.
For example, if we have the following class

class MyClass
{
String name;
HashSet coll;
MyOtherClass other;
}

and we want to have the option of the other field loaded whenever we load objects of this
class, we do the following

Here we have made use of the EntityManager.find method and provided the property
javax.persistence.loadgraph to be our EntityGraph. This means that it will fetch
all fields in the default EntityGraph, plus all fields in this EntityGraph.
If we had provided the property javax.persistence.fetchgraph set to our
EntityGraph it would have fetched just the fields defined in that EntityGraph.

Note that you can also make use of EntityGraphs when using the JPA Query API, specifying
the same properties above but as query hints.