EclipseLink 1.1.4, build 'v20100812-r7860' API Reference

org.eclipse.persistence.descriptors
Class FetchGroupManager

java.lang.Object
  extended by org.eclipse.persistence.descriptors.FetchGroupManager
All Implemented Interfaces:
java.lang.Cloneable

public class FetchGroupManager
extends java.lang.Object
implements java.lang.Cloneable

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
Author:
King Wang
Since:
TopLink 10.1.3.

Constructor Summary
FetchGroupManager()
          Constructor
 
Method Summary
 void addFetchGroup(FetchGroup group)
          Add a named fetch group to the descriptor
 java.lang.Object clone()
          INTERNAL: Clone the fetch group manager.
 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
 ClassDescriptor getClassDescriptor()
          INTERNAL: Return the referenced descriptor.
 FetchGroup getDefaultFetchGroup()
          Return the descriptor-level default fetch group.
 ClassDescriptor getDescriptor()
          PUBLIC: Return the referenced descriptor.
 FetchGroup getFetchGroup(java.lang.String groupName)
          Return a pre-defined named fetch group.
 java.util.Map getFetchGroups()
          Return the fetch group map: keyed by the group name, valued by the fetch group object.
 void initialize(org.eclipse.persistence.internal.sessions.AbstractSession session)
          INTERNAL: Initialize the fetch groups.
 boolean isAttributeFetched(java.lang.Object object, java.lang.String attributeName)
          Return true if the attribute of the object has already been fetched
 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 prepareQueryWithFetchGroup(ObjectLevelReadQuery query)
          INTERNAL: Prepare the query with the fetch group to add group attributes to the query for partial reading.
 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: Reset object attributes to the default their values.
 void setRefreshOnFetchGroupToObject(java.lang.Object source, boolean shouldRefreshOnFetchgroup)
          INTERNAL: Set if the tracked object is fetched from executing a query with or without refresh.
 boolean shouldWriteInto(java.lang.Object cachedObject, java.lang.Object clone)
          INTERNAL: Return true if the cached object data should be written in clone.
 void unionFetchGroupIntoObject(java.lang.Object source, FetchGroup newFetchGroup, org.eclipse.persistence.internal.sessions.AbstractSession session)
          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, 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 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)

getFetchGroup

public FetchGroup getFetchGroup(java.lang.String groupName)
Return a pre-defined named fetch group.


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,
                                   org.eclipse.persistence.internal.sessions.UnitOfWorkImpl uow)
INTERNAL: Write data of the partially fetched object into the working and backup clones


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


unionFetchGroupIntoObject

public void unionFetchGroupIntoObject(java.lang.Object source,
                                      FetchGroup newFetchGroup,
                                      org.eclipse.persistence.internal.sessions.AbstractSession session)
INTERNAL: Union the fetch group of the domain object with the new fetch group.


unionFetchGroups

public FetchGroup unionFetchGroups(FetchGroup first,
                                   FetchGroup second)
INTERNAL: Union two fetch groups.


reset

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


setObjectFetchGroup

public void setObjectFetchGroup(java.lang.Object source,
                                FetchGroup fetchGroup,
                                org.eclipse.persistence.internal.sessions.AbstractSession session)
INTERNAL: Reset object attributes to the default their values.


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 object,
                                  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.


getClassDescriptor

public ClassDescriptor getClassDescriptor()
INTERNAL: Return the referenced descriptor.


setDescriptor

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


prepareQueryWithFetchGroup

public void prepareQueryWithFetchGroup(ObjectLevelReadQuery query)
INTERNAL: Prepare the query with the fetch group to add group attributes to the query for partial reading.


initialize

public void initialize(org.eclipse.persistence.internal.sessions.AbstractSession session)
                throws DescriptorException
INTERNAL: Initialize the fetch groups.

Throws:
DescriptorException

clone

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

Overrides:
clone in class java.lang.Object

EclipseLink 1.1.4, build 'v20100812-r7860' API Reference