FetchGroupManager (EclipseLink 2.6.0, API Reference)

java.lang.Object
- org.eclipse.persistence.descriptors.FetchGroupManager

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable
```
public class FetchGroupManager
extends java.lang.Object
implements java.lang.Cloneable, java.io.Serializable
```
Purpose: The fetch group manager controls the named fetch groups defined at the descriptor level. EclipseLink supports multiple, overlapped fetch groups, optionally with one of them as the default fetch group.
The domain object must implement org.eclipse.persistence.queries.FetchGroupTracker interface, in order to make use of the fetch group performance enhancement feature.
Please refer to FetchGroup class for the pros and cons of fetch group usage.

See Also:
FetchGroup, FetchGroupTracker, Serialized Form
Author:

King Wang, dclarke

Since:

TopLink 10.1.3.

Constructor Summary

Constructors
Constructor and Description

FetchGroupManager()
Constructor

Constructors
Constructor and Description
`FetchGroupManager()` Constructor

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`addFetchGroup(FetchGroup group)` Add a named fetch group to the descriptor
`void`	`addMinimalFetchGroup(FetchGroup fetchGroup)` INTERNAL: Add primary key and version attributes to the passed fetch group.
`java.lang.Object`	`clone()` INTERNAL: Clone the fetch group manager.
`void`	`copyAggregateFetchGroupInto(java.lang.Object source, java.lang.Object target, java.lang.Object rootEntity, org.eclipse.persistence.internal.sessions.AbstractSession session)` INTERNAL: Copy fetch group reference from the source object to the target
`void`	`copyFetchGroupInto(java.lang.Object source, java.lang.Object target, org.eclipse.persistence.internal.sessions.AbstractSession session)` INTERNAL: Copy fetch group reference from the source object to the target
`FetchGroup`	`createDefaultFetchGroup()` PUBLIC: Returns clone of the default fetch group.
`FetchGroup`	`createFullFetchGroup()` PUBLIC: Returns clone of the full fetch group - contains all the attributes, no nesting.
`FetchGroup`	`createMinimalFetchGroup()` PUBLIC: Returns clone of the minimal fetch group.
`org.eclipse.persistence.internal.queries.EntityFetchGroup`	`flatUnionFetchGroups(FetchGroup first, FetchGroup second, boolean shouldClone)` INTERNAL: Union two fetch groups as EntityFetchGroups.
`org.eclipse.persistence.internal.queries.EntityFetchGroup`	`getDefaultEntityFetchGroup()` INTERNAL: Returns EntityFetchGroup corresponding to default FetchGroup.
`FetchGroup`	`getDefaultFetchGroup()` Return the descriptor-level default fetch group.
`ClassDescriptor`	`getDescriptor()` PUBLIC: Return the referenced descriptor.
`org.eclipse.persistence.internal.queries.EntityFetchGroup`	`getEntityFetchGroup(FetchGroup fetchGroup)` INTERNAL: Returns entity fetch group corresponding to the passed fetch group.
`org.eclipse.persistence.internal.queries.EntityFetchGroup`	`getEntityFetchGroup(java.util.Set<java.lang.String> attributeNames)` INTERNAL: Returns entity fetch group corresponding to the passed set of attributes.
`FetchGroup`	`getFetchGroup(java.lang.String groupName)` Return a pre-defined named fetch group.
`FetchGroup`	`getFetchGroup(java.lang.String groupName, boolean useDefault)` Lookup the FetchGroup to use given a name and a flag taking into consideration descriptor inheritance to ensure parent descriptors are searched for named and default FetchGroup.
`java.util.Map<java.lang.String,FetchGroup>`	`getFetchGroups()` Return the fetch group map: keyed by the group name, valued by the fetch group object.
`org.eclipse.persistence.internal.queries.EntityFetchGroup`	`getIdEntityFetchGroup()` INTERNAL: Returns EntityFetchGroup corresponding to primary key attribute(s).
`org.eclipse.persistence.internal.queries.EntityFetchGroup`	`getNonReferenceEntityFetchGroup()` INTERNAL: Returns EntityFetchGroup corresponding to non relational attributes intersected with defaultFetchGroup.
`org.eclipse.persistence.internal.queries.EntityFetchGroup`	`getNonReferenceEntityFetchGroup(boolean addPk, boolean addVersion)` INTERNAL: Returns EntityFetchGroup corresponding to non relational attributes intersected with defaultFetchGroup.
`org.eclipse.persistence.internal.queries.EntityFetchGroup`	`getObjectEntityFetchGroup(java.lang.Object domainObject)` INTERNAL: Return FetchGroup held by the object.
`FetchGroup`	`getObjectFetchGroup(java.lang.Object domainObject)` INTERNAL: Return FetchGroup held by the object.
`boolean`	`hasFetchGroup(java.lang.String groupName)` Return true if a fetch group exists for the given group name.
`void`	`initialize(org.eclipse.persistence.internal.sessions.AbstractSession session)` INTERNAL: Initialize the fetch groups.
`protected void`	`initNonReferenceEntityFetchGroup()`
`boolean`	`isAttributeFetched(java.lang.Object entity, java.lang.String attributeName)` Return true if the attribute of the object has already been fetched
`boolean`	`isFullFetchGroup(FetchGroup fetchGroup)` PUBLIC: Indicates whether the passed fetch group contains all the attributes, no nesting.
`boolean`	`isMinimalFetchGroup(FetchGroup fetchGroup)` PUBLIC: Indicates whether the passed fetch group is minimal.
`boolean`	`isObjectValidForFetchGroup(java.lang.Object object, FetchGroup fetchGroup)` INTERNAL: Return if the cached object data is sufficiently valid against a fetch group
`boolean`	`isPartialObject(java.lang.Object domainObject)` INTERNAL: Return true if the object is partially fetched and cached.
`void`	`postInitialize(org.eclipse.persistence.internal.sessions.AbstractSession session)` INTERNAL: postInitialize called for inheritance children first.
`void`	`prepareAndVerify(FetchGroup fetchGroup)` PUBLIC: Add primary key and version attributes to the passed fetch group and all the fetch group it contains.
`protected void`	`prepareAndVerifyInternal(FetchGroup fetchGroup, java.lang.String attributePrefix)` INTERNAL: Add primary key and version attributes to the passed fetch group and all the fetch group it contains.
`void`	`reset(java.lang.Object source)` INTERNAL: Reset object attributes to the default values.
`void`	`setDefaultFetchGroup(FetchGroup newDefaultFetchGroup)` Set the descriptor-level default fetch group.
`void`	`setDescriptor(ClassDescriptor descriptor)` Set the referenced descriptor.
`void`	`setObjectFetchGroup(java.lang.Object source, FetchGroup fetchGroup, org.eclipse.persistence.internal.sessions.AbstractSession session)` INTERNAL: Set fetch group into the object.
`void`	`setRefreshOnFetchGroupToObject(java.lang.Object source, boolean shouldRefreshOnFetchgroup)` INTERNAL: Set if the tracked object is fetched from executing a query with or without refresh.
`void`	`setShouldUseInheritedDefaultFetchGroup(boolean shouldUseInheritedDefaultFetchGroup)` PUBLIC: Set whether defaultFetchGroup should be copied from the parent if not set.
`boolean`	`shouldUseInheritedDefaultFetchGroup()` PUBLIC: Indicates whether defaultFetchGroup should be copied from the parent if not set.
`boolean`	`shouldWriteInto(java.lang.Object cachedObject, java.lang.Object clone)` INTERNAL: Return true if the cached object data should be written in clone.
`void`	`unionEntityFetchGroupIntoObject(java.lang.Object source, org.eclipse.persistence.internal.queries.EntityFetchGroup newEntityFetchGroup, org.eclipse.persistence.internal.sessions.AbstractSession session, boolean shouldClone)` INTERNAL: Union the fetch group of the domain object with the new fetch group.
`FetchGroup`	`unionFetchGroups(FetchGroup first, FetchGroup second)` INTERNAL: Union two fetch groups.
`void`	`writePartialIntoClones(java.lang.Object partialObject, java.lang.Object workingClone, java.lang.Object backupClone, org.eclipse.persistence.internal.sessions.UnitOfWorkImpl uow)` INTERNAL: Write data of the partially fetched object into the working and backup clones

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

- Constructor Detail
  - FetchGroupManager
```
public FetchGroupManager()
```
    Constructor
- Method Detail
  - addFetchGroup
```
public void addFetchGroup(FetchGroup group)
```
    Add a named fetch group to the descriptor
  - getFetchGroups
```
public java.util.Map<java.lang.String,FetchGroup> getFetchGroups()
```
    Return the fetch group map: keyed by the group name, valued by the fetch group object.
  - getDefaultFetchGroup
```
public FetchGroup getDefaultFetchGroup()
```
    Return the descriptor-level default fetch group. All read object and read all queries would use the default fetch group if no fetch group is explicitly defined for the query, unless setShouldUseDefaultFetchGroup(false); is also called on the query. Default fetch group should be used carefully. It would be beneficial if most of the system queries are for the subset of the object, so un-needed attributes data would not have to be read, and the users do not have to setup every query for the given fetch group, as default one is always used. However, if queries on object are mostly use case specific and not systematic, using default fetch group could cause undesirable extra round-trip and performance degradation.
    
    See Also:
    ObjectLevelReadQuery.setShouldUseDefaultFetchGroup(boolean)
  - getDefaultEntityFetchGroup
```
public org.eclipse.persistence.internal.queries.EntityFetchGroup getDefaultEntityFetchGroup()
```
    INTERNAL: Returns EntityFetchGroup corresponding to default FetchGroup.
  - createMinimalFetchGroup
