Interface FetchGroup
-
public interface FetchGroup
FetchGroup represents a named fetch group for a specific class or interface. A fetch group instance identifies the name of the class or interface, the list of members (fields or properties) to be fetched when the fetch group is active, and the recursion depth for each member.Fetch groups are updated using methods on this interface. An instance of a class implementing this interface can be obtained from
PersistenceManager.getFetchGroup(java.lang.Class, java.lang.String)
orPersistenceManagerFactory.getFetchGroup(java.lang.Class, java.lang.String)
.A FetchGroup can be unscoped or can be in one of two scopes (the
PersistenceManager
or thePersistenceManagerFactory
scope). Unscoped FetchGroups do not affect any behavior. A FetchGroup in PersistenceManager scope hides the corresponding FetchGroup in the PersistenceManagerFactory scope.- When a FetchGroup is obtained via
PersistenceManager.getFetchGroup(java.lang.Class, java.lang.String)
, it is immediately in scope of itsPersistenceManager
. Subsequent modifications of the FetchGroup immediately affectFetchPlan
s that contain theFetchGroup
. - When a FetchGroup is obtained via
PersistenceManagerFactory.getFetchGroup(java.lang.Class, java.lang.String)
, it is unscoped. - When a FetchGroup is added to the set of active FetchGroups via
PersistenceManagerFactory.addFetchGroups(javax.jdo.FetchGroup...)
, it is put in scope of thePersistenceManagerFactory
. - When a FetchGroup is removed from the set of active FetchGroups via
PersistenceManagerFactory.removeFetchGroups(javax.jdo.FetchGroup...)
,PersistenceManagerFactory.removeAllFetchGroups()
, or replaced viaPersistenceManagerFactory.addFetchGroups(javax.jdo.FetchGroup...)
, it is unscoped.
- Since:
- 2.2
- Version:
- 2.2
- When a FetchGroup is obtained via
-
-
Field Summary
Fields Modifier and Type Field Description static String
ALL
For use withaddCategory(java.lang.String)
andremoveCategory(java.lang.String)
calls.static String
BASIC
For use withaddCategory(java.lang.String)
andremoveCategory(java.lang.String)
calls.static String
DEFAULT
For use withaddCategory(java.lang.String)
andremoveCategory(java.lang.String)
calls.static String
MULTIVALUED
For use withaddCategory(java.lang.String)
andremoveCategory(java.lang.String)
calls.static String
RELATIONSHIP
For use withaddCategory(java.lang.String)
andremoveCategory(java.lang.String)
calls.
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description FetchGroup
addCategory(String categoryName)
Add the members (fields or properties) of the named category to the set of members in this FetchGroup.FetchGroup
addMember(String memberName)
Add the member (field or property) to the set of members in this FetchGroup.FetchGroup
addMembers(String... memberNames)
Add the member (field or property) to the set of members in this FetchGroup.boolean
equals(Object other)
Return whether this instance is equal to the other.Set
getMembers()
Return an immutable Set of String containing the names of all members.String
getName()
Get the name of this FetchGroup.boolean
getPostLoad()
Get the post-load property of this FetchGroup.int
getRecursionDepth(String memberName)
Get the recursion-depth for this member.Class
getType()
Get the persistent type (class or interface) of this FetchGroup.int
hashCode()
Return the hashCode for this instance.boolean
isUnmodifiable()
Return whether this FetchGroup is unmodifiable.FetchGroup
removeCategory(String categoryName)
Remove the members (fields or properties) of the named category from the set of members in this FetchGroup.FetchGroup
removeMember(String memberName)
Remove the member (field or property) from the set of members in this FetchGroup.FetchGroup
removeMembers(String... memberNames)
Remove the member (field or property) from the set of members in this FetchGroup.FetchGroup
setPostLoad(boolean postLoad)
Set the post-load property of this FetchGroup.FetchGroup
setRecursionDepth(String memberName, int recursionDepth)
Set the recursion-depth for this member.FetchGroup
setUnmodifiable()
Make this FetchGroup unmodifiable.
-
-
-
Field Detail
-
DEFAULT
static final String DEFAULT
For use withaddCategory(java.lang.String)
andremoveCategory(java.lang.String)
calls. This category includes members defined in the default fetch group in xml or annotations. Redefining the default fetch group via the API does not affect the members defined by this category.Using this category also sets the fetch-depth for the members in the default fetch group.
- Since:
- 2.2
- See Also:
- Constant Field Values
-
RELATIONSHIP
static final String RELATIONSHIP
For use withaddCategory(java.lang.String)
andremoveCategory(java.lang.String)
calls. This category includes members of all relationship types.- Since:
- 2.2
- See Also:
- Constant Field Values
-
MULTIVALUED
static final String MULTIVALUED
For use withaddCategory(java.lang.String)
andremoveCategory(java.lang.String)
calls. This category includes members of all multi-valued types, including Collection, array, and Map types of basic and relationship types.- Since:
- 2.2
- See Also:
- Constant Field Values
-
BASIC
static final String BASIC
For use withaddCategory(java.lang.String)
andremoveCategory(java.lang.String)
calls. This category includes members of all primitive and immutable object class types as defined in section 6.4 of the specification, including String, Locale, Currency, BigDecimal, and BigInteger; as well as Date and its jdbc subtypes and Enum types.- Since:
- 2.2
- See Also:
- Constant Field Values
-
ALL
static final String ALL
For use withaddCategory(java.lang.String)
andremoveCategory(java.lang.String)
calls. This category includes all members in the persistent type.Using this category also sets the fetch-depth for the members in the default fetch group.
- Since:
- 2.2
- See Also:
- Constant Field Values
-
-
Method Detail
-
hashCode
int hashCode()
Return the hashCode for this instance. The hash code should combine both the class and fetch group name. The hash codes for two equal instances must be identical.
-
equals
boolean equals(Object other)
Return whether this instance is equal to the other. The equals method must compare the class for identity and the fetch group name for equality.
-
getName
String getName()
Get the name of this FetchGroup. The name is set only in the factory method.- Returns:
- the name
- Since:
- 2.2
-
getType
Class getType()
Get the persistent type (class or interface) of this FetchGroup. The persistent type is set only in the factory method(s).- Returns:
- the persistent type
- Since:
- 2.2
-
getPostLoad
boolean getPostLoad()
Get the post-load property of this FetchGroup.- Returns:
- the post-load property
- Since:
- 2.2
-
setPostLoad
FetchGroup setPostLoad(boolean postLoad)
Set the post-load property of this FetchGroup.- Parameters:
postLoad
- Whether to post load this fetch group- Returns:
- the FetchGroup
- Throws:
JDOUserException
- if the FetchGroup is unmodifiable- Since:
- 2.2
-
addMember
FetchGroup addMember(String memberName)
Add the member (field or property) to the set of members in this FetchGroup.- Parameters:
memberName
- the name of a member to add to the FetchGroup- Returns:
- the FetchGroup
- Throws:
JDOUserException
- if the parameter is not a member of the persistent typeJDOUserException
- if the FetchGroup is unmodifiable- Since:
- 2.2
-
addMembers
FetchGroup addMembers(String... memberNames)
Add the member (field or property) to the set of members in this FetchGroup. Duplicates are ignored.- Parameters:
memberNames
- the names of members to add to the FetchGroup- Returns:
- the FetchGroup
- Throws:
JDOUserException
- if any parameter is not a member of the persistent typeJDOUserException
- if the FetchGroup is unmodifiable- Since:
- 2.2
-
removeMember
FetchGroup removeMember(String memberName)
Remove the member (field or property) from the set of members in this FetchGroup.- Parameters:
memberName
- Name of the member of the class to remove from the FetchGroup.- Returns:
- the FetchGroup
- Throws:
JDOUserException
- if the parameter is not a member of the persistent typeJDOUserException
- if the FetchGroup is unmodifiable- Since:
- 2.2
-
removeMembers
FetchGroup removeMembers(String... memberNames)
Remove the member (field or property) from the set of members in this FetchGroup. Duplicates in the parameter list are eliminated before removing them from the membership.- Parameters:
memberNames
- Member names of the class to remove from this FetchGroup.- Returns:
- the FetchGroup
- Throws:
JDOUserException
- if any parameter is not a member of the persistent typeJDOUserException
- if the FetchGroup is unmodifiable- Since:
- 2.2
-
addCategory
FetchGroup addCategory(String categoryName)
Add the members (fields or properties) of the named category to the set of members in this FetchGroup. This method first resolves the category name to a set of members and then adds the members as ifaddMembers(java.lang.String...)
was called. After this method executes, the category is not remembered.- Parameters:
categoryName
- Category to add to this FetchGroup.- Returns:
- the FetchGroup
- Throws:
JDOUserException
- if the FetchGroup is unmodifiable- Since:
- 2.2
-
removeCategory
FetchGroup removeCategory(String categoryName)
Remove the members (fields or properties) of the named category from the set of members in this FetchGroup. This method first resolves the category name to a set of members and then removes the members as ifremoveMembers(java.lang.String...)
was called. After this method executes, the category is not remembered.- Parameters:
categoryName
- Category to remove from this FetchGroup.- Returns:
- the FetchGroup
- Throws:
JDOUserException
- if the FetchGroup is unmodifiable- Since:
- 2.2
-
setRecursionDepth
FetchGroup setRecursionDepth(String memberName, int recursionDepth)
Set the recursion-depth for this member. The default is 1. A value of 0 means don't fetch the member (as if the member were omitted entirely). A value of -1 means fetch all instances reachable via this member.- Parameters:
memberName
- the name of the field or propertyrecursionDepth
- the value for the recursion-depth property- Returns:
- the FetchGroup
- Throws:
JDOUserException
- if the member does not existJDOUserException
- if the FetchGroup is unmodifiable- Since:
- 2.2
-
getRecursionDepth
int getRecursionDepth(String memberName)
Get the recursion-depth for this member.- Parameters:
memberName
- the name of the field or property- Returns:
- the recursion-depth for this member
- Throws:
JDOUserException
- if the member is not in the FetchGroup- Since:
- 2.2
-
getMembers
Set getMembers()
Return an immutable Set of String containing the names of all members. The Set is a copy of the currently defined members and will not change based on subsequent changes to the membership in the FetchGroup.- Returns:
- an immutable Set containing the names of all members in the FetchGroup
- Since:
- 2.2
-
setUnmodifiable
FetchGroup setUnmodifiable()
Make this FetchGroup unmodifiable. If already unmodifiable, this method has no effect.- Returns:
- the FetchGroup
- Since:
- 2.2
-
isUnmodifiable
boolean isUnmodifiable()
Return whether this FetchGroup is unmodifiable. If so, methodssetPostLoad(boolean)
,addMember(java.lang.String)
,removeMember(java.lang.String)
,addMembers(java.lang.String...)
,removeMembers(java.lang.String...)
,addCategory(java.lang.String)
, andremoveCategory(java.lang.String)
will throwJDOUserException
.- Returns:
- whether the FetchGroup is unmodifiable
- Since:
- 2.2
-
-