Index: src/java/javax/jdo/FetchGroup.java =================================================================== --- src/java/javax/jdo/FetchGroup.java (revision 0) +++ src/java/javax/jdo/FetchGroup.java (revision 0) @@ -0,0 +1,228 @@ +/* + * 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; + +/** + * Fetch groups are created and updated using methods on this interface. An + * instance of 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. + *

+ * @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. + * @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. + * @since 2.2 + */ + public static final String MULTIVALUED = "multivalued"; + + /** + * For use with {@link #addCategory} and {@link #removeCategory} calls. + * This category includes members of all basic (primitive and wrapper) + * types as well as String, Date (and jdbc subtypes), Locale, + * 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. + * @since 2.2 + */ + public static final String ALL = "all"; + + /** + * 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. + * @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. + * @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. + * @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. + * @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. + * @return the FetchGroup + * @throws JDOUserException if the FetchGroup is unmodifiable + * @since 2.2 + */ + FetchGroup removeCategory(String categoryName); + + /** + * 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(); +} + Property changes on: src/java/javax/jdo/FetchGroup.java ___________________________________________________________________ Name: svn:eol-style + LF Index: src/java/javax/jdo/PersistenceManager.java =================================================================== --- src/java/javax/jdo/PersistenceManager.java (revision 681435) +++ src/java/javax/jdo/PersistenceManager.java (working copy) @@ -1222,4 +1222,26 @@ * @since 2.1 */ Set getManagedObjects(EnumSet states, Class... classes); + + /** + * Get a modifiable FetchGroup for the Class and name. + * If a modifiable FetchGroup already exists in the + * PersistenceManager scope, return it. + * If not, create and populate a new FetchGroup from the + * existing definition in the {@link PersistenceManager} or + * {@link PersistenceManagerFactory}. If the definition for the + * FetchGroup is not in scope in either the + * PersistenceManager or + * PersistenceManagerFactory, create it with no members. + * The FetchGroup immediately + * becomes active and in scope of the PersistenceManager, and hides + * the corresponding fetch group in the PersistenceManagerFactory. + * @param cls the class or interface for the FetchGroup + * @param name the name of the fetch group + * @return the FetchGroup + * @throws JDOUserException if the class is not a persistence-capable + * class or interface + * @since 2.2 + */ + FetchGroup getFetchGroup(Class cls, String name); } Index: src/java/javax/jdo/PersistenceManagerFactory.java =================================================================== --- src/java/javax/jdo/PersistenceManagerFactory.java (revision 681435) +++ src/java/javax/jdo/PersistenceManagerFactory.java (working copy) @@ -24,9 +24,11 @@ import javax.jdo.datastore.DataStoreCache; import javax.jdo.listener.InstanceLifecycleListener; +import javax.jdo.spi.JDOPermission; // for getFetchGroups javadoc import java.io.Serializable; import java.util.Collection; import java.util.Properties; +import java.util.Set; /** The PersistenceManagerFactory is the interface to use to obtain * PersistenceManager instances. @@ -584,5 +586,82 @@ */ void removeInstanceLifecycleListener (InstanceLifecycleListener listener); + /** + * Add the FetchGroups to the set of active fetch groups. + * FetchGroups are made unmodifiable before being added. + * FetchGroups that match existing FetchGroups + * replace the corresponding FetchGroups. + * The replaced FetchGroups become unscoped. + * Match is based on identical class and equal name. + * The methods {@link #addFetchGroups}, {@link #removeFetchGroups}, + * {@link #getFetchGroups}, and {@link #removeAllFetchGroups} + * are internally serialized. + * @param groups an array of FetchGroups + * @throws SecurityException if the caller is not authorized for + * {@link JDOPermission} ("manageMetadata") + * @since 2.2 + */ + void addFetchGroups(FetchGroup... groups); + + /** + * Remove the FetchGroups from the set of active + * FetchGroups. Existing FetchGroups that match + * parameter FetchGroups are removed. Parameter + * FetchGroups that do not match any existing + * FetchGroup are ignored. + * Removed FetchGroups become unscoped. + * Match is based on identical class and equal name. + * The methods {@link #addFetchGroups}, {@link #removeFetchGroups}, + * {@link #getFetchGroups}, and {@link #removeAllFetchGroups} + * are internally serialized. + * @param groups an array of FetchGroups + * @throws SecurityException if the caller is not authorized for + * {@link JDOPermission} ("manageMetadata") + * @since 2.2 + */ + void removeFetchGroups(FetchGroup... groups); + + /** + * Remove all FetchGroups from the set of active + * FetchGroups. + * All removed FetchGroups become unscoped. + * The methods {@link #addFetchGroups}, {@link #removeFetchGroups}, + * {@link #getFetchGroups}, and {@link #removeAllFetchGroups} + * are internally serialized. + * @throws SecurityException if the caller is not authorized for + * {@link JDOPermission} ("manageMetadata") + * @since 2.2 + */ + void removeAllFetchGroups(); + + /** + * Create an unscoped, modifiable FetchGroup for the Class and + * name. If a corresponding FetchGroup already exists in + * PersistenceManagerFactory scope, copy its definition + * to a new FetchGroup. + * If the FetchGroup does not already exist, create it + * with no members. The FetchGroup does not become + * in scope until it is added to the current set via + * {@link #addFetchGroups}. + * @param cls the class or interface for the FetchGroup + * @param name the name of the fetch group + * @return the FetchGroup + * @throws JDOUserException if the class is not a persistence-capable + * class or interface + * @since 2.2 + */ + FetchGroup getFetchGroup(Class cls, String name); + + /** + * Get a modifiable Set containing a mutable copy of all currently active + * (in scope) fetch groups. + * The methods {@link #addFetchGroups}, {@link #removeFetchGroups}, + * {@link #getFetchGroups}, and {@link #removeAllFetchGroups} + * are internally serialized. + * @return a copy of all currently active fetch groups + * @throws SecurityException if the caller is not authorized for + * {@link JDOPermission} ("getMetadata") + * @since 2.2 + */ + Set getFetchGroups(); } -