FetchGroup (EclipseLink 2.6.5, API Reference)

java.lang.Object
- org.eclipse.persistence.core.queries.CoreAttributeGroup<org.eclipse.persistence.internal.queries.AttributeItem,ClassDescriptor>
- - org.eclipse.persistence.queries.AttributeGroup
  - - org.eclipse.persistence.queries.FetchGroup

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable
```
public class FetchGroup
extends AttributeGroup
```
A FetchGroup is a performance enhancement that allows a group of attributes of an object to be loaded on demand, which 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. It avoids loading all data of the object's attributes, in which the user is interested in only a subset of them. A great deal of caution and careful system use case analysis should be use when using the fetch group feature, as the extra round-trip would well offset the gain from the deferred loading in many cases.
FetchGroup usage is only possible when an entity class implements the FetchGroupTracker interface so that the FetchGroup can be stored in the entity. The entity must also use the provided check methods to ensure the attributes are loaded prior to use. In general this support is enabled through weaving of the entity classes. If an entity class does not implement FetchGroupTracker no FetchGroup functionality will be supported and attempted use of a FetchGroup in a query will not result in the expected behavior.
FetchGroups are defined in 3 ways:
- A FetchGroupManager.getDefaultFetchGroup() is created and stored on the FetchGroupManager during metadata processing if any of the basic (DirectToFieldMapping) are configured to be loaded directly.
- A named FetchGroup can be defined and added to the FetchGroupManager. For JPA users this can be accomplished using annotation (@FetchGroup) or in an eclipselink-orm.xml. For JPA and native users named groups can be defined in code and added to the FetchGroupManager.addFetchGroup(FetchGroup). Adding named groups in code is typically done in a DescriptorCustomizerand should be done before the session is initialized at login. To use a named FetchGroup on a query the native ObjectLevelReadQuery.setFetchGroupName(String) can be used of for JPA users the QueryHints.FETCH_GROUP_NAME an be used.
- A dynamic FetchGroup can be created within the application and used on a query. For native API usage this is done using ObjectLevelReadQuery.setFetchGroup(FetchGroup) while JPA users generally use the QueryHints.FETCH_GROUP.
When a query is executed only one FetchGroup will be used. The order of precedence is:
1. If a FetchGroup is specified on a query it will be used.
2. If no FetchGroup is specified but a FetchGroup name is specified and the FetchGroupManager has a group by this name it will be used.
3. If neither a FetchGroup nor a FetchGroup name is specified on the query an the FetchGroupManager has a default group then it will be used.
4. If none of these conditions are met then no FetchGroup will be used when executing a query.
Note: This includes the execution of queries to populate lazy and eager relationships.
Loading: A FetchGroup can optionally specify that it needs its included relationships loaded. This can be done using setShouldLoad(boolean) and setShouldLoadAll(boolean) as well as the corresponding configurations in the @FetchGroup annotation and the <fetch-group> element in the eclipselink-orm.xml. When this is configured the FetchGroup will also function as a LoadGroup causing all of its specified relationships to be populated prior to returning the results from the query execution.
See Also:
FetchGroupManager, QueryHints.FETCH_GROUP, LoadGroup, Serialized Form
Author:

King Wang, dclarke, ailitchev

Since:

TopLink 10.1.3

Field Summary

Fields
Modifier and Type	Field and Description
`protected org.eclipse.persistence.internal.queries.EntityFetchGroup`	`entityFetchGroup` Caches the EntityFetch group for this FetchGroup
`protected FetchGroupTracker`	`rootEntity` Stores a reference to the root entity for an Aggregate Object relationship.

Fields inherited from class org.eclipse.persistence.core.queries.CoreAttributeGroup
allsubclasses, isValidated, items, name, subClasses, superClassGroup, type, typeName

Constructor Summary

Constructors
Constructor and Description

FetchGroup()

FetchGroup(java.lang.String name)

