org.eclipse.persistence.queries
Class FetchGroup

java.lang.Object
  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 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.

   See Also:

   FetchGroupManager, QueryHints#FETCH_GROUP, LoadGroup, Serialized Form

   Author:

   King Wang, dclarke, ailitchev

   Since:

   TopLink 10.1.3

   Field Summary

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

   items

   Constructor Summary

   FetchGroup()
   

   FetchGroup(java.lang.String name)
   

   Method Summary

   void	addAttribute(java.lang.String attributeNameOrPath, AttributeGroup 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	addAttribute(java.lang.String attributeNameOrPath, FetchGroup group)
   FetchGroup	clone()
   java.util.Set<java.lang.String>	getAttributes() Deprecated. Use AttributeGroup.getAttributeNames()
   FetchGroup	getGroup(java.lang.String attributeNameOrPath) Returns FetchGroup corresponding to the passed (possibly nested) attribute.
   boolean	isEntityFetchGroup()
   boolean	isFetchGroup()
   protected FetchGroup	newGroup(java.lang.String name, AttributeGroup 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	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	toLoadGroupLoadOnly()

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

   addAttribute, addAttributes, containsAttribute, containsAttributeInternal, convert, equals, getAttributeNames, getItem, getItems, getName, hasItems, isCopyGroup, isLoadGroup, isSupersetOf, newItem, removeAttribute, setAttributeNames, setName, toCopyGroup, toFetchGroup, toLoadGroup, toString, toStringAdditionalInfo, toStringItems, toStringPath

   Methods inherited from class java.lang.Object

   finalize, 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 AttributeGroup.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.

   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.

   newGroup

   protected FetchGroup newGroup(java.lang.String name,
                                 AttributeGroup parent)

   Description copied from class: AttributeGroup

   Subclass may create different types.

   Overrides:

   newGroup in class AttributeGroup

   isFetchGroup

   public boolean isFetchGroup()

   Overrides:

   isFetchGroup in class AttributeGroup

   isEntityFetchGroup

   public boolean isEntityFetchGroup()

   toLoadGroupLoadOnly

   public LoadGroup toLoadGroupLoadOnly()

   clone

   public FetchGroup clone()

   Overrides:

   clone in class AttributeGroup

   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,
                            AttributeGroup group)

   Description copied from class: AttributeGroup

   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 AttributeGroup

   group - - an AttributeGroup to be added.

   addAttribute

   public void addAttribute(java.lang.String attributeNameOrPath,
                            FetchGroup group)