Author: andyj
Date: Tue Sep 23 11:47:46 2008
New Revision: 698279
URL: http://svn.apache.org/viewvc?rev=698279&view=rev
Log:
[JDO-554] Apply FetchGroup API changes to api2-legacy
Added:
db/jdo/trunk/api2-legacy/src/java/javax/jdo/FetchGroup.java
Modified:
db/jdo/trunk/api2-legacy/src/java/javax/jdo/PersistenceManager.java
db/jdo/trunk/api2-legacy/src/java/javax/jdo/PersistenceManagerFactory.java
Added: db/jdo/trunk/api2-legacy/src/java/javax/jdo/FetchGroup.java
URL: http://svn.apache.org/viewvc/db/jdo/trunk/api2-legacy/src/java/javax/jdo/FetchGroup.java?rev=698279&view=auto
==============================================================================
--- db/jdo/trunk/api2-legacy/src/java/javax/jdo/FetchGroup.java (added)
+++ db/jdo/trunk/api2-legacy/src/java/javax/jdo/FetchGroup.java Tue Sep 23 11:47:46 2008
@@ -0,0 +1,281 @@
+/*
+ * 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.
+ * <p>
+ * 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}.
+ * <p>
+ * 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.
+ * <ul><li>When a FetchGroup is obtained via
+ * {@link PersistenceManager#getFetchGroup},
+ * it is immediately in scope of its <code>PersistenceManager</code>.
+ * Subsequent modifications of the FetchGroup
+ * immediately affect <code>FetchPlan</code>s that contain the
+ * <code>FetchGroup</code>.
+ * </li><li>When a FetchGroup is obtained via
+ * {@link PersistenceManagerFactory#getFetchGroup}, it is unscoped.
+ * </li><li>When a FetchGroup is added to the set of active FetchGroups via
+ * {@link PersistenceManagerFactory#addFetchGroups}, it is put in scope of the
+ * <code>PersistenceManagerFactory</code>.
+ * </li><li>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.
+ * </li></ul>
+ * @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.
+ * <p>
+ * Using this category also sets the fetch-depth for the members in the
+ * default fetch group.</p>
+ * @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.
+ * <p>
+ * Using this category also sets the fetch-depth for the members in the
+ * default fetch group.</p>
+ * @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.
+ * @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);
+
+ /**
+ * 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();
+}
Modified: db/jdo/trunk/api2-legacy/src/java/javax/jdo/PersistenceManager.java
URL: http://svn.apache.org/viewvc/db/jdo/trunk/api2-legacy/src/java/javax/jdo/PersistenceManager.java?rev=698279&r1=698278&r2=698279&view=diff
==============================================================================
--- db/jdo/trunk/api2-legacy/src/java/javax/jdo/PersistenceManager.java (original)
+++ db/jdo/trunk/api2-legacy/src/java/javax/jdo/PersistenceManager.java Tue Sep 23 11:47:46
2008
@@ -1202,4 +1202,26 @@
* @since 2.1
*/
Set getManagedObjects(Class[] classes);
+
+ /**
+ * Get a modifiable <code>FetchGroup</code> for the Class and name.
+ * If a modifiable <code>FetchGroup</code> already exists in the
+ * <code>PersistenceManager</code> scope, return it.
+ * If not, create and populate a new <code>FetchGroup</code> from the
+ * existing definition in the {@link PersistenceManager} or
+ * {@link PersistenceManagerFactory}. If the definition for the
+ * <code>FetchGroup</code> is not in scope in either the
+ * <code>PersistenceManager</code> or
+ * <code>PersistenceManagerFactory</code>, create it with no members.
+ * The <code>FetchGroup</code> 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 <code>FetchGroup</code>
+ * @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);
}
Modified: db/jdo/trunk/api2-legacy/src/java/javax/jdo/PersistenceManagerFactory.java
URL: http://svn.apache.org/viewvc/db/jdo/trunk/api2-legacy/src/java/javax/jdo/PersistenceManagerFactory.java?rev=698279&r1=698278&r2=698279&view=diff
==============================================================================
--- db/jdo/trunk/api2-legacy/src/java/javax/jdo/PersistenceManagerFactory.java (original)
+++ db/jdo/trunk/api2-legacy/src/java/javax/jdo/PersistenceManagerFactory.java Tue Sep 23
11:47:46 2008
@@ -24,9 +24,12 @@
import javax.jdo.datastore.DataStoreCache;
import javax.jdo.listener.InstanceLifecycleListener;
+import javax.jdo.spi.JDOPermission;
+
import java.io.Serializable;
import java.util.Collection;
import java.util.Properties;
+import java.util.Set;
/** The <code>PersistenceManagerFactory</code> is the interface to use to obtain
* <code>PersistenceManager</code> instances.
@@ -584,5 +587,83 @@
*/
void removeInstanceLifecycleListener (InstanceLifecycleListener listener);
+ /**
+ * Add the <code>FetchGroup</code>s to the set of active fetch groups.
+ * <code>FetchGroup</code>s are made unmodifiable before being added.
+ * <code>FetchGroup</code>s that match existing <code>FetchGroup</code>s
+ * replace the corresponding <code>FetchGroup</code>s.
+ * The replaced <code>FetchGroup</code>s 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 <code>FetchGroup</code>s from the set of active
+ * <code>FetchGroup</code>s. Existing <code>FetchGroup</code>s
that match
+ * parameter <code>FetchGroup</code>s are removed. Parameter
+ * <code>FetchGroup</code>s that do not match any existing
+ * <code>FetchGroup</code> are ignored.
+ * Removed <code>FetchGroup</code>s 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 <code>FetchGroup</code>s from the set of active
+ * <code>FetchGroup</code>s.
+ * All removed <code>FetchGroup</code>s 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 <code>FetchGroup</code> for the Class and
+ * name. If a corresponding <code>FetchGroup</code> already exists in
+ * <code>PersistenceManagerFactory</code> scope, copy its definition
+ * to a new <code>FetchGroup</code>.
+ * If the <code>FetchGroup</code> does not already exist, create it
+ * with no members. The <code>FetchGroup</code> 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();
}
|