|
Oracle Fusion Middleware Java API Reference for Oracle TopLink 11g Release 1 (11.1.1) E28847-01 |
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object
org.eclipse.persistence.queries.AttributeGroup
org.eclipse.persistence.queries.FetchGroup
public class FetchGroup
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:
FetchGroupManager#getDefaultFetchGroup()
is created and stored on the FetchGroupManager
during metadata processing if any of the basic (DirectToFieldMapping
) are configured to be loaded directly.FetchGroupManager
. For JPA users this can be accomplished using annotation (@FetchGroup) or in an eclipselink-orm.xml. For JPA and native users named groups can be defined in code and added to the FetchGroupManager#addFetchGroup(FetchGroup)
. Adding named groups in code is typically done in a DescriptorCustomizer
and should be done before the session is initialized at login. To use a named FetchGroup on a query the native ObjectLevelReadQuery.setFetchGroupName(String)
can be used of for JPA users the QueryHints#FETCH_GROUP_NAME
an be used.ObjectLevelReadQuery.setFetchGroup(FetchGroup)
while JPA users generally use the QueryHints#FETCH_GROUP
.When a query is executed only one FetchGroup will be used. The order of precedence is:
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 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.
FetchGroupManager
, QueryHints#FETCH_GROUP
, LoadGroup
, Serialized FormField Summary | |
---|---|
private boolean |
shouldLoad Indicates whether this group should be also used as a LoadGroup when processing the query result. |
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 |
Field Detail |
---|
private boolean shouldLoad
LoadGroup
when processing the query result.Constructor Detail |
---|
public FetchGroup()
public FetchGroup(java.lang.String name)
Method Detail |
---|
@Deprecated
public java.util.Set<java.lang.String> getAttributes()
AttributeGroup.getAttributeNames()
public java.lang.String onUnfetchedAttribute(FetchGroupTracker entity, java.lang.String attributeName)
This method is typically only invoked through woven code in the persistence object introduced when FetchGroupTracker
is woven into the entity.
public java.lang.String onUnfetchedAttributeForSet(FetchGroupTracker entity, java.lang.String attributeName)
This method is typically only invoked through woven code in the persistence object introduced when FetchGroupTracker
is woven into the entity.
public void setShouldLoad(boolean shouldLoad)
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.public void setShouldLoadAll(boolean shouldLoad)
LoadGroup
the same as setShouldLoad(boolean)
. Additionally this method will apply the provided boolean value to all nested groups already added.public boolean shouldLoad()
LoadGroup
when processing the results of a query to force the specified relationships to be loaded.protected FetchGroup newGroup(java.lang.String name, AttributeGroup parent)
AttributeGroup
newGroup
in class AttributeGroup
public boolean isFetchGroup()
isFetchGroup
in class AttributeGroup
public boolean isEntityFetchGroup()
public LoadGroup toLoadGroupLoadOnly()
public FetchGroup clone()
clone
in class AttributeGroup
public FetchGroup getGroup(java.lang.String attributeNameOrPath)
getGroup
in class AttributeGroup
public void addAttribute(java.lang.String attributeNameOrPath, AttributeGroup group)
AttributeGroup
Example: group.addAttribute("firstName", group1);
Note that existing group corresponding to attributeNameOrPath will be overridden with the passed group.
group.addAttribute("manager.address", group2);
addAttribute
in class AttributeGroup
group
- - an AttributeGroup to be added.public void addAttribute(java.lang.String attributeNameOrPath, FetchGroup group)
|
|
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |