EclipseLink/Development/2.1/AdvancedJPA Queries/FetchGroup

EclipseLink 2.1: Enhanced FetchGroup Support

This feature will make major enhancements to EclipseLink's existing FetchGroup support to extends its use beyond lazy loading of basics to encompass full graph definition and usage with queries (including find), detach/copy, and merge.

Related Bugs

• bug 244124: Add Nested FetchGroup support

Requirements

This feature will enhance FetchGroup to address the following requirements:

The enhancement to FetchGroup support will include addressing the following requirements:

1. Support defining FetchGroups that define what should be loaded including basic, embedded attributes, and relationships
   • Default FetchGroup for an entity type is defined based on the fetch (lazy loading) configuration of the attributes. For default FetchGroup only the attributes on the entity class itself and those available through inheritance are included.
   • Named FetchGroup can be defined using Annotations (@FetchGroup), eclipselink-orm.xml, and API (typically in customizer). Only one named FetchGroup of a given name can exist for an entity type. Note: They can be overridden in inheritance hierarchies using the same name.
   • Dynamic FetchGroup can be specified to override
2. FetchGroup can be used on any object-level query (ReadAllQuery, ObjectLevelReadQuery, JPA find)
   • If a FetchGroup is specified on a query directly or through the application of a JPA query hint it will be used and applied to the query result
   • If no FetchGroup is specified but a FetchGroup name is configured, either directly or through JAP query hint, then the named FetchGroup will be looked up through the descriptor and its parents hierarchy during query prepare and used if found. If not found an exception should be thrown
   • If no FetchGroup of FetchGroup name is specified on a query then the default FetchGroup looked up through the entity type's descriptor hierarchy will be used.
   • The FetchGroup specified, looked up by name, or looked up as default should not be cached in the query except during actual execution. This will allow FetchGroupManager changes to default and named FetchGroup to be used on subsequent query executions.
3. FetchGroup can be used to detach/copy and entity or collection of entities
   • JpaHelper.copy(Object entity, FetchGroup fetchGroup)
   • detached entities with a FetchGroup will have a special DetachedFetchGroup attached that extends its definition based on state changes made to the Entity.
     • An exception will be thrown if a DetachedFetchGroup is on an entity and an unfetched attribute is attempted to be fetched.
4. FetchGroup can be used to merge entities
   • If a FetchGroup exists on an entity (FetchGroupTarcker._persistence_getFetchGroup) being merged in EntityManager.merge or UnitOfWork.merge then only the attributes specified in the FetchGroup will be merged.

Usage Examples

Configuration

Default FetchGroup

The default FetchGroup is determined through the use of fetch=LAZY on basic mappings. There is no support for relationships in default the default FetchGroup unless the default FetchGroup is manually configured on an entity type's descriptor using API (DescritporCustomizer).

DescriptorCustomizer Example

FetchGroup phoneFG = new FetchGroup();
phoneFG.addAttribute("number");
ClassDescriptor phoneDescriptor = session.getClassDescriptor(PhoneNumber.class);
phoneDescriptor.getFetchGroupManager().setDefaultFetchGroup(phoneFG);

Named FetchGroup

A named FetchGroup can be configured through annotations or API (DecsriptorCustomizer). This feature includes extensions to the @FetchGroup annotation and eclipselink-orm.xml to support defining FetchGroup items for relationships.

Annotation Example

EclipseLink ORM XML Example

Descriptor Customizer Example

Querying

A FetchGroup is used in the processing of a query when a default FetchGroup exists on the entity type's descriptor or one is specified on the query.

Named FetchGroup Example

Dynamic FetchGroup Example