org.eclipse.persistence.queries

Class FetchGroup

java.lang.Object

org.eclipse.persistence.core.queries.CoreAttributeGroup<org.eclipse.persistence.internal.queries.AttributeItem>

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 si configured the FetchGroup will also function as a LoadGroup causing all of its specified relationships to be populated prior to returning the results form the query execution.

Since:

TopLink 10.1.3

Author:

King Wang, dclarke, ailitchev

See Also:

FetchGroupManager, QueryHints#FETCH_GROUP, LoadGroup, Serialized Form

Constructor Summary

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()
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).
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, toCopyGroup, toCopyGroup, toFetchGroup, toFetchGroup, toLoadGroup

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

addAttribute, addAttributes, clone, containsAttribute, containsAttributeInternal, convertClassNamesToClasses, equals, getAllItems, getAttributeNames, getItems, getName, getSubClassGroups, getType, getTypeName, hasInheritance, hasItems, insertSubClass, isSupersetOf, isValidated, removeAttribute, setAllSubclasses, setAttributeNames, setName, toString

Methods inherited from class java.lang.Object

getClass, hashCode, notify, notifyAll, wait, wait, wait

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

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.

isFetchGroup

public boolean isFetchGroup()

Overrides:

isFetchGroup in class CoreAttributeGroup<org.eclipse.persistence.internal.queries.AttributeItem>

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>

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>

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>

group - - an AttributeGroup to be added.