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.Collection;
26 import java.util.Date;
27 import java.util.EnumSet;
28 import java.util.Set;
29
30 import javax.jdo.datastore.JDOConnection;
31 import javax.jdo.datastore.Sequence;
32
33 import javax.jdo.listener.InstanceLifecycleListener;
34
35 /** <code>PersistenceManager</code> is the primary interface for JDO-aware
36 * application components. It is the factory for <code>Query</code> and
37 * <code>Transaction</code> instances, and contains methods to manage the
38 * life cycle of <code>PersistenceCapable</code> instances.
39 *
40 * <P>A <code>PersistenceManager</code> is obtained from the
41 * {@link PersistenceManagerFactory}
42 * (recommended) or by construction.
43 * @version 2.1
44 */
45
46 public interface PersistenceManager {
47 /**
48 * A <code>PersistenceManager</code> instance can be used until it is
49 * closed.
50 * @return <code>true</code> if this <code>PersistenceManager</code> has
51 * been closed.
52 * @see #close()
53 */
54 boolean isClosed ();
55
56 /** Close this <code>PersistenceManager</code> so that no further requests
57 * may be made on it. A <code>PersistenceManager</code> instance can be
58 * used only until it is closed.
59 *
60 * <P>Closing a <code>PersistenceManager</code> might release it to the pool
61 * of available <code>PersistenceManager</code>s, or might be garbage
62 * collected, at the option of the JDO implementation. Before being used
63 * again to satisfy a <code>getPersistenceManager()</code> request, the
64 * default values for options will be restored to their values as specified
65 * in the <code>PersistenceManagerFactory</code>.
66 *
67 * <P>This method closes the <code>PersistenceManager</code>.
68 */
69 void close ();
70
71 /** Return the <code>Transaction</code> instance associated with a
72 * <code>PersistenceManager</code>. There is one <code>Transaction</code>
73 * instance associated with each <code>PersistenceManager</code> instance.
74 * The <code>Transaction</code> instance supports options as well as
75 * transaction completion requests.
76 * @return the <code>Transaction</code> associated with this
77 * <code>PersistenceManager</code>.
78 */
79 Transaction currentTransaction();
80
81 /** Mark an instance as no longer needed in the cache. Eviction is normally
82 * done automatically by the <code>PersistenceManager</code> at transaction
83 * completion. This method allows the application to explicitly provide a
84 * hint to the <code>PersistenceManager</code> that the instance is no
85 * longer needed in the cache.
86 * @param pc the instance to evict from the cache.
87 */
88 void evict (Object pc);
89
90 /** Mark an array of instances as no longer needed in the cache.
91 * @see #evict(Object pc)
92 * @param pcs the array of instances to evict from the cache.
93 */
94 void evictAll (Object... pcs);
95
96 /** Mark a <code>Collection</code> of instances as no longer needed in the
97 * cache.
98 * @see #evict(Object pc)
99 * @param pcs the <code>Collection</code> of instances to evict from the
100 * cache.
101 */
102 void evictAll (Collection pcs);
103
104 /** Mark the parameter instances as no longer needed in the cache.
105 * @param pcClass the class of instances to evict
106 * @param subclasses if true, mark instances of subclasses also
107 * @since 2.1
108 */
109 void evictAll (boolean subclasses, Class pcClass);
110
111 /** Mark all persistent-nontransactional instances as no longer needed
112 * in the cache. It transitions
113 * all persistent-nontransactional instances to hollow. Transactional
114 * instances are subject to eviction based on the RetainValues setting.
115 * @see #evict(Object pc)
116 */
117 void evictAll ();
118
119 /** Refresh the state of the instance from the data store.
120 *
121 * <P>In an optimistic transaction, the state of instances in the cache
122 * might not match the state in the data store. This method is used to
123 * reload the state of the instance from the data store so that a subsequent
124 * commit is more likely to succeed.
125 * <P>Outside a transaction, this method will refresh nontransactional
126 * state.
127 * @param pc the instance to refresh.
128 */
129 void refresh (Object pc);
130
131 /** Refresh the state of an array of instances from the data store.
132 *
133 * @see #refresh(Object pc)
134 * @param pcs the array of instances to refresh.
135 */
136 void refreshAll (Object... pcs);
137
138 /** Refresh the state of a <code>Collection</code> of instances from the
139 * data store.
140 *
141 * @see #refresh(Object pc)
142 * @param pcs the <code>Collection</code> of instances to refresh.
143 */
144 void refreshAll (Collection pcs);
145
146 /** Refresh the state of all applicable instances from the data store.
147 * <P>If called with an active transaction, all transactional instances
148 * will be refreshed. If called outside an active transaction, all
149 * nontransactional instances will be refreshed.
150 * @see #refresh(Object pc)
151 */
152 void refreshAll ();
153
154 /**
155 * Refreshes all instances in the exception that failed verification.
156 *
157 * @since 2.0
158 */
159 void refreshAll (JDOException jdoe);
160
161 /** Create a new <code>Query</code> with no elements.
162 * @return the new <code>Query</code>.
163 */
164 Query newQuery ();
165
166 /** Create a new <code>Query</code> using elements from another
167 * <code>Query</code>. The other <code>Query</code> must have been created
168 * by the same JDO implementation. It might be active in a different
169 * <code>PersistenceManager</code> or might have been serialized and
170 * restored.
171 * <P>All of the settings of the other <code>Query</code> are copied to this
172 * <code>Query</code>, except for the candidate <code>Collection</code> or
173 * <code>Extent</code>.
174 * @return the new <code>Query</code>
175 * @param compiled another <code>Query</code> from the same JDO
176 * implementation
177 */
178 Query newQuery (Object compiled);
179
180 /** Create a Construct a new query instance using the specified String
181 * as the single-string representation of the query.
182 * @param query the single-string query
183 * @return the new <code>Query</code>
184 * @since 2.0
185 */
186 Query newQuery (String query);
187
188 /** Create a new <code>Query</code> using the specified language.
189 * @param language the language of the query parameter
190 * @param query the query, which is of a form determined by the language
191 * @return the new <code>Query</code>
192 */
193 Query newQuery (String language, Object query);
194
195 /** Create a new <code>Query</code> specifying the <code>Class</code> of the
196 * candidate instances.
197 * @param cls the <code>Class</code> of the candidate instances
198 * @return the new <code>Query</code>
199 */
200 Query newQuery (Class cls);
201
202 /** Create a new <code>Query</code> with the <code>Class</code> of the
203 * candidate instances and candidate <code>Extent</code>.
204 * @param cln the <code>Extent</code> of candidate instances
205 * @return the new <code>Query</code>
206 */
207 Query newQuery (Extent cln);
208
209 /** Create a new <code>Query</code> with the candidate <code>Class</code>
210 * and <code>Collection</code>.
211 * @param cls the <code>Class</code> of results
212 * @param cln the <code>Collection</code> of candidate instances
213 * @return the new <code>Query</code>
214 */
215 Query newQuery (Class cls, Collection cln);
216
217 /** Create a new <code>Query</code> with the <code>Class</code> of the
218 * candidate instances and filter.
219 * @param cls the <code>Class</code> of results
220 * @param filter the filter for candidate instances
221 * @return the new <code>Query</code>
222 */
223 Query newQuery (Class cls, String filter);
224
225 /** Create a new <code>Query</code> with the <code>Class</code> of the
226 * candidate instances,
227 * candidate <code>Collection</code>, and filter.
228 * @param cls the <code>Class</code> of candidate instances
229 * @param cln the <code>Collection</code> of candidate instances
230 * @param filter the filter for candidate instances
231 * @return the new <code>Query</code>
232 */
233 Query newQuery (Class cls, Collection cln, String filter);
234
235 /** Create a new <code>Query</code> with the
236 * candidate <code>Extent</code> and filter; the class
237 * is taken from the <code>Extent</code>.
238 * @param cln the <code>Extent</code> of candidate instances
239 * @param filter the filter for candidate instances
240 * @return the new <code>Query</code>
241 */
242 Query newQuery (Extent cln, String filter);
243
244 /**
245 * Create a new <code>Query</code> with the given candidate class
246 * from a named query. The query name given must be the name of a
247 * query defined in metadata.
248 * @param cls the <code>Class</code> of candidate instances
249 * @param queryName the name of the query to look up in metadata
250 * @return the new <code>Query</code>
251 */
252 Query newNamedQuery (Class cls, String queryName);
253
254 /** The <code>PersistenceManager</code> manages a collection of instances in
255 * the data store based on the class of the instances. This method returns
256 * an <code>Extent</code> of instances in the data store that might be
257 * iterated or given to a <code>Query</code>. The <code>Extent</code>
258 * itself might not reference any instances, but only hold the class name
259 * and an indicator as to whether subclasses are included in the
260 * <code>Extent</code>.
261 * <P>Note that the <code>Extent</code> might be very large.
262 * @param persistenceCapableClass <code>Class</code> of instances
263 * @param subclasses whether to include instances of subclasses
264 * @return an <code>Extent</code> of the specified <code>Class</code>
265 * @see Query
266 */
267 <T> Extent<T> getExtent (Class<T> persistenceCapableClass, boolean subclasses);
268
269 /**
270 * Equivalent to <code>getExtent (persistenceCapableClass,
271 * true)</code>.
272 * @see #getExtent(Class,boolean)
273 * @since 2.0
274 */
275 <T> Extent<T> getExtent (Class<T> persistenceCapableClass);
276
277 /** This method locates a persistent instance in the cache of instances
278 * managed by this <code>PersistenceManager</code>.
279 * The <code>getObjectById</code> method attempts
280 * to find an instance in the cache with the specified JDO identity.
281 * The <code>oid</code> parameter object might have been returned by an
282 * earlier call to <code>getObjectId</code> or
283 * <code>getTransactionalObjectId</code>, or might have been constructed by
284 * the application.
285 * <P>If the <code>PersistenceManager</code> is unable to resolve the
286 * <code>oid</code> parameter to an ObjectId instance, then it throws a
287 * <code>JDOUserException</code>.
288 * <P>If the <code>validate</code> flag is <code>false</code>, and there is
289 * already an instance in the cache with the same JDO identity as the
290 * <code>oid</code> parameter, then this method returns it. There is no
291 * change made to the state of the returned instance.
292 * <P>If there is not an instance already in the cache with the same JDO
293 * identity as the <code>oid</code> parameter, then this method creates an
294 * instance with the specified JDO identity and returns it. If there is no
295 * transaction in progress, the returned instance will be hollow or
296 * persistent-nontransactional, at the choice of the implementation.
297 * <P>If there is a transaction in progress, the returned instance will
298 * be hollow, persistent-nontransactional, or persistent-clean, at the
299 * choice of the implementation.
300 * <P>It is an implementation decision whether to access the data store,
301 * if required to determine the exact class. This will be the case of
302 * inheritance, where multiple <code>PersistenceCapable</code> classes share
303 * the same ObjectId class.
304 * <P>If the validate flag is <code>false</code>, and the instance does not
305 * exist in the data store, then this method might not fail. It is an
306 * implementation choice whether to fail immediately with a
307 * <code>JDOObjectNotFoundException</code>. But a subsequent access
308 * of the fields of the
309 * instance will throw a <code>JDOObjectNotFoundException</code>
310 * if the instance does not
311 * exist at that time. Further, if a relationship is established to this
312 * instance, then the transaction in which the association was made will
313 * fail.
314 * <P>If the <code>validate</code> flag is <code>true</code>, and there is
315 * already a transactional instance in the cache with the same JDO identity
316 * as the <code>oid</code> parameter, then this method returns it. There is
317 * no change made to the state of the returned instance.
318 * <P>If there is an instance already in the cache with the same JDO
319 * identity as the <code>oid</code> parameter, but the instance is not
320 * transactional, then it must be verified in the data store. If the
321 * instance does not exist in the datastore, then a
322 * <code>JDOObjectNotFoundException</code> is thrown.
323 * <P>If there is not an instance already in the cache with the same JDO
324 * identity as the <code>oid</code> parameter, then this method creates an
325 * instance with the specified JDO identity, verifies that it exists in the
326 * data store, and returns it. If there is no transaction in progress, the
327 * returned instance will be hollow or persistent-nontransactional,
328 * at the choice of the implementation.
329 * <P>If there is a data store transaction in progress, the returned
330 * instance will be persistent-clean.
331 * If there is an optimistic transaction in progress, the returned
332 * instance will be persistent-nontransactional.
333 * @see #getObjectId(Object pc)
334 * @see #getTransactionalObjectId(Object pc)
335 * @return the <code>PersistenceCapable</code> instance with the specified
336 * ObjectId
337 * @param oid an ObjectId
338 * @param validate if the existence of the instance is to be validated
339 */
340 Object getObjectById (Object oid, boolean validate);
341
342 /**
343 * Looks up the instance of the given type with the given key.
344 * @param cls The type of object to load
345 * @param key either the string representation of the object id, or
346 * an object representation of a single field identity key
347 * @return the corresponding persistent instance
348 * @since 2.0
349 */
350 <T> T getObjectById (Class<T> cls, Object key);
351
352 /**
353 * Looks up the instance corresponding to the specified oid. This is
354 * equivalent to <code>getObjectById(oid, true);
355 * @param oid The object id of the object to load
356 * @return the corresponding persistent instance
357 */
358 Object getObjectById (Object oid);
359
360 /** The ObjectId returned by this method represents the JDO identity of
361 * the instance. The ObjectId is a copy (clone) of the internal state
362 * of the instance, and changing it does not affect the JDO identity of
363 * the instance.
364 * <P>The <code>getObjectId</code> method returns an ObjectId instance that
365 * represents the object identity of the specified JDO instance. The
366 * identity is guaranteed to be unique only in the context of the JDO
367 * <code>PersistenceManager</code> that created the identity, and only for
368 * two types of JDO Identity: those that are managed by the application, and
369 * those that are managed by the data store.
370 * <P>If the object identity is being changed in the transaction, by the
371 * application modifying one or more of the application key fields,
372 * then this method returns the identity as of the beginning of the
373 * transaction. The value returned by <code>getObjectId</code> will be
374 * different following <code>afterCompletion</code> processing for
375 * successful transactions. <P>Within a transaction, the ObjectId returned
376 * will compare equal to the ObjectId returned by only one among all JDO
377 * instances associated with the <code>PersistenceManager</code> regardless
378 * of the type of ObjectId.
379 * <P>The ObjectId does not necessarily contain any internal state of the
380 * instance, nor is it necessarily an instance of the class used to
381 * manage identity internally. Therefore, if the application makes a
382 * change to the ObjectId instance returned by this method, there is
383 * no effect on the instance from which the ObjectId was obtained.
384 * <P>The <code>getObjectById</code> method can be used between instances of
385 * <code>PersistenceManager</code> of different JDO vendors only for
386 * instances of persistence capable classes using application-managed
387 * (primary key) JDO identity. If it is used for instances of classes using
388 * datastore identity, the method might succeed, but there are no guarantees
389 * that the parameter and return instances are related in any way.
390 * @see #getTransactionalObjectId(Object pc)
391 * @see #getObjectById(Object oid, boolean validate)
392 * @param pc the <code>PersistenceCapable</code> instance
393 * @return the ObjectId of the instance
394 */
395 Object getObjectId (Object pc);
396
397 /** The ObjectId returned by this method represents the JDO identity of
398 * the instance. The ObjectId is a copy (clone) of the internal state
399 * of the instance, and changing it does not affect the JDO identity of
400 * the instance.
401 * <P>If the object identity is being changed in the transaction, by the
402 * application modifying one or more of the application key fields,
403 * then this method returns the current identity in the transaction.
404 * <P>If there is no transaction in progress, or if none of the key fields
405 * is being modified, then this method will return the same value as
406 * <code>getObjectId</code>.
407 * @see #getObjectId(Object pc)
408 * @see #getObjectById(Object oid, boolean validate)
409 * @param pc a <code>PersistenceCapable</code> instance
410 * @return the ObjectId of the instance
411 */
412 Object getTransactionalObjectId (Object pc);
413
414 /**
415 * This method returns an object id instance corresponding to the pcClass
416 * and key arguments.
417 * @param pcClass the <code>Class</code> of the persistence-capable instance
418 * @param key for single-field identity, the parameter for the
419 * constructor; for non-single-field application identity, the result
420 * of toString() on the object id instance.
421 * @return an instance of the object identity class
422 */
423 Object newObjectIdInstance (Class pcClass, Object key);
424
425 /**
426 * Return the objects with the given oids.
427 * @param oids the oids of the objects to return
428 * @param validate if true, the existance of the objects in
429 * the datastore will be validated.
430 * @return the objects that were looked up, in the
431 * same order as the oids parameter.
432 * @see #getObjectById(Object,boolean)
433 * @since 2.0
434 */
435 Collection getObjectsById (Collection oids, boolean validate);
436
437 /**
438 * Return the objects with the given oids. This method is equivalent
439 * to calling {@link #getObjectsById(Collection, boolean)}
440 * with the validate flag true.
441 * @param oids the oids of the objects to return
442 * @return the objects that were looked up, in the
443 * same order as the oids parameter.
444 * @see #getObjectsById(Collection,boolean)
445 * @since 2.0
446 */
447 Collection getObjectsById (Collection oids);
448
449 /**
450 * Return the objects with the given oids.
451 * @param oids the oids of the objects to return
452 * @param validate if true, the existance of the objects in
453 * the datastore will be validated.
454 * @return the objects that were looked up, in the
455 * same order as the oids parameter.
456 * @see #getObjectById(Object,boolean)
457 * @see #getObjectsById(boolean,Object...)
458 * @deprecated
459 * @since 2.0
460 */
461 Object[] getObjectsById (Object[] oids, boolean validate);
462
463 /**
464 * Return the objects with the given oids.
465 * @param oids the oids of the objects to return
466 * @param validate if true, the existance of the objects in
467 * the datastore will be validated.
468 * @return the objects that were looked up, in the
469 * same order as the oids parameter.
470 * @see #getObjectById(Object,boolean)
471 * @since 2.1
472 */
473 Object[] getObjectsById (boolean validate, Object... oids);
474
475 /**
476 * Return the objects with the given oids. This method is equivalent
477 * to calling {@link #getObjectsById(boolean,Object...)}
478 * with the validate flag true.
479 * @param oids the oids of the objects to return
480 * @return the objects that were looked up, in the
481 * same order as the oids parameter.
482 * @see #getObjectsById(boolean,Object...)
483 * @since 2.0
484 */
485 Object[] getObjectsById (Object... oids);
486
487 /** Make the parameter instance persistent in this
488 * <code>PersistenceManager</code>.
489 * This method makes transient instances persistent and applies detached
490 * instance changes to the cache. It must be called in the context of
491 * an active transaction, or a JDOUserException is thrown. For a transient
492 * instance, it assigns an object identity to the instance and transitions
493 * it to persistent-new. Any transient instances reachable from this
494 * instance via persistent fields of this instance become provisionally
495 * persistent, transitively. That is, they behave as persistent-new
496 * instances (return true to isPersistent, isNew, and isDirty).
497 * But at commit time, the reachability algorithm is run again,
498 * and instances made provisionally persistent that are not then
499 * reachable from persistent instances will revert to transient.
500 * <P>During makePersistent of transient instances, the create life cycle
501 * listener is called.
502 * <P>For detached instances, it locates or instantiates a persistent
503 * instance with the same JDO identity as the detached instance,
504 * and merges the persistent state of the detached instance into the
505 * persistent instance. Only the state of persistent fields is merged.
506 * If non-persistent state needs to be copied, the application should
507 * use the jdoPostAttach callback or the postAttach lifecycle event
508 * listener. Any references to the detached instances from instances
509 * in the closure of the parameter instances are modified to refer to
510 * the corresponding persistent instance instead of to the
511 * detached instance.
512 * <P>During attachment of detached instances, the attach callbacks
513 * and attach life cycle listeners are called.
514 * <P>During application of changes of the detached state, if the JDO
515 * implementation can determine that there were no changes made during
516 * detachment, then the implementation is not required to mark the
517 * corresponding instance dirty. If it cannot determine if changes
518 * were made, then it must mark the instance dirty.
519 * No consistency checking is done during makePersistent of detached
520 * instances. If consistency checking is required by the application,
521 * then flush or checkConsistency should be called after attaching the
522 * instances.
523 * <P>These methods have no effect on parameter persistent instances
524 * already managed by this PersistenceManager. They will throw a
525 * JDOUserException if the parameter instance is managed by a
526 * different PersistenceManager.
527 * If an instance is of a class whose identity type (application,
528 * datastore, or none) is not supported by the JDO implementation,
529 * then a JDOUserException will be thrown for that instance.
530 * The return value for parameter instances in the transient or persistent
531 * states is the same as the parameter value. The return value for
532 * parameter instances in the detached state is the persistent instance
533 * corresponding to the detached instance.
534 * The return values for makePersistentAll methods correspond by position
535 * to the parameter instances.
536 * @param pc an instance of a <code>Class</code> that is persistent
537 * capable.
538 * @return the parameter instance for parameters in the transient or
539 * persistent state, or the corresponding persistent instance
540 * for detached parameter instances
541 */
542 <T> T makePersistent (T pc);
543
544 /** Make an array of instances persistent.
545 * @param pcs an array of instances
546 * @return the parameter instances for parameters in the transient or
547 * persistent state, or the corresponding persistent instance
548 * for detached parameter instances, in the same order as in the
549 * parameter array
550 * @see #makePersistent(Object pc)
551 */
552 <T> T[] makePersistentAll (T... pcs);
553
554 /** Make a <code>Collection</code> of instances persistent.
555 * @param pcs a <code>Collection</code> of instances
556 * @return the parameter instance for parameters in the transient or
557 * persistent state, or the corresponding persistent instance
558 * for detached parameter instances, with an iteration in the same order
559 * as in the parameter Collection
560 * @see #makePersistent(Object pc)
561 */
562 <T> Collection<T> makePersistentAll (Collection<T> pcs);
563
564 /** Delete the persistent instance from the data store.
565 * This method must be called in an active transaction.
566 * The data store object will be removed at commit.
567 * Unlike <code>makePersistent</code>, which makes the closure of the
568 * instance persistent, the closure of the instance is not deleted from the
569 * data store. This method has no effect if the instance is already deleted
570 * in the current transaction.
571 * This method throws <code>JDOUserException</code> if the instance is
572 * transient or is managed by another <code>PersistenceManager</code>.
573 *
574 * @param pc a persistent instance
575 */
576 void deletePersistent (Object pc);
577
578 /** Delete an array of instances from the data store.
579 * @param pcs a <code>Collection</code> of persistent instances
580 * @see #deletePersistent(Object pc)
581 */
582 void deletePersistentAll (Object... pcs);
583
584 /** Delete a <code>Collection</code> of instances from the data store.
585 * @param pcs a <code>Collection</code> of persistent instances
586 * @see #deletePersistent(Object pc)
587 */
588 void deletePersistentAll (Collection pcs);
589
590 /** Make an instance transient, removing it from management by this
591 * <code>PersistenceManager</code>.
592 *
593 * <P>The instance loses its JDO identity and it is no longer associated
594 * with any <code>PersistenceManager</code>. The state of fields is
595 * preserved unchanged.
596 * @param pc the instance to make transient.
597 */
598 void makeTransient (Object pc);
599
600 /** Make an array of instances transient, removing them from management by
601 * this <code>PersistenceManager</code>.
602 *
603 * <P>The instances lose their JDO identity and they are no longer
604 * associated with any <code>PersistenceManager</code>. The state of fields
605 * is preserved unchanged.
606 * @param pcs the instances to make transient.
607 */
608 void makeTransientAll (Object... pcs);
609
610 /** Make a <code>Collection</code> of instances transient, removing them
611 * from management by this <code>PersistenceManager</code>.
612 *
613 * <P>The instances lose their JDO identity and they are no longer
614 * associated with any <code>PersistenceManager</code>. The state of fields
615 * is preserved unchanged.
616 * @param pcs the instances to make transient.
617 */
618 void makeTransientAll (Collection pcs);
619
620 /** Make an instance transient, removing it from management by this
621 * <code>PersistenceManager</code>. If the useFetchPlan parameter is
622 * false, this method behaves exactly as makeTransient(Object pc).
623 * <P>The affected instance(s) lose their JDO identity and are no longer
624 * associated with any <code>PersistenceManager</code>. The state
625 * of fields is unchanged.
626 * <P>If the useFetchPlan parameter is true, then the current FetchPlan
627 * is applied to the pc parameter, as if detachCopy(Object) had been
628 * called. After the graph of instances is loaded, the instances
629 * reachable via loaded fields is made transient. The state of fields
630 * in the affected instances is as specified by the FetchPlan.
631 * <P>Unlike detachCopy, the instances are not detached; there is no
632 * detachment information in the instances.
633 * <P>The instances to be made transient do not need to
634 * implement the javax.jdo.spi.Detachable interface.
635 * @param pc the root instance to make transient.
636 * @param useFetchPlan whether to use the current fetch plan to determine
637 * which fields to load and which instances to make transient
638 * @since 2.0
639 */
640 void makeTransient (Object pc, boolean useFetchPlan);
641
642 /** Make instances transient, removing them from management
643 * by this <code>PersistenceManager</code>. If the useFetchPlan parameter
644 * is false, this method behaves exactly as makeTransientAll(Object[] pcs).
645 * <P>The affected instance(s) lose their JDO identity and are no longer
646 * associated with any <code>PersistenceManager</code>. The state
647 * of fields is unchanged.
648 * <P>If the useFetchPlan parameter is true, then the current FetchPlan
649 * is applied to the pcs parameters and the entire graph of instances
650 * reachable via loaded fields is made transient. The state of fields
651 * in the affected instances is as specified by the FetchPlan.
652 * <P>Unlike detachCopy, the instances are not detached; there is no
653 * detachment information in the instances.
654 * <P>The instances to be made transient do not need to
655 * implement the javax.jdo.spi.Detachable interface.
656 * @param pcs the root instances to make transient.
657 * @param useFetchPlan whether to use the current fetch plan to determine
658 * which fields to load and which instances to make transient
659 * @see #makeTransientAll(boolean,Object...)
660 * @deprecated
661 * @since 2.0
662 */
663 void makeTransientAll (Object[] pcs, boolean useFetchPlan);
664
665 /** Make instances transient, removing them from management
666 * by this <code>PersistenceManager</code>. If the useFetchPlan parameter
667 * is false, this method behaves exactly as makeTransientAll(Object[] pcs).
668 * <P>The affected instance(s) lose their JDO identity and are no longer
669 * associated with any <code>PersistenceManager</code>. The state
670 * of fields is unchanged.
671 * <P>If the useFetchPlan parameter is true, then the current FetchPlan
672 * is applied to the pcs parameters and the entire graph of instances
673 * reachable via loaded fields is made transient. The state of fields
674 * in the affected instances is as specified by the FetchPlan.
675 * <P>Unlike detachCopy, the instances are not detached; there is no
676 * detachment information in the instances.
677 * <P>The instances to be made transient do not need to
678 * implement the javax.jdo.spi.Detachable interface.
679 * @param pcs the root instances to make transient.
680 * @param useFetchPlan whether to use the current fetch plan to determine
681 * which fields to load and which instances to make transient
682 * @since 2.1
683 */
684 void makeTransientAll (boolean useFetchPlan, Object... pcs);
685
686 /** Make instances transient, removing them from management
687 * by this <code>PersistenceManager</code>. If the useFetchPlan parameter
688 * is false, this method behaves exactly as
689 * makeTransientAll(Collection pcs).
690 * <P>The affected instance(s) lose their JDO identity and are no longer
691 * associated with any <code>PersistenceManager</code>. The state
692 * of fields is unchanged.
693 * <P>If the useFetchPlan parameter is true, then the current FetchPlan
694 * is applied to the pcs parameters and the entire graph of instances
695 * reachable via loaded fields is made transient. The state of fields
696 * in the affected instances is as specified by the FetchPlan.
697 * <P>Unlike detachCopy, the instances are not detached; there is no
698 * detachment information in the instances.
699 * <P>The instances to be made transient do not need to
700 * implement the javax.jdo.spi.Detachable interface.
701 * @param pcs the root instances to make transient.
702 * @param useFetchPlan whether to use the current fetch plan to determine
703 * which fields to load and which instances to make transient
704 * @since 2.0
705 */
706 void makeTransientAll (Collection pcs, boolean useFetchPlan);
707
708 /** Make an instance subject to transactional boundaries.
709 *
710 * <P>Transient instances normally do not observe transaction boundaries.
711 * This method makes transient instances sensitive to transaction
712 * completion. If an instance is modified in a transaction, and the
713 * transaction rolls back, the state of the instance is restored to the
714 * state before the first change in the transaction.
715 *
716 * <P>For persistent instances read in optimistic transactions, this method
717 * allows the application to make the state of the instance part of the
718 * transactional state. At transaction commit, the state of the instance in
719 * the cache is compared to the state of the instance in the data store. If
720 * they are not the same, then an exception is thrown.
721 * @param pc the instance to make transactional.
722 */
723 void makeTransactional (Object pc);
724
725 /** Make an array of instances subject to transactional boundaries.
726 * @param pcs the array of instances to make transactional.
727 * @see #makeTransactional(Object pc)
728 */
729 void makeTransactionalAll (Object... pcs);
730
731 /** Make a <code>Collection</code> of instances subject to transactional
732 * boundaries.
733 * @param pcs the <code>Collection</code> of instances to make
734 * transactional.
735 * @see #makeTransactional(Object pc)
736 */
737 void makeTransactionalAll (Collection pcs);
738
739 /** Make an instance non-transactional after commit.
740 *
741 * <P>Normally, at transaction completion, instances are evicted from the
742 * cache. This method allows an application to identify an instance as
743 * not being evicted from the cache at transaction completion. Instead,
744 * the instance remains in the cache with nontransactional state.
745 *
746 * @param pc the instance to make nontransactional.
747 */
748 void makeNontransactional (Object pc);
749
750 /** Make an array of instances non-transactional after commit.
751 *
752 * @param pcs the array of instances to make nontransactional.
753 * @see #makeNontransactional(Object pc)
754 */
755 void makeNontransactionalAll (Object... pcs);
756
757 /** Make a <code>Collection</code> of instances non-transactional after
758 * commit.
759 *
760 * @param pcs the <code>Collection</code> of instances to make
761 * nontransactional.
762 * @see #makeNontransactional(Object pc)
763 */
764 void makeNontransactionalAll (Collection pcs);
765
766 /** Retrieve field values of an instance from the store. This tells
767 * the <code>PersistenceManager</code> that the application intends to use
768 * the instance, and its field values must be retrieved.
769 * <P>The <code>PersistenceManager</code> might use policy information about
770 * the class to retrieve associated instances.
771 * @param pc the instance
772 */
773 void retrieve (Object pc);
774
775 /** Retrieve field values of an instance from the store. This tells
776 * the <code>PersistenceManager</code> that the application intends to use
777 * the instance, and its field values must be retrieved.
778 * <P>If the useFetchPlan parameter is false, this method behaves exactly
779 * as the corresponding method without the useFetchPlan parameter.
780 * If the useFetchPlan parameter is true, and the fetch plan has not been
781 * modified from its default setting, all fields in the current fetch plan
782 * are fetched, and other fields might be fetched lazily by the
783 * implementation. If the useFetchPlan parameter is true, and the fetch
784 * plan has been changed from its default setting, then the fields
785 * specified by the fetch plan are loaded, along with related instances
786 * specified by the fetch plan.
787 * @param pc the instance
788 * @param useFetchPlan whether to use the current fetch plan to determine
789 * which fields to load and which instances to retrieve.
790 * @since 2.0
791 */
792 void retrieve (Object pc, boolean useFetchPlan);
793
794 /** Retrieve field values of instances from the store. This tells
795 * the <code>PersistenceManager</code> that the application intends to use
796 * the instances, and all field values must be retrieved.
797 * <P>The <code>PersistenceManager</code> might use policy information about
798 * the class to retrieve associated instances.
799 * @param pcs the instances
800 */
801 void retrieveAll (Collection pcs);
802
803 /** Retrieve field values of instances from the store. This tells
804 * the <code>PersistenceManager</code> that the application intends to use
805 * the instances, and their field values should be retrieved. The fields
806 * in the current fetch group must be retrieved, and the implementation
807 * might retrieve more fields than the current fetch group.
808 * <P>If the useFetchPlan parameter is false, this method behaves exactly
809 * as the corresponding method without the useFetchPlan parameter.
810 * If the useFetchPlan parameter is true, and the fetch plan has not been
811 * modified from its default setting, all fields in the current fetch plan
812 * are fetched, and other fields might be fetched lazily by the
813 * implementation. If the useFetchPlan parameter is true, and the fetch
814 * plan has been changed from its default setting, then the fields
815 * specified by the fetch plan are loaded, along with related instances
816 * specified by the fetch plan.
817 * @param pcs the instances
818 * @param useFetchPlan whether to use the current fetch plan to determine
819 * which fields to load and which instances to retrieve.
820 * @since 1.0.1
821 */
822 void retrieveAll (Collection pcs, boolean useFetchPlan);
823
824 /** Retrieve field values of instances from the store. This tells
825 * the <code>PersistenceManager</code> that the application intends to use
826 * the instances, and all field values must be retrieved.
827 * <P>The <code>PersistenceManager</code> might use policy information about
828 * the class to retrieve associated instances.
829 * @param pcs the instances
830 */
831 void retrieveAll (Object... pcs);
832
833 /** Retrieve field values of instances from the store. This tells
834 * the <code>PersistenceManager</code> that the application intends to use
835 * the instances, and their field values should be retrieved. The fields
836 * in the current fetch group must be retrieved, and the implementation
837 * might retrieve more fields than the current fetch group.
838 * <P>If the useFetchPlan parameter is false, this method behaves exactly
839 * as the corresponding method without the useFetchPlan parameter.
840 * If the useFetchPlan parameter is true, and the fetch plan has not been
841 * modified from its default setting, all fields in the current fetch plan
842 * are fetched, and other fields might be fetched lazily by the
843 * implementation. If the useFetchPlan parameter is true, and the fetch
844 * plan has been changed from its default setting, then the fields
845 * specified by the fetch plan are loaded, along with related instances
846 * specified by the fetch plan.
847 * @param pcs the instances
848 * @param useFetchPlan whether to use the current fetch plan to determine
849 * which fields to load and which instances to retrieve.
850 * @deprecated
851 * @see #retrieveAll(boolean,Object...)
852 * @since 1.0.1
853 */
854 void retrieveAll (Object[] pcs, boolean useFetchPlan);
855
856 /** Retrieve field values of instances from the store. This tells
857 * the <code>PersistenceManager</code> that the application intends to use
858 * the instances, and their field values should be retrieved. The fields
859 * in the current fetch group must be retrieved, and the implementation
860 * might retrieve more fields than the current fetch group.
861 * <P>If the useFetchPlan parameter is false, this method behaves exactly
862 * as the corresponding method without the useFetchPlan parameter.
863 * If the useFetchPlan parameter is true, and the fetch plan has not been
864 * modified from its default setting, all fields in the current fetch plan
865 * are fetched, and other fields might be fetched lazily by the
866 * implementation. If the useFetchPlan parameter is true, and the fetch
867 * plan has been changed from its default setting, then the fields
868 * specified by the fetch plan are loaded, along with related instances
869 * specified by the fetch plan.
870 * @param pcs the instances
871 * @param useFetchPlan whether to use the current fetch plan to determine
872 * which fields to load and which instances to retrieve.
873 * @since 2.1
874 */
875 void retrieveAll (boolean useFetchPlan, Object... pcs);
876
877 /** The application can manage the <code>PersistenceManager</code> instances
878 * more easily by having an application object associated with each
879 * <code>PersistenceManager</code> instance.
880 * @param o the user instance to be remembered by the
881 * <code>PersistenceManager</code>
882 * @see #getUserObject
883 */
884 void setUserObject (Object o);
885
886 /** The application can manage the <code>PersistenceManager</code> instances
887 * more easily by having an application object associated with each
888 * <code>PersistenceManager</code> instance.
889 * @return the user object associated with this
890 * <code>PersistenceManager</code>
891 * @see #setUserObject
892 */
893 Object getUserObject ();
894
895 /** This method returns the <code>PersistenceManagerFactory</code> used to
896 * create this <code>PersistenceManager</code>.
897 * @return the <code>PersistenceManagerFactory</code> that created
898 * this <code>PersistenceManager</code>
899 */
900 PersistenceManagerFactory getPersistenceManagerFactory();
901
902 /** Return the <code>Class</code> that implements the JDO Identity for the
903 * specified <code>PersistenceCapable</code> class. The application can use
904 * the returned <code>Class</code> to construct a JDO Identity instance for
905 * application identity <code>PersistenceCapable</code> classes. This JDO
906 * Identity instance can then be used to get an instance of the
907 * <code>PersistenceCapable</code> class for use in the application.
908 *
909 * <P>In order for the application to construct an instance of the ObjectId
910 * class it needs to know the class being used by the JDO implementation.
911 * @param cls the <code>PersistenceCapable Class</code>
912 * @return the <code>Class</code> of the ObjectId of the parameter
913 * @see #getObjectById
914 */
915 Class getObjectIdClass(Class cls);
916
917 /** Set the Multithreaded flag for this <code>PersistenceManager</code>.
918 * Applications that use multiple threads to invoke methods or access fields
919 * from instances managed by this <code>PersistenceManager</code> must set
920 * this flag to <code>true</code>.
921 * Instances managed by this <code>PersistenceManager</code> include
922 * persistent or transactional instances of <code>PersistenceCapable</code>
923 * classes, as well as helper instances such as <code>Query</code>,
924 * <code>Transaction</code>, or <code>Extent</code>.
925 * @param flag the Multithreaded setting.
926 */
927 void setMultithreaded (boolean flag);
928
929 /** Get the current Multithreaded flag for this
930 * <code>PersistenceManager</code>.
931 * @see #setMultithreaded
932 * @return the Multithreaded setting.
933 */
934 boolean getMultithreaded();
935
936 /** Set the ignoreCache parameter for queries.
937 *
938 * <P>IgnoreCache set to <code>true</code> specifies that for all
939 * <code>Query</code> instances created by this
940 * <code>PersistenceManager</code>, the default is the cache should be
941 * ignored for queries.
942 * @param flag the ignoreCache setting.
943 */
944 void setIgnoreCache(boolean flag);
945
946 /** Get the ignoreCache setting for queries.
947 *
948 * <P>IgnoreCache set to <code>true</code> specifies that for all
949 * <code>Query</code> instances created by this
950 * <code>PersistenceManager</code>, the default is the cache should be
951 * ignored for queries.
952 * @return the ignoreCache setting.
953 */
954 boolean getIgnoreCache();
955
956 /** Set the default query timeout setting for all <code>Query</code>
957 * instances obtained from this PersistenceManager.
958 *
959 * @param interval The default timeout setting (millisecs).
960 * @since 2.3
961 */
962 void setQueryTimeoutMillis(Integer interval);
963
964 /** Get the default query timeout setting for all
965 * <code>Query</code> instances obtained from this PersistenceManager.
966 *
967 * @return the default query timeout setting.
968 * @since 2.3
969 */
970 Integer getQueryTimeoutMillis();
971
972 /** Gets the detachAllOnCommit setting.
973 * @see #setDetachAllOnCommit(boolean)
974 * @since 2.0
975 * @return the detachAllOnCommit setting.
976 */
977 boolean getDetachAllOnCommit();
978
979 /** Sets the detachAllOnCommit setting.
980 *
981 * <P>DetachAllOnCommit set to <code>false</code> specifies that the
982 * state of persistent instances in the cache after commit is defined
983 * by the <code>retainValues</code> flag. With this flag set to true,
984 * during beforeCompletion all cached instances are prepared for
985 * detachment according to the fetch plan in effect at commit. Loading
986 * fields and unloading fields required by the fetch plan is done after
987 * calling the user's <code>beforeCompletion</code> callback. During
988 * <code>afterCompletion</code>, before calling the user's
989 * <code>afterCompletion</code> callback, all detachable persistent
990 * instances in the cache transition to detached; non-detachable
991 * persistent instances transition to transient; and detachable
992 * instances can be serialized as detached instances. Transient
993 * transactional instances are unaffected by this flag.
994 *
995 * @see #getDetachAllOnCommit()
996 * @since 2.0
997 */
998 void setDetachAllOnCommit(boolean flag);
999
1000 /** Gets the copyOnAttach setting.
1001 * @see #setCopyOnAttach(boolean)
1002 * @since 2.1
1003 * @return the copyOnAttach setting.
1004 */
1005 boolean getCopyOnAttach();
1006
1007 /** Sets the copyOnAttach setting.
1008 *
1009 * <P>CopyOnAttach set to <code>true</code> specifies that during
1010 * makePersistent, copies are made of detached parameter instances.
1011 * With this flag set to <code>false</code>, detached parameter
1012 * instances are attached directly and change their state from
1013 * detached-clean to persistent-clean or from detached-dirty to
1014 * persistent-dirty.
1015 *
1016 * @see #getCopyOnAttach()
1017 * @since 2.1
1018 */
1019 void setCopyOnAttach(boolean flag);
1020
1021 /**
1022 * Detach the specified instance from the <code>PersistenceManager</code>.
1023 * The flags for detachment (DETACH_LOAD_FIELDS and DETACH_UNLOAD_FIELDS)
1024 * and the active fetch groups determine the scope of fetching for the
1025 * graph of instances reachable from the pc parameter. The state of fields
1026 * in the affected instances is as specified by the FetchPlan.
1027 * @param pc the instance to detach
1028 * @return the detached instance
1029 * @see #detachCopyAll(Object[])
1030 * @since 2.0
1031 */
1032 <T> T detachCopy (T pc);
1033
1034 /**
1035 * Detach the specified instances from the <code>PersistenceManager</code>.
1036 * The flags for detachment (DETACH_LOAD_FIELDS and DETACH_UNLOAD_FIELDS)
1037 * and the active fetch groups determine the scope of fetching for the
1038 * graph of instances reachable from the pcs parameter. The state of fields
1039 * in the affected instances is as specified by the FetchPlan.
1040 * @param pcs the instances to detach
1041 * @return the detached instances
1042 * @see #detachCopyAll(Object[])
1043 * @since 2.0
1044 */
1045 <T> Collection<T> detachCopyAll (Collection<T> pcs);
1046
1047 /**
1048 * Detach the specified instances from the <code>PersistenceManager</code>.
1049 * The flags for detachment (DETACH_LOAD_FIELDS and DETACH_UNLOAD_FIELDS)
1050 * and the active fetch groups determine the scope of fetching for the
1051 * graph of instances reachable from the pcs parameter. The state of fields
1052 * in the affected instances is as specified by the FetchPlan.
1053 * The objects returned can be manipulated and re-attached with
1054 * {@link #makePersistentAll(Object[])}.
1055 * The detached instances will be
1056 * unmanaged copies of the specified parameters, and are suitable
1057 * for serialization and manipulation outside of a JDO
1058 * environment. When detaching instances, only fields in the
1059 * current {@link FetchPlan} will be traversed. Thus, to detach a
1060 * graph of objects, relations to other persistent instances must
1061 * either be in the <code>default-fetch-group</code>, or in the
1062 * current custom {@link FetchPlan}.
1063 * @param pcs the instances to detach
1064 * @return the detached instances
1065 * @throws JDOUserException if any of the instances to be detached do not
1066 * implement the javax.jdo.spi.Detachable interface.
1067 * @see #makePersistentAll(Object[])
1068 * @see #getFetchPlan
1069 * @since 2.0
1070 */
1071 <T> T[] detachCopyAll (T... pcs);
1072
1073 /**
1074 * Put the specified key-value pair into the map of user objects.
1075 * @since 2.0
1076 */
1077 Object putUserObject (Object key, Object val);
1078
1079 /**
1080 * Get the value for the specified key from the map of user objects.
1081 * @param key the key of the object to be returned
1082 * @return the object
1083 * @since 2.0
1084 */
1085 Object getUserObject (Object key);
1086
1087 /**
1088 * Remove the specified key and its value from the map of user objects.
1089 * @param key the key of the object to be removed
1090 * @since 2.0
1091 */
1092 Object removeUserObject (Object key);
1093
1094 /**
1095 * Flushes all dirty, new, and deleted instances to the data
1096 * store. It has no effect if a transaction is not active.
1097 * <p>If a datastore transaction is active, this method
1098 * synchronizes the cache with the datastore and reports any
1099 * exceptions.</p>
1100 * <p>If an optimistic transaction is active, this method obtains
1101 * a datastore connection, synchronizes the cache with the
1102 * datastore using this connection and reports any
1103 * exceptions. The connection obtained by this method is held
1104 * until the end of the transaction.</p>
1105 * <p>If exceptions occur during flush, the implementation will
1106 * set the current transaction's <code>RollbackOnly</code> flag
1107 * (see {@link Transaction#setRollbackOnly}).</p>
1108 * @since 2.0
1109 */
1110 void flush ();
1111
1112 /**
1113 * Validates the <code>PersistenceManager</code> cache with the
1114 * datastore. This method has no effect if a transaction is not
1115 * active.
1116 * <p>If a datastore transaction is active, this method verifies
1117 * the consistency of instances in the cache against the
1118 * datastore. An implementation might flush instances as if
1119 * {@link #flush} were called, but it is not required to do
1120 * so.</p>
1121 * <p>If an optimistic transaction is active, this method obtains
1122 * a datastore connection and verifies the consistency of the
1123 * instances in the cache against the datastore. If any
1124 * inconsistencies are detected, a {@link
1125 * JDOOptimisticVerificationException} is thrown. This exception
1126 * contains a nested {@link JDOOptimisticVerificationException}
1127 * for each object that failed the consistency check. No
1128 * datastore resources acquired during the execution of this
1129 * method are held beyond the scope of this method.</p>
1130 * @since 2.0
1131 */
1132 void checkConsistency ();
1133
1134 /**
1135 * Returns the <code>FetchPlan</code> used by this
1136 * <code>PersistenceManager</code>.
1137 * @return the FetchPlan
1138 * @since 2.0
1139 */
1140 FetchPlan getFetchPlan ();
1141
1142 /**
1143 * Creates an instance of a persistence-capable interface,
1144 * or of a concrete or abstract class.
1145 * The returned instance is transient.
1146 * @param pcClass Must be a persistence-capable interface,
1147 * or a concrete or abstract class that is declared in the metadata.
1148 * @return the created instance
1149 * @since 2.0
1150 */
1151 <T> T newInstance (Class<T> pcClass);
1152
1153 /**
1154 * Returns the sequence identified by <code>name</code>.
1155 * @param name the name of the Sequence
1156 * @return the Sequence
1157 * @since 2.0
1158 */
1159 Sequence getSequence (String name);
1160
1161 /**
1162 * If this method is called while a datastore transaction is
1163 * active, the object returned will be enlisted in the current
1164 * transaction. If called in an optimistic transaction or outside
1165 * an active transaction, the object returned will not be
1166 * enlisted in any transaction.
1167 * @return the JDOConnection instance
1168 * @since 2.0
1169 */
1170 JDOConnection getDataStoreConnection ();
1171
1172 /**
1173 * Adds the listener instance to the list of lifecycle event
1174 * listeners. The <code>classes</code> parameter identifies all
1175 * of the classes of interest. If the <code>classes</code>
1176 * parameter is specified as <code>null</code>, events for all
1177 * persistent classes and interfaces will be sent to
1178 * <code>listenerInstance</code>.
1179 * <p>The listenerInstance will be called for each event for which it
1180 * implements the corresponding listenerInstance interface.</p>
1181 * @param listener the lifecycle listener
1182 * @param classes the classes of interest to the listener
1183 * @since 2.0
1184 */
1185 void addInstanceLifecycleListener (InstanceLifecycleListener listener,
1186 Class... classes);
1187
1188 /**
1189 * Removes the listener instance from the list of lifecycle event listeners.
1190 * @param listener the listener instance to be removed
1191 * @since 2.0
1192 */
1193 void removeInstanceLifecycleListener (InstanceLifecycleListener listener);
1194
1195 /**
1196 * Get the Date as seen by the server.
1197 * Clients using this method can order their operations according to
1198 * a single time source. Implementations use the setting of the
1199 * server time zone to prepare a Date instance that represents
1200 * UTC time on the server.
1201 * @return a Date instance corresponding to the UTC Date
1202 * as seen by the server
1203 * @since 2.1
1204 */
1205 Date getServerDate();
1206
1207 /**
1208 * Get the objects managed by this persistence manager.
1209 * @return the objects
1210 * @since 2.1
1211 */
1212 Set getManagedObjects();
1213
1214 /**
1215 * Get the objects managed by this persistence manager having the
1216 * specified object states.
1217 * @param states The states of objects that we are interested in
1218 * @return the objects
1219 * @since 2.1
1220 */
1221 Set getManagedObjects(EnumSet<ObjectState> states);
1222
1223 /**
1224 * Get the objects managed by this persistence manager being instances of
1225 * the specified classes.
1226 * @param classes The classes of objects that we are interested in
1227 * @return the objects
1228 * @since 2.1
1229 */
1230 Set getManagedObjects(Class... classes);
1231
1232 /**
1233 * Get the objects managed by this persistence manager having the
1234 * specified object states and being instances of the specified classes.
1235 * @param states The states of objects that we are interested in
1236 * @param classes The classes of objects that we are interested in
1237 * @return the objects
1238 * @since 2.1
1239 */
1240 Set getManagedObjects(EnumSet<ObjectState> states, Class... classes);
1241
1242 /**
1243 * Get a modifiable <code>FetchGroup</code> for the Class and name.
1244 * If a modifiable <code>FetchGroup</code> already exists in the
1245 * <code>PersistenceManager</code> scope, return it.
1246 * If not, create and populate a new <code>FetchGroup</code> from the
1247 * existing definition in the {@link PersistenceManager} or
1248 * {@link PersistenceManagerFactory}. If the definition for the
1249 * <code>FetchGroup</code> is not in scope in either the
1250 * <code>PersistenceManager</code> or
1251 * <code>PersistenceManagerFactory</code>, create it with no members.
1252 * The <code>FetchGroup</code> immediately
1253 * becomes active and in scope of the PersistenceManager, and hides
1254 * the corresponding fetch group in the PersistenceManagerFactory.
1255 * @param cls the class or interface for the <code>FetchGroup</code>
1256 * @param name the name of the fetch group
1257 * @return the FetchGroup
1258 * @throws JDOUserException if the class is not a persistence-capable
1259 * class or interface
1260 * @since 2.2
1261 */
1262 FetchGroup getFetchGroup(Class cls, String name);
1263 }