Package org.eclipse.persistence.descriptors

Class FetchGroupManager

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Cloneable
    public class FetchGroupManager
extends java.lang.Object
implements java.lang.Cloneable, java.io.Serializable

    Purpose: The fetch group manager controls the named fetch groups defined at the descriptor level. EclipseLink supports multiple, overlapped fetch groups, optionally with one of them as the default fetch group.

    The domain object must implement org.eclipse.persistence.queries.FetchGroupTracker interface, in order to make use of the fetch group performance enhancement feature.

    Please refer to FetchGroup class for the pros and cons of fetch group usage.

    See Also:
    FetchGroup, FetchGroupTracker, Serialized Form
    Author:
    King Wang, dclarke
    Since:
    TopLink 10.1.3.

    • Constructor Summary

      Constructors 
      Constructor Description
      FetchGroupManager()
      Constructor

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void addFetchGroup​(FetchGroup group)
      Add a named fetch group to the descriptor
      void addMinimalFetchGroup​(FetchGroup fetchGroup)
      INTERNAL: Add primary key and version attributes to the passed fetch group.
      java.lang.Object clone()
      INTERNAL: Clone the fetch group manager.
      void copyAggregateFetchGroupInto​(java.lang.Object source, java.lang.Object target, java.lang.Object rootEntity, org.eclipse.persistence.internal.sessions.AbstractSession session)
      INTERNAL: Copy fetch group reference from the source object to the target
      void copyFetchGroupInto​(java.lang.Object source, java.lang.Object target, org.eclipse.persistence.internal.sessions.AbstractSession session)
      INTERNAL: Copy fetch group reference from the source object to the target
      FetchGroup createDefaultFetchGroup()
      PUBLIC: Returns clone of the default fetch group.
      FetchGroup createFullFetchGroup()
      PUBLIC: Returns clone of the full fetch group - contains all the attributes, no nesting.
      FetchGroup createMinimalFetchGroup()
      PUBLIC: Returns clone of the minimal fetch group.
      org.eclipse.persistence.internal.queries.EntityFetchGroup flatUnionFetchGroups​(FetchGroup first, FetchGroup second, boolean shouldClone)
      INTERNAL: Union two fetch groups as EntityFetchGroups.
      org.eclipse.persistence.internal.queries.EntityFetchGroup getDefaultEntityFetchGroup()
      INTERNAL: Returns EntityFetchGroup corresponding to default FetchGroup.
      FetchGroup getDefaultFetchGroup()
      Return the descriptor-level default fetch group.
      ClassDescriptor getDescriptor()
      PUBLIC: Return the referenced descriptor.
      org.eclipse.persistence.internal.queries.EntityFetchGroup getEntityFetchGroup​(java.util.Set<java.lang.String> attributeNames)
      INTERNAL: Returns entity fetch group corresponding to the passed set of attributes.
      org.eclipse.persistence.internal.queries.EntityFetchGroup getEntityFetchGroup​(FetchGroup fetchGroup)
      INTERNAL: Returns entity fetch group corresponding to the passed fetch group.
      FetchGroup getFetchGroup​(java.lang.String groupName)
      Return a pre-defined named fetch group.
      FetchGroup getFetchGroup​(java.lang.String groupName, boolean useDefault)
      Lookup the FetchGroup to use given a name and a flag taking into consideration descriptor inheritance to ensure parent descriptors are searched for named and default FetchGroup.
      java.util.Map<java.lang.String,​FetchGroup> getFetchGroups()
      Return the fetch group map: keyed by the group name, valued by the fetch group object.
      org.eclipse.persistence.internal.queries.EntityFetchGroup getIdEntityFetchGroup()
      INTERNAL: Returns EntityFetchGroup corresponding to primary key attribute(s).
      org.eclipse.persistence.internal.queries.EntityFetchGroup getNonReferenceEntityFetchGroup()
      INTERNAL: Returns EntityFetchGroup corresponding to non relational attributes intersected with defaultFetchGroup.
      org.eclipse.persistence.internal.queries.EntityFetchGroup getNonReferenceEntityFetchGroup​(boolean addPk, boolean addVersion)
      INTERNAL: Returns EntityFetchGroup corresponding to non relational attributes intersected with defaultFetchGroup.
      org.eclipse.persistence.internal.queries.EntityFetchGroup getObjectEntityFetchGroup​(java.lang.Object domainObject)
      INTERNAL: Return FetchGroup held by the object.
      FetchGroup getObjectFetchGroup​(java.lang.Object domainObject)
      INTERNAL: Return FetchGroup held by the object.
      boolean hasFetchGroup​(java.lang.String groupName)
      Return true if a fetch group exists for the given group name.
      void initialize​(org.eclipse.persistence.internal.sessions.AbstractSession session)
      INTERNAL: Initialize the fetch groups.
      protected void initNonReferenceEntityFetchGroup()  
      boolean isAttributeFetched​(java.lang.Object entity, java.lang.String attributeName)
      Return true if the attribute of the object has already been fetched
      boolean isFullFetchGroup​(FetchGroup fetchGroup)
      PUBLIC: Indicates whether the passed fetch group contains all the attributes, no nesting.
      boolean isMinimalFetchGroup​(FetchGroup fetchGroup)
      PUBLIC: Indicates whether the passed fetch group is minimal.
      boolean isObjectValidForFetchGroup​(java.lang.Object object, FetchGroup fetchGroup)
      INTERNAL: Return if the cached object data is sufficiently valid against a fetch group
      boolean isPartialObject​(java.lang.Object domainObject)
      INTERNAL: Return true if the object is partially fetched and cached.
      void postInitialize​(org.eclipse.persistence.internal.sessions.AbstractSession session)
      INTERNAL: postInitialize called for inheritance children first.
      void prepareAndVerify​(FetchGroup fetchGroup)
      PUBLIC: Add primary key and version attributes to the passed fetch group and all the fetch group it contains.
      protected void prepareAndVerifyInternal​(FetchGroup fetchGroup, java.lang.String attributePrefix)
      INTERNAL: Add primary key and version attributes to the passed fetch group and all the fetch group it contains.
      void reset​(java.lang.Object source)
      INTERNAL: Reset object attributes to the default values.
      void setDefaultFetchGroup​(FetchGroup newDefaultFetchGroup)
      Set the descriptor-level default fetch group.
      void setDescriptor​(ClassDescriptor descriptor)
      Set the referenced descriptor.
      void setObjectFetchGroup​(java.lang.Object source, FetchGroup fetchGroup, org.eclipse.persistence.internal.sessions.AbstractSession session)
      INTERNAL: Set fetch group into the object.
      void setRefreshOnFetchGroupToObject​(java.lang.Object source, boolean shouldRefreshOnFetchgroup)
      INTERNAL: Set if the tracked object is fetched from executing a query with or without refresh.
      void setShouldUseInheritedDefaultFetchGroup​(boolean shouldUseInheritedDefaultFetchGroup)
      PUBLIC: Set whether defaultFetchGroup should be copied from the parent if not set.
      boolean shouldUseInheritedDefaultFetchGroup()
      PUBLIC: Indicates whether defaultFetchGroup should be copied from the parent if not set.
      boolean shouldWriteInto​(java.lang.Object cachedObject, java.lang.Object clone)
      INTERNAL: Return true if the cached object data should be written in clone.
      void unionEntityFetchGroupIntoObject​(java.lang.Object source, org.eclipse.persistence.internal.queries.EntityFetchGroup newEntityFetchGroup, org.eclipse.persistence.internal.sessions.AbstractSession session, boolean shouldClone)
      INTERNAL: Union the fetch group of the domain object with the new fetch group.
      FetchGroup unionFetchGroups​(FetchGroup first, FetchGroup second)
      INTERNAL: Union two fetch groups.
      void writePartialIntoClones​(java.lang.Object partialObject, java.lang.Object workingClone, java.lang.Object backupClone, org.eclipse.persistence.internal.sessions.UnitOfWorkImpl uow)
      INTERNAL: Write data of the partially fetched object into the working and backup clones

      • Methods inherited from class java.lang.Object

        equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Constructor Detail

      • FetchGroupManager

        public FetchGroupManager()
        Constructor

    • Method Detail

      • addFetchGroup

        public void addFetchGroup​(FetchGroup group)
        Add a named fetch group to the descriptor

      • getFetchGroups

        public java.util.Map<java.lang.String,​FetchGroup> getFetchGroups()
        Return the fetch group map: keyed by the group name, valued by the fetch group object.

      • getDefaultFetchGroup

        public FetchGroup getDefaultFetchGroup()
        Return the descriptor-level default fetch group. All read object and read all queries would use the default fetch group if no fetch group is explicitly defined for the query, unless setShouldUseDefaultFetchGroup(false); is also called on the query. Default fetch group should be used carefully. It would be beneficial if most of the system queries are for the subset of the object, so un-needed attributes data would not have to be read, and the users do not have to setup every query for the given fetch group, as default one is always used. However, if queries on object are mostly use case specific and not systematic, using default fetch group could cause undesirable extra round-trip and performance degradation.
        See Also:
        ObjectLevelReadQuery.setShouldUseDefaultFetchGroup(boolean)

      • getDefaultEntityFetchGroup

        public org.eclipse.persistence.internal.queries.EntityFetchGroup getDefaultEntityFetchGroup()
        INTERNAL: Returns EntityFetchGroup corresponding to default FetchGroup.

      • createMinimalFetchGroup

        public FetchGroup createMinimalFetchGroup()
        PUBLIC: Returns clone of the minimal fetch group. Could be used as a starting point for a new user-defined fetch group.

      • isMinimalFetchGroup

        public boolean isMinimalFetchGroup​(FetchGroup fetchGroup)
        PUBLIC: Indicates whether the passed fetch group is minimal.

      • getIdEntityFetchGroup

        public org.eclipse.persistence.internal.queries.EntityFetchGroup getIdEntityFetchGroup()
        INTERNAL: Returns EntityFetchGroup corresponding to primary key attribute(s).

      • getNonReferenceEntityFetchGroup

        public org.eclipse.persistence.internal.queries.EntityFetchGroup getNonReferenceEntityFetchGroup()
        INTERNAL: Returns EntityFetchGroup corresponding to non relational attributes intersected with defaultFetchGroup.

      • getNonReferenceEntityFetchGroup

        public org.eclipse.persistence.internal.queries.EntityFetchGroup getNonReferenceEntityFetchGroup​(boolean addPk,
                                                                                                 boolean addVersion)
        INTERNAL: Returns EntityFetchGroup corresponding to non relational attributes intersected with defaultFetchGroup.

      • addMinimalFetchGroup

        public void addMinimalFetchGroup​(FetchGroup fetchGroup)
        INTERNAL: Add primary key and version attributes to the passed fetch group.

      • prepareAndVerify

        public void prepareAndVerify​(FetchGroup fetchGroup)
        PUBLIC: Add primary key and version attributes to the passed fetch group and all the fetch group it contains. Also verifies that all the attributes have corresponding mappings. Could be used for fetch group preparation and validation. Called by ObjectLevelReadQuery prepareFetchgroup method.

      • prepareAndVerifyInternal

        protected void prepareAndVerifyInternal​(FetchGroup fetchGroup,
                                        java.lang.String attributePrefix)
        INTERNAL: Add primary key and version attributes to the passed fetch group and all the fetch group it contains. Also verifies that all the attributes have corresponding mappings.

      • createDefaultFetchGroup

        public FetchGroup createDefaultFetchGroup()
        PUBLIC: Returns clone of the default fetch group. Could be used as a starting point for a new user-defined fetch group.

      • createFullFetchGroup

        public FetchGroup createFullFetchGroup()
        PUBLIC: Returns clone of the full fetch group - contains all the attributes, no nesting. Could be used as a starting point for a new user-defined fetch group.

      • isFullFetchGroup

        public boolean isFullFetchGroup​(FetchGroup fetchGroup)
        PUBLIC: Indicates whether the passed fetch group contains all the attributes, no nesting.

      • getEntityFetchGroup

        public org.eclipse.persistence.internal.queries.EntityFetchGroup getEntityFetchGroup​(java.util.Set<java.lang.String> attributeNames)
        INTERNAL: Returns entity fetch group corresponding to the passed set of attributes.

      • getEntityFetchGroup

        public org.eclipse.persistence.internal.queries.EntityFetchGroup getEntityFetchGroup​(FetchGroup fetchGroup)
        INTERNAL: Returns entity fetch group corresponding to the passed fetch group.

      • getFetchGroup

        public FetchGroup getFetchGroup​(java.lang.String groupName)
        Return a pre-defined named fetch group. Lookup the FetchGroup to use given a name taking into consideration descriptor inheritance to ensure parent descriptors are searched for named FetchGroups.

      • getFetchGroup

        public FetchGroup getFetchGroup​(java.lang.String groupName,
                                boolean useDefault)
        Lookup the FetchGroup to use given a name and a flag taking into consideration descriptor inheritance to ensure parent descriptors are searched for named and default FetchGroup. This is used to determine the FetchGroup to use in a query's prepare.

      • setDefaultFetchGroup

        public void setDefaultFetchGroup​(FetchGroup newDefaultFetchGroup)
        Set the descriptor-level default fetch group. All read object and read all queries would use the default fetch group if no fetch group is explicitly defined for the query, unless setShouldUseDefaultFetchGroup(false); is also called on the query. Default fetch group should be used carefully. It would be beneficial if most of the system queries are for the subset of the object, so un-needed attributes data would not have to be read, and the users do not have to setup every query for the given fetch group, as default one is always used. However, if queries on object are mostly use case specific and not systematic, using default fetch group could cause undesirable extra round-trip and performance degradation.
        See Also:
        ObjectLevelReadQuery.setShouldUseDefaultFetchGroup(boolean)

      • isPartialObject

        public boolean isPartialObject​(java.lang.Object domainObject)
        INTERNAL: Return true if the object is partially fetched and cached. It applies to the query with fetch group.

      • isObjectValidForFetchGroup

        public boolean isObjectValidForFetchGroup​(java.lang.Object object,
                                          FetchGroup fetchGroup)
        INTERNAL: Return if the cached object data is sufficiently valid against a fetch group

      • shouldWriteInto

        public boolean shouldWriteInto​(java.lang.Object cachedObject,
                               java.lang.Object clone)
        INTERNAL: Return true if the cached object data should be written in clone. It is used in Fetch Group case when filling in the clone from the cached object.

      • writePartialIntoClones

        public void writePartialIntoClones​(java.lang.Object partialObject,
                                   java.lang.Object workingClone,
                                   java.lang.Object backupClone,
                                   org.eclipse.persistence.internal.sessions.UnitOfWorkImpl uow)
        INTERNAL: Write data of the partially fetched object into the working and backup clones

      • copyAggregateFetchGroupInto

        public void copyAggregateFetchGroupInto​(java.lang.Object source,
                                        java.lang.Object target,
                                        java.lang.Object rootEntity,
                                        org.eclipse.persistence.internal.sessions.AbstractSession session)
        INTERNAL: Copy fetch group reference from the source object to the target

      • copyFetchGroupInto

        public void copyFetchGroupInto​(java.lang.Object source,
                               java.lang.Object target,
                               org.eclipse.persistence.internal.sessions.AbstractSession session)
        INTERNAL: Copy fetch group reference from the source object to the target

      • unionEntityFetchGroupIntoObject

        public void unionEntityFetchGroupIntoObject​(java.lang.Object source,
                                            org.eclipse.persistence.internal.queries.EntityFetchGroup newEntityFetchGroup,
                                            org.eclipse.persistence.internal.sessions.AbstractSession session,
                                            boolean shouldClone)
        INTERNAL: Union the fetch group of the domain object with the new fetch group.

      • flatUnionFetchGroups

        public org.eclipse.persistence.internal.queries.EntityFetchGroup flatUnionFetchGroups​(FetchGroup first,
                                                                                      FetchGroup second,
                                                                                      boolean shouldClone)
        INTERNAL: Union two fetch groups as EntityFetchGroups. Ignores all nested attributes.

      • reset

        public void reset​(java.lang.Object source)
        INTERNAL: Reset object attributes to the default values.

      • getObjectFetchGroup

        public FetchGroup getObjectFetchGroup​(java.lang.Object domainObject)
        INTERNAL: Return FetchGroup held by the object.

      • getObjectEntityFetchGroup

        public org.eclipse.persistence.internal.queries.EntityFetchGroup getObjectEntityFetchGroup​(java.lang.Object domainObject)
        INTERNAL: Return FetchGroup held by the object.

      • setObjectFetchGroup

        public void setObjectFetchGroup​(java.lang.Object source,
                                FetchGroup fetchGroup,
                                org.eclipse.persistence.internal.sessions.AbstractSession session)
        INTERNAL: Set fetch group into the object.

      • setRefreshOnFetchGroupToObject

        public void setRefreshOnFetchGroupToObject​(java.lang.Object source,
                                           boolean shouldRefreshOnFetchgroup)
        INTERNAL: Set if the tracked object is fetched from executing a query with or without refresh.

      • isAttributeFetched

        public boolean isAttributeFetched​(java.lang.Object entity,
                                  java.lang.String attributeName)
        Return true if the attribute of the object has already been fetched

      • getDescriptor

        public ClassDescriptor getDescriptor()
        PUBLIC: Return the referenced descriptor.

      • setDescriptor

        public void setDescriptor​(ClassDescriptor descriptor)
        Set the referenced descriptor.

      • hasFetchGroup

        public boolean hasFetchGroup​(java.lang.String groupName)
        Return true if a fetch group exists for the given group name.

      • initialize

        public void initialize​(org.eclipse.persistence.internal.sessions.AbstractSession session)
                throws DescriptorException
        INTERNAL: Initialize the fetch groups. XXX-dclarke: added support for reinit the query manager's queries if they exist
        Throws:
        DescriptorException

      • postInitialize

        public void postInitialize​(org.eclipse.persistence.internal.sessions.AbstractSession session)
                    throws DescriptorException
        INTERNAL: postInitialize called for inheritance children first. That allows to copy defaultFetchGroup from the parent only in case it has been set by user (not automatically generated).
        Throws:
        DescriptorException

      • initNonReferenceEntityFetchGroup

        protected void initNonReferenceEntityFetchGroup()

      • clone

        public java.lang.Object clone()
        INTERNAL: Clone the fetch group manager.
        Overrides:
        clone in class java.lang.Object

      • setShouldUseInheritedDefaultFetchGroup

        public void setShouldUseInheritedDefaultFetchGroup​(boolean shouldUseInheritedDefaultFetchGroup)
        PUBLIC: Set whether defaultFetchGroup should be copied from the parent if not set.

      • shouldUseInheritedDefaultFetchGroup

        public boolean shouldUseInheritedDefaultFetchGroup()
        PUBLIC: Indicates whether defaultFetchGroup should be copied from the parent if not set.