3.6.7.1. Custom Fetch Groups
OpenJPA places any field that is eagerly loaded according to the JPA metadata rules into the built-in default fetch group. As its name implies, the default fetch group is active by default. You may also define your own named fetch groups and activate or deactivate them at runtime, as described later in this chapter. OpenJPA will eagerly-load the fields in all active fetch groups when loading objects from the datastore.
You create fetch groups with the
org.apache.openjpa.persistence.FetchGroup annotation.
If your class only has one custom fetch group, you can place this annotation directly on the class declaration.
Otherwise, use the
org.apache.openjpa.persistence.FetchGroups annotation to declare an array of individual FetchGroup values.
The FetchGroup annotation has the following properties:
-
String name: The name of the fetch group. Fetch group names are global, and are expected to be shared among classes. For example, a shopping website may use a detail fetch group in each product class to efficiently load all the data needed to display a product’s "detail" page. The website might also define a sparse list fetch group containing only the fields needed to display a table of products, as in a search result.
The following names are reserved for use by OpenJPA: default , values, all, none, and any name beginning with jdo, jpa, or openjpa.
* FetchAttribute[] attributes: The set of persistent fields or properties in the fetch group.
* String[] fetchGroups: Other fetch groups whose fields to include in this group.
As you might expect, listing a
org.apache.openjpa.persistence.FetchAttribute within a FetchGroup includes the corresponding persistent field or property in the fetch group.
Each FetchAttribute has the following properties:
-
String name: The name of the persistent field or property to include in the fetch group. -
recursionDepth: If the attribute represents a relation, the maximum number of same-typed relations to eager-fetch from this field. Defaults to 1. For example, consider anEmployeeclass with amanagerfield, also of typeEmployee. When we load anEmployeeand themanagerfield is in an active fetch group, the recursion depth (along with the max fetch depth setting, described below) determines whether we only retrieve the targetEmployeeand his manager (depth 1), or whether we also retrieve the manager’s manager (depth 2), or the manager’s manager’s manager (depth 3), etc. Use -1 for unlimited depth.
Creates a detail fetch group consisting of the publisher and articles relations.
import org.apache.openjpa.persistence.*;
@Entity
@FetchGroups({
@FetchGroup(name="detail", attributes={
@FetchAttribute(name="publisher"),
@FetchAttribute(name="articles")
}),
...
})
public class Magazine {
...
}
A field can be a member of any number of fetch groups. A field can also declare a load fetch group. When you access a lazy-loaded field for the first time, OpenJPA makes a datastore trip to fetch that field’s data. Sometimes, however, you know that whenever you access a lazy field A, you’re likely to access lazy fields B and C as well. Therefore, it would be more efficient to fetch the data for A, B, and C in the same datastore trip. By setting A’s load fetch group to the name of a fetch group containing B and C, you can tell OpenJPA to load all of these fields together when A is first accessed.
Use OpenJPA’s org.apache.openjpa.persistence.LoadFetchGroup annotation to specify the load fetch group of any persistent field. The value of the annotation is the name of a declared fetch group whose members should be loaded along with the annotated field.
import org.apache.openjpa.persistence.*;
@Entity
@FetchGroups({
@FetchGroup(name="detail", attributes={
@FetchAttribute(name="publisher"),
@FetchAttribute(name="articles")
}),
...
})
public class Magazine {
@ManyToOne(fetch=FetchType.LAZY)
@LoadFetchGroup("detail")
private Publisher publisher;
...
}