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,204 @@ +/* + * 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 updated using methods on this interface. An + * instance of this interface can be obtained from {@link + * PersistenceManager#getFetchGroup}. When a FetchGroup + * is created, it is immediately in scope of its + * PersistenceManager. + * Subsequent modifications of the FetchGroup also + * immediately affect FetchPlans that contain the + * FetchGroup. + * @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. + * @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. + * @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,17 @@ * @since 2.1 */ Set getManagedObjects(EnumSet states, Class... classes); + + /** + * Get the FetchGroup that represents the Class and name. If the + * FetchGroup does not already exist, create it. The returned FetchGroup + * is modifiable. The FetchGroup immediately becomes active. That is, + * if a FetchPlan contains the name of the FetchGroup, the contents of + * the FetchGroup are used to implement the behavior of the FetchPlan. + * @param cls the class of the FetchGroup + * @param name the name of the fetch group + * @return the FetchGroup + * @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) @@ -27,6 +27,7 @@ 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 +585,42 @@ */ void removeInstanceLifecycleListener (InstanceLifecycleListener listener); + /** + * Add the fetch groups to the set of active fetch groups. Fetch groups + * are made unmodifiable before being added. Fetch groups that match + * existing fetch groups are made unmodifiable and replace the + * corresponding fetch groups. + * Match is based on identical class and equal name. + * The methods {@link #addFetchGroups}, {@link #removeFetchGroups}, and + * {@link #getFetchGroups} are internally serialized. + * @param groups an array of FetchGroups + * @throws SecurityException if the caller is not authorized for + * JDOPermission("manageMetadata") + * @since 2.2 + */ + void addFetchGroups(FetchGroup... groups); + + /** + * Remove the fetch groups from the set of active fetch groups. + * Existing fetch groups that match parameter fetch groups are removed. + * Match is based on identical class and equal name. + * The methods {@link #addFetchGroups}, {@link #removeFetchGroups}, and + * {@link #getFetchGroups} are internally serialized. + * @param groups an array of FetchGroups + * @throws SecurityException if the caller is not authorized for + * JDOPermission("manageMetadata") + * @since 2.2 + */ + void removeFetchGroups(FetchGroup... groups); + + /** + * Get a Set containing a mutable copy of all currently active fetch groups. + * The methods {@link #addFetchGroups}, {@link #removeFetchGroups}, and + * {@link #getFetchGroups} are internally serialized. + * @return all currently defined fetch groups, from metadata or API + * @throws SecurityException if the caller is not authorized for + * JDOPermission("manageMetadata") + * @since 2.2 + */ + Set getFetchGroups(); } -