```
public FetchGroup createMinimalFetchGroup()
```
    PUBLIC: Returns clone of the minimal fetch group. Could be used as a starting point for a new user-defined fetch group.
  - isMinimalFetchGroup
```
public boolean isMinimalFetchGroup(FetchGroup fetchGroup)
```
    PUBLIC: Indicates whether the passed fetch group is minimal.
  - getIdEntityFetchGroup
```
public org.eclipse.persistence.internal.queries.EntityFetchGroup getIdEntityFetchGroup()
```
    INTERNAL: Returns EntityFetchGroup corresponding to primary key attribute(s).
  - getNonReferenceEntityFetchGroup
```
public org.eclipse.persistence.internal.queries.EntityFetchGroup getNonReferenceEntityFetchGroup()
```
    INTERNAL: Returns EntityFetchGroup corresponding to non relational attributes intersected with defaultFetchGroup.
  - getNonReferenceEntityFetchGroup
```
public org.eclipse.persistence.internal.queries.EntityFetchGroup getNonReferenceEntityFetchGroup(boolean addPk,
                                                                                        boolean addVersion)
```
    INTERNAL: Returns EntityFetchGroup corresponding to non relational attributes intersected with defaultFetchGroup.
  - addMinimalFetchGroup
```
public void addMinimalFetchGroup(FetchGroup fetchGroup)
```
    INTERNAL: Add primary key and version attributes to the passed fetch group.
  - prepareAndVerify
```
public void prepareAndVerify(FetchGroup fetchGroup)
```
    PUBLIC: Add primary key and version attributes to the passed fetch group and all the fetch group it contains. Also verifies that all the attributes have corresponding mappings. Could be used for fetch group preparation and validation. Called by ObjectLevelReadQuery prepareFetchgroup method.
  - prepareAndVerifyInternal
```
protected void prepareAndVerifyInternal(FetchGroup fetchGroup,
                            java.lang.String attributePrefix)
```
    INTERNAL: Add primary key and version attributes to the passed fetch group and all the fetch group it contains. Also verifies that all the attributes have corresponding mappings.
  - createDefaultFetchGroup
```
public FetchGroup createDefaultFetchGroup()
```
    PUBLIC: Returns clone of the default fetch group. Could be used as a starting point for a new user-defined fetch group.
  - createFullFetchGroup
```
public FetchGroup createFullFetchGroup()
```
    PUBLIC: Returns clone of the full fetch group - contains all the attributes, no nesting. Could be used as a starting point for a new user-defined fetch group.
  - isFullFetchGroup
```
public boolean isFullFetchGroup(FetchGroup fetchGroup)
```
    PUBLIC: Indicates whether the passed fetch group contains all the attributes, no nesting.
  - getEntityFetchGroup
```
public org.eclipse.persistence.internal.queries.EntityFetchGroup getEntityFetchGroup(java.util.Set<java.lang.String> attributeNames)
```
    INTERNAL: Returns entity fetch group corresponding to the passed set of attributes.
  - getEntityFetchGroup
