javax.jdo.FetchGroup Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of javax.jdo Show documentation
Show all versions of javax.jdo Show documentation
The Java Data Objects API (JDO) : a standard interface-based Java model abstraction of persistence, developed by the JCP.
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/*
* FetchGroup.java
*
*/
package javax.jdo;
import java.util.Set;
/**
* 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
* {@link PersistenceManager#getFetchGroup} or
* {@link PersistenceManagerFactory#getFetchGroup}.
*
* A FetchGroup can be unscoped or can be in one of two scopes (the
* {@link PersistenceManager} or the {@link PersistenceManagerFactory} 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
* {@link PersistenceManager#getFetchGroup},
* it is immediately in scope of its
PersistenceManager.
* Subsequent modifications of the FetchGroup
* immediately affect FetchPlans that contain the
* FetchGroup.
* - When a FetchGroup is obtained via
* {@link PersistenceManagerFactory#getFetchGroup}, it is unscoped.
*
- When a FetchGroup is added to the set of active FetchGroups via
* {@link PersistenceManagerFactory#addFetchGroups}, it is put in scope of the
*
PersistenceManagerFactory.
* - When a FetchGroup is removed from the set of active FetchGroups via
* {@link PersistenceManagerFactory#removeFetchGroups},
* {@link PersistenceManagerFactory#removeAllFetchGroups}, or replaced via
* {@link PersistenceManagerFactory#addFetchGroups}, it is unscoped.
*
* @version 2.2
* @since 2.2
*/
public interface FetchGroup {
/**
* For use with {@link #addCategory} and {@link #removeCategory} 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
*/
public static final String DEFAULT = "default";
/**
* For use with {@link #addCategory} and {@link #removeCategory} calls.
* This category includes members of all relationship types.
* @since 2.2
*/
public static final String RELATIONSHIP = "relationship";
/**
* For use with {@link #addCategory} and {@link #removeCategory} calls.
* This category includes members of all multi-valued types, including
* Collection, array, and Map types of basic and relationship types.
* @since 2.2
*/
public static final String MULTIVALUED = "multivalued";
/**
* For use with {@link #addCategory} and {@link #removeCategory} 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
*/
public static final String BASIC = "basic";
/**
* For use with {@link #addCategory} and {@link #removeCategory} 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
*/
public static final String ALL = "all";
/**
* 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.
* @return the hash code
* @since 2.2
*/
int hashCode();
/**
* 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.
* @return whether this instance is equal to the other
* @since 2.2
*/
boolean equals(Object other);
/**
* Get the name of this FetchGroup. The name is set only in the
* factory method.
* @return the name
* @since 2.2
*/
String getName();
/**
* Get the persistent type (class or interface) of this FetchGroup.
* The persistent type is set only in the factory method(s).
* @return the persistent type
* @since 2.2
*/
Class getType();
/**
* Get the post-load property of this FetchGroup.
* @return the post-load property
* @since 2.2
*/
boolean getPostLoad();
/**
* Set the post-load property of this FetchGroup.
* @param postLoad Whether to post load this fetch group
* @return the FetchGroup
* @throws JDOUserException if the FetchGroup is unmodifiable
* @since 2.2
*/
FetchGroup setPostLoad(boolean postLoad);
/**
* Add the member (field or property) to the set of members in this
* FetchGroup.
* @param memberName the name of a member to add to the FetchGroup
* @return the FetchGroup
* @throws JDOUserException if the parameter is not a member of the
* persistent type
* @throws JDOUserException if the FetchGroup is unmodifiable
* @since 2.2
*/
FetchGroup addMember(String memberName);
/**
* Add the member (field or property) to the set of members in this
* FetchGroup. Duplicates are ignored.
* @param memberNames the names of members to add to the FetchGroup
* @return the FetchGroup
* @throws JDOUserException if any parameter is not a member of the
* persistent type
* @throws JDOUserException if the FetchGroup is unmodifiable
* @since 2.2
*/
FetchGroup addMembers(String... memberNames);
/**
* Remove the member (field or property) from the set of members in this FetchGroup.
* @param memberName Name of the member of the class to remove from the FetchGroup.
* @return the FetchGroup
* @throws JDOUserException if the parameter is not a member of the persistent type
* @throws JDOUserException if the FetchGroup is unmodifiable
* @since 2.2
*/
FetchGroup removeMember(String memberName);
/**
* 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.
* @param memberNames Member names of the class to remove from this FetchGroup.
* @return the FetchGroup
* @throws JDOUserException if any parameter is not a member of the persistent type
* @throws JDOUserException if the FetchGroup is unmodifiable
* @since 2.2
*/
FetchGroup removeMembers(String... memberNames);
/**
* 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 if {@link #addMembers} was called. After this
* method executes, the category is not remembered.
* @param categoryName Category to add to this FetchGroup.
* @return the FetchGroup
* @throws JDOUserException if the FetchGroup is unmodifiable
* @since 2.2
*/
FetchGroup addCategory(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 if {@link #removeMembers} was called. After this
* method executes, the category is not remembered.
* @param categoryName Category to remove from this FetchGroup.
* @return the FetchGroup
* @throws JDOUserException if the FetchGroup is unmodifiable
* @since 2.2
*/
FetchGroup removeCategory(String categoryName);
/**
* 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.
* @return the FetchGroup
* @param memberName the name of the field or property
* @param recursionDepth the value for the recursion-depth property
* @throws JDOUserException if the member does not exist
* @throws JDOUserException if the FetchGroup is unmodifiable
* @since 2.2
*/
FetchGroup setRecursionDepth(String memberName, int recursionDepth);
/**
* Get the recursion-depth for this member.
* @param memberName the name of the field or property
* @return the recursion-depth for this member
* @throws JDOUserException if the member is not in the FetchGroup
* @since 2.2
*/
int getRecursionDepth(String memberName);
/**
* 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.
* @return an immutable Set containing the names of all members
* in the FetchGroup
* @since 2.2
*/
Set getMembers();
/**
* Make this FetchGroup unmodifiable. If already unmodifiable, this method
* has no effect.
* @return the FetchGroup
* @since 2.2
*/
FetchGroup setUnmodifiable();
/**
* Return whether this FetchGroup is unmodifiable. If so, methods
* {@link #setPostLoad}, {@link #addMember}, {@link #removeMember},
* {@link #addMembers}, {@link #removeMembers},
* {@link #addCategory}, and {@link #removeCategory}
* will throw {@link JDOUserException}.
* @return whether the FetchGroup is unmodifiable
* @since 2.2
*/
boolean isUnmodifiable();
}