Package org.eclipse.persistence.queries

Class 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 <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 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 on nested groups

      • setSubclassShouldLoad

        protected void setSubclassShouldLoad​(boolean shouldLoad)
        passes should load to subclasses.
        See Also:
        to configure on 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.

      • isEntityFetchGroup

        public boolean isEntityFetchGroup()

      • toLoadGroupLoadOnly

        public LoadGroup toLoadGroupLoadOnly()

      • 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.