```
public org.eclipse.persistence.internal.queries.EntityFetchGroup getEntityFetchGroup(FetchGroup fetchGroup)
```
    INTERNAL: Returns entity fetch group corresponding to the passed fetch group.
  - getFetchGroup
```
public FetchGroup getFetchGroup(java.lang.String groupName)
```
    Return a pre-defined named fetch group. Lookup the FetchGroup to use given a name taking into consideration descriptor inheritance to ensure parent descriptors are searched for named FetchGroups.
  - getFetchGroup
```
public FetchGroup getFetchGroup(java.lang.String groupName,
                       boolean useDefault)
```
    Lookup the FetchGroup to use given a name and a flag taking into consideration descriptor inheritance to ensure parent descriptors are searched for named and default FetchGroup. This is used to determine the FetchGroup to use in a query's prepare.
  - setDefaultFetchGroup
```
public void setDefaultFetchGroup(FetchGroup newDefaultFetchGroup)
```
    Set the descriptor-level default fetch group. All read object and read all queries would use the default fetch group if no fetch group is explicitly defined for the query, unless setShouldUseDefaultFetchGroup(false); is also called on the query. Default fetch group should be used carefully. It would be beneficial if most of the system queries are for the subset of the object, so un-needed attributes data would not have to be read, and the users do not have to setup every query for the given fetch group, as default one is always used. However, if queries on object are mostly use case specific and not systematic, using default fetch group could cause undesirable extra round-trip and performance degradation.
    
    See Also:
    ObjectLevelReadQuery.setShouldUseDefaultFetchGroup(boolean)
  - isPartialObject
```
public boolean isPartialObject(java.lang.Object domainObject)
```
    INTERNAL: Return true if the object is partially fetched and cached. It applies to the query with fetch group.
  - isObjectValidForFetchGroup
```
public boolean isObjectValidForFetchGroup(java.lang.Object object,
                                 FetchGroup fetchGroup)
```
    INTERNAL: Return if the cached object data is sufficiently valid against a fetch group
  - shouldWriteInto
```
public boolean shouldWriteInto(java.lang.Object cachedObject,
                      java.lang.Object clone)
```
    INTERNAL: Return true if the cached object data should be written in clone. It is used in Fetch Group case when filling in the clone from the cached object.
  - writePartialIntoClones
```
public void writePartialIntoClones(java.lang.Object partialObject,
                          java.lang.Object workingClone,
                          java.lang.Object backupClone,
                          org.eclipse.persistence.internal.sessions.UnitOfWorkImpl uow)
```
    INTERNAL: Write data of the partially fetched object into the working and backup clones
  - copyAggregateFetchGroupInto
```
public void copyAggregateFetchGroupInto(java.lang.Object source,
                               java.lang.Object target,
                               java.lang.Object rootEntity,
                               org.eclipse.persistence.internal.sessions.AbstractSession session)
```
    INTERNAL: Copy fetch group reference from the source object to the target
  - copyFetchGroupInto
```
public void copyFetchGroupInto(java.lang.Object source,
                      java.lang.Object target,
                      org.eclipse.persistence.internal.sessions.AbstractSession session)
```
    INTERNAL: Copy fetch group reference from the source object to the target
  - unionEntityFetchGroupIntoObject
```
public void unionEntityFetchGroupIntoObject(java.lang.Object source,
                                   org.eclipse.persistence.internal.queries.EntityFetchGroup newEntityFetchGroup,
                                   org.eclipse.persistence.internal.sessions.AbstractSession session,
                                   boolean shouldClone)
```
    INTERNAL: Union the fetch group of the domain object with the new fetch group.
  - unionFetchGroups
```
public FetchGroup unionFetchGroups(FetchGroup first,
                          FetchGroup second)
```
    INTERNAL: Union two fetch groups.
  - flatUnionFetchGroups
```
public org.eclipse.persistence.internal.queries.EntityFetchGroup flatUnionFetchGroups(FetchGroup first,
                                                                             FetchGroup second,
                                                                             boolean shouldClone)
```
    INTERNAL: Union two fetch groups as EntityFetchGroups. Ignores all nested attributes.
  - reset
```
public void reset(java.lang.Object source)
```
    INTERNAL: Reset object attributes to the default values.
  - getObjectFetchGroup
