1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
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 }