Constructors
Constructor and Description
`FetchGroup()`
`FetchGroup(java.lang.String name)`

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`addAttribute(java.lang.String attributeNameOrPath, java.util.Collection<? extends CoreAttributeGroup> groups)` Add an attribute and the corresponding list of AttributeGroups.
`void`	`addAttribute(java.lang.String attributeNameOrPath, CoreAttributeGroup group)` Add a basic attribute or nested attribute with each String representing an attribute on the path to what needs to be included in the AttributeGroup.
`void`	`addAttributeKey(java.lang.String attributeNameOrPath, CoreAttributeGroup group)` Add a basic attribute or nested attribute with each String representing the key of an attribute of type Map on the path to what needs to be included in the AttributeGroup.
`FetchGroup`	`clone()`
`java.util.Set<java.lang.String>`	`getAttributes()` Deprecated. Use `CoreAttributeGroup.getAttributeNames()`
`org.eclipse.persistence.internal.queries.EntityFetchGroup`	`getEntityFetchGroup(FetchGroupManager fetchGroupManager)` INTERNAL: Used to retrieve the EntityFetchGroup for this FetchGroup
`FetchGroup`	`getGroup(java.lang.String attributeNameOrPath)` Returns FetchGroup corresponding to the passed (possibly nested) attribute.
`FetchGroupTracker`	`getRootEntity()` INTERNAL:
`boolean`	`isEntityFetchGroup()`
`boolean`	`isFetchGroup()`
`protected FetchGroup`	`newGroup(java.lang.String name, CoreAttributeGroup parent)` Subclass may create different types.
`java.lang.String`	`onUnfetchedAttribute(FetchGroupTracker entity, java.lang.String attributeName)` INTERNAL: Called on attempt to get value of an attribute that hasn't been fetched yet.
`java.lang.String`	`onUnfetchedAttributeForSet(FetchGroupTracker entity, java.lang.String attributeName)` INTERNAL: Called on attempt to assign value to an attribute that hasn't been fetched yet.
`void`	`setRootEntity(FetchGroupTracker rootEntity)` INTERNAL:
`void`	`setShouldLoad(boolean shouldLoad)` Configure this group to also act as a `LoadGroup` when set to true and load all of the specified relationships so that the entities returned from the query where this group was used have the requested relationships populated.
`void`	`setShouldLoadAll(boolean shouldLoad)` Configure this group to also act as a `LoadGroup` the same as `setShouldLoad(boolean)`.
`protected void`	`setSubclassShouldLoad(boolean shouldLoad)` passes should load to subclasses.
`boolean`	`shouldLoad()`
`LoadGroup`	`toLoadGroup(java.util.Map<AttributeGroup,LoadGroup> cloneMap, boolean loadOnly)`
`LoadGroup`	`toLoadGroupLoadOnly()`

Methods inherited from class org.eclipse.persistence.queries.AttributeGroup
addAttribute, findGroup, getItem, isConcurrent, isCopyGroup, isLoadGroup, isSupersetOf, newItem, newItem, toCopyGroup, toCopyGroup, toFetchGroup, toFetchGroup, toLoadGroup

Methods inherited from class org.eclipse.persistence.core.queries.CoreAttributeGroup
addAttribute, addAttributes, clone, containsAttribute, containsAttributeInternal, convert, convertClassNamesToClasses, equals, getAllItems, getAttributeNames, getItem, getItems, getName, getSubClassGroups, getType, getTypeName, hasInheritance, hasItems, insertSubClass, isSupersetOf, isValidated, removeAttribute, setAllSubclasses, setAttributeNames, setName, toString, toStringAdditionalInfo, toStringItems, toStringPath

Methods inherited from class java.lang.Object
finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - entityFetchGroup
```
protected org.eclipse.persistence.internal.queries.EntityFetchGroup entityFetchGroup
```
    Caches the EntityFetch group for this FetchGroup
  - rootEntity
```
protected FetchGroupTracker rootEntity
```
    Stores a reference to the root entity for an Aggregate Object relationship. This ensures that partially loaded aggregates can be triggered.
- Constructor Detail
  - FetchGroup
```
public FetchGroup()
```
  - FetchGroup
```
public FetchGroup(java.lang.String name)
```
- Method Detail
  - getAttributes
```
@Deprecated
public java.util.Set<java.lang.String> getAttributes()
```
    Deprecated. Use CoreAttributeGroup.getAttributeNames()
    
    Return the attribute names on the current FetchGroup. This does not include the attributes on nested FetchGroups
  - onUnfetchedAttribute
```
public java.lang.String onUnfetchedAttribute(FetchGroupTracker entity,
                                    java.lang.String attributeName)
```
    INTERNAL: Called on attempt to get value of an attribute that hasn't been fetched yet. Returns an error message in case javax.persistence.EntityNotFoundException should be thrown by the calling method, null otherwise.
    This method is typically only invoked through woven code in the persistence object introduced when FetchGroupTracker is woven into the entity.
  - onUnfetchedAttributeForSet
```
public java.lang.String onUnfetchedAttributeForSet(FetchGroupTracker entity,
                                          java.lang.String attributeName)
```
    INTERNAL: Called on attempt to assign value to an attribute that hasn't been fetched yet. Returns an error message in case javax.persistence.EntityNotFoundException should be thrown by the calling method, null otherwise.
    This method is typically only invoked through woven code in the persistence object introduced when FetchGroupTracker is woven into the entity.
  - getRootEntity
```
public FetchGroupTracker getRootEntity()
```
    INTERNAL:
    
    Returns:
    the rootEntity
  - setRootEntity
```
public void setRootEntity(FetchGroupTracker rootEntity)
```
    INTERNAL:
    
    Parameters:
    rootEntity - the rootEntity to set
  - setShouldLoad
