5.5. Fetch Group Element

5.5. Fetch Group Element
Prev	Chapter 5. Metadata	Next

Fetch groups are sets of fields that are loaded together. You may recall that a field can use the default-fetch-group attribute to control whether it is in the default fetch group. JDO also allows you to create other fetch groups. As you will see in Chapter 12, FetchPlan, you can use fetch groups in conjunction with JDO's FetchPlan interface to fine-tune data loading.

You create fetch groups with the fetch-group metadata element. This element goes within the class element, after all field elements. Classes can define multiple fetch groups. The fetch-group element has the following attributes:

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 JDO: default, values, all, none, and any name beginning with jdo.

	Note
	Kodo also reserves fetch group names beginning with `ejb` or `kodo`.

Each fetch-group contains field elements. As you might expect, listing a field within a fetch-group includes that field in the fetch group. Each fetch group field can have the following attributes:

name: The name of the persistent field.
fetch-depth: If the field represents a relation, the depth to which to recurse. The current fetch group will be applied to the related object when fetching it, and so on until the depth is exhausted or the related object has no relation fields in the current fetch group. Under the default depth of 1, the related object will be fetched, but none of its relation fields will be traversed, even if they are in the current fetch group. With a depth of 2, the related object will be fetched, and if it has any relation fields in the current fetch group, those will be fetched with a depth of 1. A depth of 0 indicates that the recursion continues until the graph is exhausted or a related object has no relation fields in the current fetch group.

Thus, to create a detail fetch group consisting of the publisher and articles relations, with the fetch group applied recursively to the related objects, use:

<fetch-group name="detail">
    <field name="publisher" fetch-depth="0"/>
    <field name="articles" fetch-depth="0"/>
</fetch-group>

Note

Kodo currently places the following restrictions on fetch groups:

A given field may be in only one fetch group, including the default fetch group.
All relation fields included in a custom fetch group must set their fetch-depth to 0, meaning the fetch group will be applied recursively to arbitrary depth.

The behavior mandated by these restrictions mimics the behavior of previous Kodo versions.

Prev	Up	Next
5.4. Field Element	Home	5.6. The Complete Document