View Javadoc

1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    * 
9    *     http://www.apache.org/licenses/LICENSE-2.0
10   * 
11   * Unless required by applicable law or agreed to in writing, software 
12   * distributed under the License is distributed on an "AS IS" BASIS, 
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 
14   * See the License for the specific language governing permissions and 
15   * limitations under the License.
16   */
17  
18  /*
19   * FetchGroup.java
20   *
21   */
22   
23  package javax.jdo;
24  
25  import java.util.Set;
26  
27  /**
28   * FetchGroup represents a named fetch group for a specific class or 
29   * interface. A fetch group instance identifies the name of the class or 
30   * interface, the list of members (fields or properties) to be fetched when 
31   * the fetch group is active, and the recursion depth for each member.
32   * <p> 
33   * Fetch groups are updated using methods on this interface. An instance of
34   * a class implementing this interface can be obtained from
35   * {@link PersistenceManager#getFetchGroup} or
36   * {@link PersistenceManagerFactory#getFetchGroup}.
37   * <p> 
38   * A FetchGroup can be unscoped or can be in one of two scopes (the 
39   * {@link PersistenceManager} or the {@link PersistenceManagerFactory} scope). 
40   * Unscoped FetchGroups do not affect any behavior.
41   * A FetchGroup in PersistenceManager scope hides the corresponding 
42   * FetchGroup in the PersistenceManagerFactory scope.
43   * <ul><li>When a FetchGroup is obtained via 
44   * {@link PersistenceManager#getFetchGroup},
45   * it is immediately in scope of its <code>PersistenceManager</code>.
46   * Subsequent modifications of the FetchGroup
47   * immediately affect <code>FetchPlan</code>s that contain the
48   * <code>FetchGroup</code>.
49   * </li><li>When a FetchGroup is obtained via 
50   * {@link PersistenceManagerFactory#getFetchGroup}, it is unscoped.
51   * </li><li>When a FetchGroup is added to the set of active FetchGroups via
52   * {@link PersistenceManagerFactory#addFetchGroups}, it is put in scope of the
53   * <code>PersistenceManagerFactory</code>. 
54   * </li><li>When a FetchGroup is removed from the set of active FetchGroups via
55   * {@link PersistenceManagerFactory#removeFetchGroups}, 
56   * {@link PersistenceManagerFactory#removeAllFetchGroups}, or replaced via
57   * {@link PersistenceManagerFactory#addFetchGroups}, it is unscoped.
58   * </li></ul>
59   * @version 2.2
60   * @since 2.2
61   */
62  public interface FetchGroup {
63  
64      /**
65       * For use with {@link #addCategory} and {@link #removeCategory} calls.
66       * This category includes members defined in the default fetch group
67       * in xml or annotations. Redefining the default fetch group via the API
68       * does not affect the members defined by this category.
69       * <p>
70       * Using this category also sets the fetch-depth for the members in the
71       * default fetch group.</p>
72       * @since 2.2
73       */
74      public static final String DEFAULT = "default";
75  
76      /**
77       * For use with {@link #addCategory} and {@link #removeCategory} calls.
78       * This category includes members of all relationship types.
79       * @since 2.2
80       */
81      public static final String RELATIONSHIP = "relationship";
82  
83      /**
84       * For use with {@link #addCategory} and {@link #removeCategory} calls.
85       * This category includes members of all multi-valued types, including
86       * Collection, array, and Map types of basic and relationship types.
87       * @since 2.2
88       */
89      public static final String MULTIVALUED = "multivalued";
90  
91      /**
92       * For use with {@link #addCategory} and {@link #removeCategory} calls.
93       * This category includes members of all primitive and immutable
94       * object class types as defined in section 6.4 of the specification,
95       * including String, Locale, Currency, BigDecimal, and BigInteger; 
96       * as well as Date and its jdbc subtypes and Enum types.
97       * @since 2.2
98       */
99      public static final String BASIC = "basic";
100 
101     /**
102      * For use with {@link #addCategory} and {@link #removeCategory} calls.
103      * This category includes all members in the persistent type.
104      * <p>
105      * Using this category also sets the fetch-depth for the members in the
106      * default fetch group.</p>
107      * @since 2.2
108      */
109     public static final String ALL = "all";
110 
111     /** 
112      * Return the hashCode for this instance. The hash code should combine both
113      * the class and fetch group name. The hash codes for two equal instances
114      * must be identical.
115      * @return the hash code
116      * @since 2.2
117      */
118     int hashCode();
119 
120     /**
121      * Return whether this instance is equal to the other. The equals method
122      * must compare the class for identity and the fetch group name for
123      * equality.
124      * @return whether this instance is equal to the other
125      * @since 2.2
126      */
127     boolean equals(Object other);
128 
129     /** 
130      * Get the name of this FetchGroup. The name is set only in the
131      * factory method.
132      * @return the name
133      * @since 2.2
134      */
135     String getName();
136 
137     /** 
138      * Get the persistent type (class or interface) of this FetchGroup.
139      * The persistent type is set only in the factory method(s).
140      * @return the persistent type
141      * @since 2.2
142      */
143     Class getType();
144 
145     /** 
146      * Get the post-load property of this FetchGroup.
147      * @return the post-load property
148      * @since 2.2
149      */
150     boolean getPostLoad();
151 
152     /** 
153      * Set the post-load property of this FetchGroup.
154      * @return the FetchGroup
155      * @throws JDOUserException if the FetchGroup is unmodifiable
156      * @since 2.2
157      */
158     FetchGroup setPostLoad(boolean postLoad);
159 
160     /** 
161      * Add the member (field or property) to the set of members in this
162      * FetchGroup.
163      * @param memberName the name of a member to add to the FetchGroup
164      * @return the FetchGroup
165      * @throws JDOUserException if the parameter is not a member of the
166      * persistent type
167      * @throws JDOUserException if the FetchGroup is unmodifiable
168      * @since 2.2
169      */
170     FetchGroup addMember(String memberName);
171 
172     /** 
173      * Add the member (field or property) to the set of members in this
174      * FetchGroup. Duplicates are ignored.
175      * @param memberNames the names of members to add to the FetchGroup
176      * @return the FetchGroup
177      * @throws JDOUserException if any parameter is not a member of the
178      * persistent type
179      * @throws JDOUserException if the FetchGroup is unmodifiable
180      * @since 2.2
181      */
182     FetchGroup addMembers(String... memberNames);
183 
184     /**
185      * Remove the member (field or property) from the set of members in this
186      * FetchGroup.
187      * @return the FetchGroup
188      * @throws JDOUserException if the parameter is not a member of the
189      * persistent type
190      * @throws JDOUserException if the FetchGroup is unmodifiable
191      * @since 2.2
192      */
193     FetchGroup removeMember(String memberName);
194 
195     /**
196      * Remove the member (field or property) from the set of members in this
197      * FetchGroup. Duplicates in the parameter list are eliminated before
198      * removing them from the membership.
199      * @return the FetchGroup
200      * @throws JDOUserException if any parameter is not a member of the
201      * persistent type
202      * @throws JDOUserException if the FetchGroup is unmodifiable
203      * @since 2.2
204      */
205     FetchGroup removeMembers(String... memberNames);
206 
207     /**
208      * Add the members (fields or properties) of the named category
209      * to the set of members in this FetchGroup. This method first 
210      * resolves the category name to a set of members and then adds
211      * the members as if {@link #addMembers} was called. After this
212      * method executes, the category is not remembered.
213      * @return the FetchGroup
214      * @throws JDOUserException if the FetchGroup is unmodifiable
215      * @since 2.2
216      */
217     FetchGroup addCategory(String categoryName);
218 
219     /**
220      * Remove the members (fields or properties) of the named category
221      * from the set of members in this FetchGroup. This method first 
222      * resolves the category name to a set of members and then removes
223      * the members as if {@link #removeMembers} was called. After this
224      * method executes, the category is not remembered.
225      * @return the FetchGroup
226      * @throws JDOUserException if the FetchGroup is unmodifiable
227      * @since 2.2
228      */
229     FetchGroup removeCategory(String categoryName);
230 
231     /**
232      * Set the recursion-depth for this member. The default is 1. A value of 0
233      * means don't fetch the member (as if the member were omitted entirely).
234      * A value of -1 means fetch all instances reachable via this member.
235      * @return the FetchGroup
236      * @param memberName the name of the field or property
237      * @param recursionDepth the value for the recursion-depth property
238      * @throws JDOUserException if the member does not exist
239      * @throws JDOUserException if the FetchGroup is unmodifiable
240      * @since 2.2
241      */
242     FetchGroup setRecursionDepth(String memberName, int recursionDepth);
243 
244     /**
245      * Get the recursion-depth for this member.
246      * @param memberName the name of the field or property
247      * @return the recursion-depth for this member
248      * @throws JDOUserException if the member is not in the FetchGroup
249      * @since 2.2
250      */
251     int getRecursionDepth(String memberName);
252 
253     /**
254      * Return an immutable Set of String containing the names of all members.
255      * The Set is a copy of the currently defined members and will not change
256      * based on subsequent changes to the membership in the FetchGroup.
257      * @return an immutable Set containing the names of all members
258      * in the FetchGroup
259      * @since 2.2
260      */
261     Set getMembers();
262 
263     /**
264      * Make this FetchGroup unmodifiable. If already unmodifiable, this method
265      * has no effect.
266      * @return the FetchGroup
267      * @since 2.2
268      */
269     FetchGroup setUnmodifiable();
270 
271     /**
272      * Return whether this FetchGroup is unmodifiable. If so, methods
273      * {@link #setPostLoad}, {@link #addMember}, {@link #removeMember}, 
274      * {@link #addMembers}, {@link #removeMembers}, 
275      * {@link #addCategory}, and {@link #removeCategory}
276      * will throw {@link JDOUserException}.
277      * @return whether the FetchGroup is unmodifiable
278      * @since 2.2
279      */
280     boolean isUnmodifiable();
281 }