Skip Headers

Oracle TopLink Developer's Guide 10g Release 3 (10.1.3) B13593-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# Configuring Fetch Groups

By default, when you execute an object-level read query for a particular object class, TopLink returns all the persistent attributes mapped in the object's descriptor. With this single query, all the object's persistent attributes are defined, and calling their `get` methods returns the value directly from the object.

When you are interested in only some of the attributes of an object, it may be more efficient to return only a subset of the object's attributes using a fetch group.

Using a fetch group, you can define a subset of an object's attributes and associate the fetch group with either a `ReadObjectQuery` or `ReadAllQuery` query. When you execute the query, TopLink retrieves only the attributes in the fetch group. TopLink 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 either a `ReadObjectQuery` or `ReadAllQuery` query without specifying a fetch group, TopLink will use the default fetch group, unless you configure the query otherwise (see "Configuring Default Fetch Group Behavior").

Currently, you can use fetch groups only in CMP 2.0 projects for EJB objects. For non-CMP classes, use partial object querying (see "Partial Object Queries").

Before using fetch groups, Oracle recommends 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. For more information about optimizing read performance, see "Read Optimization Examples".

Table 28-38 summarizes which descriptors support fetch group configuration.

Table 28-38 Descriptor Support for Fetch Group Configuration

Descriptor | Using TopLink Workbench | Using Java
--- | --- | ---
Relational Descriptors |  |
Object-Relational Descriptors |  |
EIS Descriptors |  |
XML Descriptors |  |

This section describes how to create a fetch group, store it in a descriptor, and optionally designate a fetch group as the default fetch group for its descriptor reference class.

For more information, see the following:

- "Fetch Groups"

- "Fetch Groups and Object Level Read Queries"

- "Configuring Default Fetch Group Behavior"

## Using Java

To configure a fetch group, use a descriptor amendment method (see "Configuring Amendment Methods") as Example 28-26 shows.

Example 28-26 Configuring a Fetch Group

    //Create a FetchGroupManager for the descriptor
    descriptor.setFetchGroupManager(new FetchGroupManager());
    // Create a FetchGroup
    FetchGroup group = new FetchGroup("nameOnly");
    // Add attributes to FetchGroup. Alternatively, use
    // FetchGroup method addAttributes, passing in a Set of String attribute names
    group.addAttribute("firstName");
    group.addAttribute("lastName");
    // Add the FetchGroup to the FetchGroupManager
    descriptor.getFetchGroupManager().addFetchGroup(group);
    //Set the default fetch group
    descriptor.getFetchGroupManager().setDefaultFetchGroup(group);

Each instance of `FetchGroup` that you store in a descriptor must be configured with a fetch group name that is unique for that descriptor (that is, each descriptor owns a set of named fetch groups).

When configuring fetch groups, note that the primary key fields and other required fields (such as inheritance type and optimistic lock version) are always included in all fetch groups.Fetch groups can include direct and relationship attributes. Including a relationship attribute in a fetch group does not cause the relationship to be joined or instantiated: joining and indirection are set independently of fetch groups.

After you add a fetch group to a descriptor, you can configure a `ReadObjectQuery` or `ReadAllQuery` query with this fetch group by name (`nameOnly`) or rely on TopLink to use this fetch group by default. For more information, see "Using Queries with Fetch Groups".