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