@FetchGroup

Use @FetchGroup to load a group of attributes on demand, as needed.

This avoids wasteful practice of loading all data of the object's attributes, if which the user is interested in only partial of them. However, it also means that the data for an attribute might not loaded from the underlying data source until an explicit access call for the attribute first occurs.

Annotation Elements

Table 2-22 describes this annotation's elements.

Usage

You should perform a careful use case analysis when using @FetchGroup; any gains realized from the deferred loading could be offset by the extra round-trip.

EclipseLink supports fetch groups at two levels:

• Pre-defined fetch groups at the Entity or MappedSuperclass level

• Dynamic (use case) fetch groups at the query level

You can use fetch groups only when using weaving or when individual classes that define them explicitly implement the org.eclipse.persistence.queries.FetchGroupTracker interface.

When using a fetch group, you can define a subset of an object's attributes and associate the fetch group with a query. When you execute the query, EclipseLink retrieves only the attributes in the fetch group. EclipseLink automatically executes a query to fetch all the attributes excluded from this subset when and if you call a get method on any one of the excluded attributes.

You can define more than one fetch group for a class. You can optionally designate at most one such fetch group as the default fetch group. If you execute a query without specifying a fetch group, EclipseLink will use the default fetch group, unless you configure the query otherwise.

Before using fetch groups, we recommend that you perform a careful analysis of system use. In many cases, the extra queries required to load attributes not in the fetch group could well offset the gain from the partial attribute loading.

Examples

Example 2-44 show how to use this annotation.

@FetchGroup(name="names", attributes={
    @FetchAttribute(name="firstName"), 
    @FetchAttribute(name="lastName")})

Example 2-44 show how to use this feature in the eclipselink-orm.xml file.

<entity class="model.Employee">
    <secondary-table name="SALARY" />
    <fetch-group name="names">
        <attribute name="firstName" />
        <attribute name="lastName" />
    </fetch-group>
...

You can also use a named fetch group with a query, as shown in Example 2-46.

TypedQuery query = em.createQuery("SELECT e FROM Employee e", Employee.class);
 
query.setHint(QueryHints.FETCH_GROUP_NAME, "names");

See Also

For more information, see:

• Understanding EclipseLink

• "@FetchAttribute"

• "@FetchGroups"