Module org.eclipse.persistence.core
Package org.eclipse.persistence.queries

Class FetchGroup

java.lang.Object
org.eclipse.persistence.core.queries.CoreAttributeGroup<AttributeItem,ClassDescriptor>
org.eclipse.persistence.queries.AttributeGroup
org.eclipse.persistence.queries.FetchGroup
All Implemented Interfaces:
Serializable, Cloneable
Direct Known Subclasses:
EntityFetchGroup
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.

Since:
TopLink 10.1.3
See Also:

  • Field Details

    • entityFetchGroup

      protected 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 Details

    • FetchGroup

      public FetchGroup()

    • FetchGroup

      public FetchGroup(String name)

  • Method Details

    • onUnfetchedAttribute

      public String onUnfetchedAttribute(FetchGroupTracker entity, String attributeName)
      INTERNAL: Called on attempt to get value of an attribute that hasn't been fetched yet. Returns an error message in case jakarta.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 String onUnfetchedAttributeForSet(FetchGroupTracker entity, String attributeName)
      INTERNAL: Called on attempt to assign value to an attribute that hasn't been fetched yet. Returns an error message in case jakarta.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:

    • setSubclassShouldLoad

      protected void setSubclassShouldLoad(boolean shouldLoad)
      passes should load to subclasses.
      See Also:

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

    • 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(String name, CoreAttributeGroup parent)
      Description copied from class: AttributeGroup
      Subclass may create different types.
      Overrides:
      newGroup in class AttributeGroup

    • isFetchGroup

      public boolean isFetchGroup()
      Overrides:
      isFetchGroup in class CoreAttributeGroup<AttributeItem,ClassDescriptor>

    • isEntityFetchGroup

      public boolean isEntityFetchGroup()

    • toLoadGroupLoadOnly

      public LoadGroup toLoadGroupLoadOnly()

    • clone

      public FetchGroup clone()
      Overrides:
      clone in class AttributeGroup

    • toLoadGroup

      public LoadGroup toLoadGroup(Map<AttributeGroup,LoadGroup> cloneMap, boolean loadOnly)
      Overrides:
      toLoadGroup in class AttributeGroup

    • getEntityFetchGroup

      public EntityFetchGroup getEntityFetchGroup(FetchGroupManager fetchGroupManager)
      INTERNAL: Used to retrieve the EntityFetchGroup for this FetchGroup
      Returns:
      the entityFetchGroup

    • getGroup

      public FetchGroup getGroup(String attributeNameOrPath)
      Returns FetchGroup corresponding to the passed (possibly nested) attribute.
      Overrides:
      getGroup in class AttributeGroup

    • addAttribute

      public void addAttribute(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<AttributeItem,ClassDescriptor>
      Parameters:
      attributeNameOrPath - A simple attribute, array or attributes forming a path
      group - - an AttributeGroup to be added.

    • addAttribute

      public void addAttribute(String attributeNameOrPath, 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<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(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<AttributeItem,ClassDescriptor>
      Parameters:
      attributeNameOrPath - A simple attribute, array or attributes forming a path to a Map key
      group - - an AttributeGroup to be added.