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.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    /**
957     * Specify a timeout interval (milliseconds) for any datastore read
958     * operations associated with this persistence manager. To unset
959     * the explicit timeout, specify null. For no timeout, specify 0.
960     * Read operations include, for example, those associated with query,
961     * getObjectById, refresh, retrieve, and extent iteration operations.
962     * If the datastore granularity is larger than milliseconds, the
963     * timeout value will be rounded up to the nearest supported datastore
964     * value.
965     * If a read operation hasn't completed within this interval, the operation
966     * will throw a JDODatastoreException. 
967     * If multiple datastore operations are required to complete the query,
968     * the timeout value applies to each of them individually.
969     * If the datastore and JDO implementation support timeouts, then
970     * javax.jdo.option.DatastoreTimeout is returned by
971     * PersistenceManagerFactory.supportedOptions().
972     * If timeouts are not supported,this method will throw
973     * JDOUnsupportedOptionException.
974     * @since 3.0
975     * @param interval the timeout interval (milliseconds)
976     */
977    void setDatastoreReadTimeoutMillis(Integer interval);
978 
979    /** Get the effective timeout setting for datastore read operations
980     * associated with this persistence manager.
981     * If the timeout has not been set on this persistence manager explicitly,
982     * the default read timeout value from the persistence manager factory
983     * is returned.
984     * @see #setDatastoreReadTimeoutMillis(Integer)
985     * @see PersistenceManagerFactory#setDatastoreReadTimeoutMillis(Integer)
986     * @return the effective timeout setting (milliseconds).
987     * @since 3.0
988     */
989    Integer getDatastoreReadTimeoutMillis();
990 
991    /**
992     * Specify a timeout interval (milliseconds) for any write operations
993     * associated with this persistence manager. To unset the explicit timeout,
994     * specify null. For no timeout, specify 0.
995     * Datastore write operations include, for example, operations associated
996     * with flush, commit, and delete by query.
997     * If the datastore granularity is larger than milliseconds, the
998     * timeout value will be rounded up to the nearest supported datastore
999     * value.
1000     * If a write operation hasn't completed within this interval, methods
1001     * will throw a JDODatastoreException. 
1002     * If multiple datastore operations are required to complete the method,
1003     * the timeout value applies to each of them individually.
1004     * If the datastore and JDO implementation support timeouts, then
1005     * javax.jdo.option.DatastoreTimeout is returned by
1006     * PersistenceManagerFactory.supportedOptions().
1007     * If timeouts are not supported,this method will throw
1008     * JDOUnsupportedOptionException.
1009     * @since 3.0
1010     * @param interval the timeout interval (milliseconds)
1011     */
1012    void setDatastoreWriteTimeoutMillis(Integer interval);
1013 
1014    /** Get the effective timeout setting for write operations. 
1015     * If the timeout has not been set on this persistence manager explicitly,
1016     * the default datastore write timeout value from the persistence manager
1017     * factory is returned.
1018     * @see #setDatastoreWriteTimeoutMillis(Integer)
1019     * @see PersistenceManagerFactory#setDatastoreWriteTimeoutMillis(Integer)
1020     * @return the effective timeout setting (milliseconds).
1021     * @since 3.0
1022     */
1023    Integer getDatastoreWriteTimeoutMillis();
1024 
1025    /** Gets the detachAllOnCommit setting.
1026     * @see #setDetachAllOnCommit(boolean)
1027     * @since 2.0
1028     * @return the detachAllOnCommit setting.
1029     */
1030    boolean getDetachAllOnCommit();
1031 
1032    /** Sets the detachAllOnCommit setting.
1033     *
1034     * <P>DetachAllOnCommit set to <code>false</code> specifies that the
1035     * state of persistent instances in the cache after commit is defined
1036     * by the <code>retainValues</code> flag. With this flag set to true,
1037     * during beforeCompletion all cached instances are prepared for
1038     * detachment according to the fetch plan in effect at commit. Loading
1039     * fields and unloading fields required by the fetch plan is done after
1040     * calling the user's <code>beforeCompletion</code> callback. During
1041     * <code>afterCompletion</code>, before calling the user's
1042     * <code>afterCompletion</code> callback, all detachable persistent
1043     * instances in the cache transition to detached; non-detachable
1044     * persistent instances transition to transient; and detachable
1045     * instances can be serialized as detached instances. Transient
1046     * transactional instances are unaffected by this flag.
1047     *
1048     * @see #getDetachAllOnCommit()
1049     * @since 2.0
1050     */
1051    void setDetachAllOnCommit(boolean flag);
1052    
1053    /** Gets the copyOnAttach setting.
1054     * @see #setCopyOnAttach(boolean)
1055     * @since 2.1
1056     * @return the copyOnAttach setting.
1057     */
1058    boolean getCopyOnAttach();
1059 
1060    /** Sets the copyOnAttach setting.
1061     *
1062     * <P>CopyOnAttach set to <code>true</code> specifies that during
1063     * makePersistent, copies are made of detached parameter instances. 
1064     * With this flag set to <code>false</code>, detached parameter
1065     * instances are attached directly and change their state from
1066     * detached-clean to persistent-clean or from detached-dirty to
1067     * persistent-dirty.
1068     *
1069     * @see #getCopyOnAttach()
1070     * @since 2.1
1071     */
1072    void setCopyOnAttach(boolean flag);
1073    
1074     /**
1075      * Detach the specified instance from the <code>PersistenceManager</code>.
1076      * The flags for detachment (DETACH_LOAD_FIELDS and DETACH_UNLOAD_FIELDS)
1077      * and the active fetch groups determine the scope of fetching for the
1078      * graph of instances reachable from the pc parameter. The state of fields
1079      * in the affected instances is as specified by the FetchPlan.
1080      * @param pc the instance to detach
1081      * @return the detached instance
1082      * @see #detachCopyAll(Object[])
1083      * @since 2.0
1084      */
1085     <T> T detachCopy (T pc);
1086 
1087     /**
1088      * Detach the specified instances from the <code>PersistenceManager</code>.
1089      * The flags for detachment (DETACH_LOAD_FIELDS and DETACH_UNLOAD_FIELDS)
1090      * and the active fetch groups determine the scope of fetching for the
1091      * graph of instances reachable from the pcs parameter. The state of fields
1092      * in the affected instances is as specified by the FetchPlan.
1093      * @param pcs the instances to detach
1094      * @return the detached instances
1095      * @see #detachCopyAll(Object[])
1096      * @since 2.0
1097      */
1098     <T> Collection<T> detachCopyAll (Collection<T> pcs);
1099 
1100     /**
1101      * Detach the specified instances from the <code>PersistenceManager</code>.
1102      * The flags for detachment (DETACH_LOAD_FIELDS and DETACH_UNLOAD_FIELDS)
1103      * and the active fetch groups determine the scope of fetching for the
1104      * graph of instances reachable from the pcs parameter. The state of fields
1105      * in the affected instances is as specified by the FetchPlan.
1106      * The objects returned can be manipulated and re-attached with 
1107      * {@link #makePersistentAll(Object[])}. 
1108      * The detached instances will be
1109      * unmanaged copies of the specified parameters, and are suitable
1110      * for serialization and manipulation outside of a JDO
1111      * environment. When detaching instances, only fields in the
1112      * current {@link FetchPlan} will be traversed. Thus, to detach a
1113      * graph of objects, relations to other persistent instances must
1114      * either be in the <code>default-fetch-group</code>, or in the
1115      * current custom {@link FetchPlan}.
1116      * @param pcs the instances to detach
1117      * @return the detached instances
1118      * @throws JDOUserException if any of the instances to be detached do not
1119      * implement the javax.jdo.spi.Detachable interface.
1120      * @see #makePersistentAll(Object[])
1121      * @see #getFetchPlan
1122      * @since 2.0
1123      */
1124     <T> T[] detachCopyAll (T... pcs);
1125 
1126     /**
1127      * Put the specified key-value pair into the map of user objects.
1128      * @since 2.0
1129      */
1130     Object putUserObject (Object key, Object val);
1131 
1132     /**
1133      * Get the value for the specified key from the map of user objects.
1134      * @param key the key of the object to be returned
1135      * @return the object 
1136      * @since 2.0
1137      */
1138     Object getUserObject (Object key);
1139 
1140     /**
1141      * Remove the specified key and its value from the map of user objects.
1142      * @param key the key of the object to be removed
1143      * @since 2.0
1144      */
1145     Object removeUserObject (Object key);
1146 
1147     /**
1148      * Flushes all dirty, new, and deleted instances to the data
1149      * store. It has no effect if a transaction is not active.
1150      * <p>If a datastore transaction is active, this method
1151      * synchronizes the cache with the datastore and reports any
1152      * exceptions.</p>
1153      * <p>If an optimistic transaction is active, this method obtains
1154      * a datastore connection, synchronizes the cache with the
1155      * datastore using this connection and reports any
1156      * exceptions. The connection obtained by this method is held
1157      * until the end of the transaction.</p>
1158      * <p>If exceptions occur during flush, the implementation will
1159      * set the current transaction's <code>RollbackOnly</code> flag
1160      * (see {@link Transaction#setRollbackOnly}).</p>
1161      * @since	2.0
1162      */
1163     void flush ();
1164 
1165     /**
1166      * Validates the <code>PersistenceManager</code> cache with the
1167      * datastore. This method has no effect if a transaction is not
1168      * active.
1169      * <p>If a datastore transaction is active, this method verifies
1170      * the consistency of instances in the cache against the
1171      * datastore. An implementation might flush instances as if
1172      * {@link #flush} were called, but it is not required to do
1173      * so.</p>
1174      * <p>If an optimistic transaction is active, this method obtains
1175      * a datastore connection and verifies the consistency of the
1176      * instances in the cache against the datastore. If any
1177      * inconsistencies are detected, a {@link
1178      * JDOOptimisticVerificationException} is thrown. This exception
1179      * contains a nested {@link JDOOptimisticVerificationException}
1180      * for each object that failed the consistency check. No
1181      * datastore resources acquired during the execution of this
1182      * method are held beyond the scope of this method.</p>
1183      * @since 2.0
1184      */
1185     void checkConsistency ();
1186 
1187     /**
1188      * Returns the <code>FetchPlan</code> used by this
1189      * <code>PersistenceManager</code>.
1190      * @return the FetchPlan
1191      * @since 2.0
1192      */
1193     FetchPlan getFetchPlan ();
1194 
1195     /**
1196      * Creates an instance of a persistence-capable interface, 
1197      * or of a concrete or abstract class. 
1198      * The returned instance is transient.
1199      * @param pcClass Must be a persistence-capable interface, 
1200      * or a concrete or abstract class that is declared in the metadata.
1201      * @return the created instance
1202      * @since 2.0
1203      */
1204     <T> T newInstance (Class<T> pcClass);
1205 
1206     /**
1207      * Returns the sequence identified by <code>name</code>.
1208      * @param name the name of the Sequence
1209      * @return the Sequence
1210      * @since 2.0
1211      */
1212     Sequence getSequence (String name);
1213 
1214     /**
1215      * If this method is called while a datastore transaction is
1216      * active, the object returned will be enlisted in the current
1217      * transaction. If called in an optimistic transaction or outside
1218      * an active transaction, the object returned will not be
1219      * enlisted in any transaction.
1220      * @return the JDOConnection instance
1221      * @since 2.0
1222      */
1223     JDOConnection getDataStoreConnection ();
1224 
1225     /**
1226      * Adds the listener instance to the list of lifecycle event
1227      * listeners. The <code>classes</code> parameter identifies all
1228      * of the classes of interest. If the <code>classes</code>
1229      * parameter is specified as <code>null</code>, events for all
1230      * persistent classes and interfaces will be sent to
1231      * <code>listenerInstance</code>.
1232      * <p>The listenerInstance will be called for each event for which it
1233      * implements the corresponding listenerInstance interface.</p>
1234      * @param listener the lifecycle listener
1235      * @param classes the classes of interest to the listener
1236      * @since 2.0
1237      */
1238     void addInstanceLifecycleListener (InstanceLifecycleListener listener,
1239         Class... classes);
1240 
1241     /**
1242      * Removes the listener instance from the list of lifecycle event listeners.
1243      * @param listener the listener instance to be removed
1244      * @since 2.0
1245      */
1246     void removeInstanceLifecycleListener (InstanceLifecycleListener listener);
1247 
1248     /**
1249      * Get the Date as seen by the server. 
1250      * Clients using this method can order their operations according to 
1251      * a single time source. Implementations use the setting of the 
1252      * server time zone to prepare a Date instance that represents 
1253      * UTC time on the server. 
1254      * @return a Date instance corresponding to the UTC Date 
1255      * as seen by the server
1256      * @since 2.1
1257      */
1258     Date getServerDate();
1259 
1260     /**
1261      * Get the objects managed by this persistence manager.
1262      * @return the objects
1263      * @since 2.1
1264      */
1265     Set getManagedObjects();
1266 
1267     /**
1268      * Get the objects managed by this persistence manager having the
1269      * specified object states.
1270      * @param states The states of objects that we are interested in
1271      * @return the objects
1272      * @since 2.1
1273      */
1274     Set getManagedObjects(EnumSet<ObjectState> states);
1275 
1276     /**
1277      * Get the objects managed by this persistence manager being instances of
1278      * the specified classes.
1279      * @param classes The classes of objects that we are interested in
1280      * @return the objects
1281      * @since 2.1
1282      */
1283     Set getManagedObjects(Class... classes);
1284 
1285     /**
1286      * Get the objects managed by this persistence manager having the
1287      * specified object states and being instances of the specified classes.
1288      * @param states The states of objects that we are interested in
1289      * @param classes The classes of objects that we are interested in
1290      * @return the objects
1291      * @since 2.1
1292      */
1293     Set getManagedObjects(EnumSet<ObjectState> states, Class... classes);
1294 
1295     /**
1296      * Get a modifiable <code>FetchGroup</code> for the Class and name.
1297      * If a modifiable <code>FetchGroup</code> already exists in the 
1298      * <code>PersistenceManager</code> scope, return it. 
1299      * If not, create and populate a new <code>FetchGroup</code> from the 
1300      * existing definition in the {@link PersistenceManager} or
1301      * {@link PersistenceManagerFactory}. If the definition for the
1302      * <code>FetchGroup</code> is not in scope in either the 
1303      * <code>PersistenceManager</code> or 
1304      * <code>PersistenceManagerFactory</code>, create it with no members. 
1305      * The <code>FetchGroup</code> immediately 
1306      * becomes active and in scope of the PersistenceManager, and hides 
1307      * the corresponding fetch group in the PersistenceManagerFactory.
1308      * @param cls the class or interface for the <code>FetchGroup</code>
1309      * @param name the name of the fetch group
1310      * @return the FetchGroup
1311      * @throws JDOUserException if the class is not a persistence-capable
1312      * class or interface
1313      * @since 2.2
1314      */
1315     FetchGroup getFetchGroup(Class cls, String name);
1316 }