```
public void setShouldLoad(boolean shouldLoad)
```
    Configure this group to also act as a LoadGroup when set to true and load all of the specified relationships so that the entities returned from the query where this group was used have the requested relationships populated. All subsequent attributes added to this group that create a nested group will have this value applied to them.
    
    See Also:
    to configure {@link #shouldLoad()} on nested groups
  - setSubclassShouldLoad
```
protected void setSubclassShouldLoad(boolean shouldLoad)
```
    passes should load to subclasses.
    
    See Also:
    to configure {@link #shouldLoad()} on nested groups
  - setShouldLoadAll
```
public void setShouldLoadAll(boolean shouldLoad)
```
    Configure this group to also act as a LoadGroup the same as setShouldLoad(boolean). Additionally this method will apply the provided boolean value to all nested groups already added.
    
    See Also:
    to only configure this grup without effecting existing nested groups.
  - shouldLoad
```
public boolean shouldLoad()
```
    Returns:
    true if this group will be used as a LoadGroupwhen processing the results of a query to force the specified relationships to be loaded.
  - newGroup
```
protected FetchGroup newGroup(java.lang.String name,
                  CoreAttributeGroup parent)
```
    Description copied from class: AttributeGroup
    
    Subclass may create different types.
    
    Overrides:
    
    newGroup in class AttributeGroup
  - isFetchGroup
```
public boolean isFetchGroup()
```
    Overrides:
    
    isFetchGroup in class CoreAttributeGroup<org.eclipse.persistence.internal.queries.AttributeItem,ClassDescriptor>
  - isEntityFetchGroup
```
public boolean isEntityFetchGroup()
```
  - toLoadGroupLoadOnly
```
public LoadGroup toLoadGroupLoadOnly()
```
  - clone
```
public FetchGroup clone()
```
    Overrides:
    
    clone in class AttributeGroup
  - toLoadGroup
```
public LoadGroup toLoadGroup(java.util.Map<AttributeGroup,LoadGroup> cloneMap,
                    boolean loadOnly)
```
    Overrides:
    
    toLoadGroup in class AttributeGroup
  - getEntityFetchGroup
```
public org.eclipse.persistence.internal.queries.EntityFetchGroup getEntityFetchGroup(FetchGroupManager fetchGroupManager)
```
    INTERNAL: Used to retrieve the EntityFetchGroup for this FetchGroup
    
    Returns:
    the entityFetchGroup
  - getGroup
```
public FetchGroup getGroup(java.lang.String attributeNameOrPath)
```
    Returns FetchGroup corresponding to the passed (possibly nested) attribute.
    
    Overrides:
    
    getGroup in class AttributeGroup
  - addAttribute
```
public void addAttribute(java.lang.String attributeNameOrPath,
                CoreAttributeGroup group)
```
    Description copied from class: CoreAttributeGroup
    
    Add a basic attribute or nested attribute with each String representing an attribute on the path to what needs to be included in the AttributeGroup.
    Example: group.addAttribute("firstName", group1); group.addAttribute("manager.address", group2); Note that existing group corresponding to attributeNameOrPath will be overridden with the passed group.
    
    Overrides:
    
    addAttribute in class CoreAttributeGroup<org.eclipse.persistence.internal.queries.AttributeItem,ClassDescriptor>
    
    Parameters:
    attributeNameOrPath - A simple attribute, array or attributes forming a path
    group - - an AttributeGroup to be added.
  - addAttribute
```
public void addAttribute(java.lang.String attributeNameOrPath,
                java.util.Collection<? extends CoreAttributeGroup> groups)
```
    Description copied from class: CoreAttributeGroup
    
    Add an attribute and the corresponding list of AttributeGroups. Multiple groups are added in the case of inheritance
    
    Overrides:
    
    addAttribute in class CoreAttributeGroup<org.eclipse.persistence.internal.queries.AttributeItem,ClassDescriptor>
    
    Parameters:
    attributeNameOrPath - A simple attribute, array or attributes forming a path
    groups - - a collection of AttributeGroups to be added.
  - addAttributeKey
```
public void addAttributeKey(java.lang.String attributeNameOrPath,
                   CoreAttributeGroup group)
```
    Description copied from class: CoreAttributeGroup
    
    Add a basic attribute or nested attribute with each String representing the key of an attribute of type Map on the path to what needs to be included in the AttributeGroup.
    Example: group.addAttribute("firstName", group1); group.addAttribute("manager.address", group2); Note that existing group corresponding to attributeNameOrPath will be overridden with the passed group.
    
    Overrides:
    
    addAttributeKey in class CoreAttributeGroup<org.eclipse.persistence.internal.queries.AttributeItem,ClassDescriptor>
    
    Parameters:
    attributeNameOrPath - A simple attribute, array or attributes forming a path to a Map key
    group - - an AttributeGroup to be added.

Class FetchGroup

Field Summary

Fields inherited from class org.eclipse.persistence.core.queries.CoreAttributeGroup

Constructor Summary

Method Summary

Methods inherited from class org.eclipse.persistence.queries.AttributeGroup

Methods inherited from class org.eclipse.persistence.core.queries.CoreAttributeGroup

Methods inherited from class java.lang.Object

Field Detail

entityFetchGroup

rootEntity

Constructor Detail

FetchGroup

FetchGroup

Method Detail

getAttributes

onUnfetchedAttribute

onUnfetchedAttributeForSet

getRootEntity

setRootEntity

setShouldLoad

setSubclassShouldLoad

setShouldLoadAll

shouldLoad

newGroup

isFetchGroup

isEntityFetchGroup

toLoadGroupLoadOnly

clone

toLoadGroup

getEntityFetchGroup

getGroup

addAttribute

addAttribute

addAttributeKey