```
public FetchGroup getObjectFetchGroup(java.lang.Object domainObject)
```
    INTERNAL: Return FetchGroup held by the object.
  - getObjectEntityFetchGroup
```
public org.eclipse.persistence.internal.queries.EntityFetchGroup getObjectEntityFetchGroup(java.lang.Object domainObject)
```
    INTERNAL: Return FetchGroup held by the object.
  - setObjectFetchGroup
```
public void setObjectFetchGroup(java.lang.Object source,
                       FetchGroup fetchGroup,
                       org.eclipse.persistence.internal.sessions.AbstractSession session)
```
    INTERNAL: Set fetch group into the object.
  - setRefreshOnFetchGroupToObject
```
public void setRefreshOnFetchGroupToObject(java.lang.Object source,
                                  boolean shouldRefreshOnFetchgroup)
```
    INTERNAL: Set if the tracked object is fetched from executing a query with or without refresh.
  - isAttributeFetched
```
public boolean isAttributeFetched(java.lang.Object entity,
                         java.lang.String attributeName)
```
    Return true if the attribute of the object has already been fetched
  - getDescriptor
```
public ClassDescriptor getDescriptor()
```
    PUBLIC: Return the referenced descriptor.
  - setDescriptor
```
public void setDescriptor(ClassDescriptor descriptor)
```
    Set the referenced descriptor.
  - hasFetchGroup
```
public boolean hasFetchGroup(java.lang.String groupName)
```
    Return true if a fetch group exists for the given group name.
  - initialize
```
public void initialize(org.eclipse.persistence.internal.sessions.AbstractSession session)
                throws DescriptorException
```
    INTERNAL: Initialize the fetch groups. XXX-dclarke: added support for reinit the query manager's queries if they exist
    
    Throws:
    
    DescriptorException
  - postInitialize
```
public void postInitialize(org.eclipse.persistence.internal.sessions.AbstractSession session)
                    throws DescriptorException
```
    INTERNAL: postInitialize called for inheritance children first. That allows to copy defaultFetchGroup from the parent only in case it has been set by user (not automatically generated).
    
    Throws:
    
    DescriptorException
  - initNonReferenceEntityFetchGroup
```
protected void initNonReferenceEntityFetchGroup()
```
  - clone
```
public java.lang.Object clone()
```
    INTERNAL: Clone the fetch group manager.
    
    Overrides:
    
    clone in class java.lang.Object
  - setShouldUseInheritedDefaultFetchGroup
```
public void setShouldUseInheritedDefaultFetchGroup(boolean shouldUseInheritedDefaultFetchGroup)
```
    PUBLIC: Set whether defaultFetchGroup should be copied from the parent if not set.
  - shouldUseInheritedDefaultFetchGroup
```
public boolean shouldUseInheritedDefaultFetchGroup()
```
    PUBLIC: Indicates whether defaultFetchGroup should be copied from the parent if not set.

Class FetchGroupManager

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

FetchGroupManager

Method Detail

addFetchGroup

getFetchGroups

getDefaultFetchGroup

getDefaultEntityFetchGroup

createMinimalFetchGroup

isMinimalFetchGroup

getIdEntityFetchGroup

getNonReferenceEntityFetchGroup

getNonReferenceEntityFetchGroup

addMinimalFetchGroup

prepareAndVerify

prepareAndVerifyInternal

createDefaultFetchGroup

createFullFetchGroup

isFullFetchGroup

getEntityFetchGroup

getEntityFetchGroup

getFetchGroup

getFetchGroup

setDefaultFetchGroup

isPartialObject

isObjectValidForFetchGroup

shouldWriteInto

writePartialIntoClones

copyAggregateFetchGroupInto

copyFetchGroupInto

unionEntityFetchGroupIntoObject

unionFetchGroups

flatUnionFetchGroups

reset

getObjectFetchGroup

getObjectEntityFetchGroup

setObjectFetchGroup

setRefreshOnFetchGroupToObject

isAttributeFetched

getDescriptor

setDescriptor

hasFetchGroup

initialize

postInitialize

initNonReferenceEntityFetchGroup

clone

setShouldUseInheritedDefaultFetchGroup

shouldUseInheritedDefaultFetchGroup