Jump to: navigation, search

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


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


Default FetchGroup


DescriptorCustomizer Example

FetchGroup phoneFG = new FetchGroup();
ClassDescriptor phoneDescriptor = session.getClassDescriptor(PhoneNumber.class);

Named FetchGroup


Annotation Example


EclipseLink ORM XML Example


Descriptor Customizer Example




Named FetchGroup Example

query.setParameter("ID", Queries.minimumEmployeeId(em));
query.setHint(QueryHints.FETCH_GROUP_NAME, "test");

Dynamic FetchGroup Example

query.setParameter("GENDER", Gender.Male);
// Define the fields to be fetched on Employee
FetchGroup fg = new FetchGroup();
// Configure the dynamic FetchGroup
query.setHint(QueryHints.FETCH_GROUP, fg);
List<Employee> emps = query.getResultList();



Query Execution

Detached Entities