EclipseLink 2.3.2, build 'v20111125-r10461' API Reference

org.eclipse.persistence.queries
Class FetchGroup

java.lang.Object
  extended by org.eclipse.persistence.queries.AttributeGroup
      extended by 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:

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)

    EclipseLink 2.3.2, build 'v20111125-r10461' API Reference