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    /*** Gets the detachAllOnCommit setting.
957     * @see #setDetachAllOnCommit(boolean)
958     * @since 2.0
959     * @return the detachAllOnCommit setting.
960     */
961    boolean getDetachAllOnCommit();
962 
963    /*** Sets the detachAllOnCommit setting.
964     *
965     * <P>DetachAllOnCommit set to <code>false</code> specifies that the
966     * state of persistent instances in the cache after commit is defined
967     * by the <code>retainValues</code> flag. With this flag set to true,
968     * during beforeCompletion all cached instances are prepared for
969     * detachment according to the fetch plan in effect at commit. Loading
970     * fields and unloading fields required by the fetch plan is done after
971     * calling the user's <code>beforeCompletion</code> callback. During
972     * <code>afterCompletion</code>, before calling the user's
973     * <code>afterCompletion</code> callback, all detachable persistent
974     * instances in the cache transition to detached; non-detachable
975     * persistent instances transition to transient; and detachable
976     * instances can be serialized as detached instances. Transient
977     * transactional instances are unaffected by this flag.
978     *
979     * @see #getDetachAllOnCommit()
980     * @since 2.0
981     */
982    void setDetachAllOnCommit(boolean flag);
983    
984    /*** Gets the copyOnAttach setting.
985     * @see #setCopyOnAttach(boolean)
986     * @since 2.1
987     * @return the copyOnAttach setting.
988     */
989    boolean getCopyOnAttach();
990 
991    /*** Sets the copyOnAttach setting.
992     *
993     * <P>CopyOnAttach set to <code>true</code> specifies that during
994     * makePersistent, copies are made of detached parameter instances. 
995     * With this flag set to <code>false</code>, detached parameter
996     * instances are attached directly and change their state from
997     * detached-clean to persistent-clean or from detached-dirty to
998     * persistent-dirty.
999     *
1000     * @see #getCopyOnAttach()
1001     * @since 2.1
1002     */
1003    void setCopyOnAttach(boolean flag);
1004    
1005     /***
1006      * Detach the specified instance from the <code>PersistenceManager</code>.
1007      * The flags for detachment (DETACH_LOAD_FIELDS and DETACH_UNLOAD_FIELDS)
1008      * and the active fetch groups determine the scope of fetching for the
1009      * graph of instances reachable from the pc parameter. The state of fields
1010      * in the affected instances is as specified by the FetchPlan.
1011      * @param pc the instance to detach
1012      * @return the detached instance
1013      * @see #detachCopyAll(Object[])
1014      * @since 2.0
1015      */
1016     <T> T detachCopy (T pc);
1017 
1018     /***
1019      * Detach the specified instances from the <code>PersistenceManager</code>.
1020      * The flags for detachment (DETACH_LOAD_FIELDS and DETACH_UNLOAD_FIELDS)
1021      * and the active fetch groups determine the scope of fetching for the
1022      * graph of instances reachable from the pcs parameter. The state of fields
1023      * in the affected instances is as specified by the FetchPlan.
1024      * @param pcs the instances to detach
1025      * @return the detached instances
1026      * @see #detachCopyAll(Object[])
1027      * @since 2.0
1028      */
1029     <T> Collection<T> detachCopyAll (Collection<T> pcs);
1030 
1031     /***
1032      * Detach the specified instances from the <code>PersistenceManager</code>.
1033      * The flags for detachment (DETACH_LOAD_FIELDS and DETACH_UNLOAD_FIELDS)
1034      * and the active fetch groups determine the scope of fetching for the
1035      * graph of instances reachable from the pcs parameter. The state of fields
1036      * in the affected instances is as specified by the FetchPlan.
1037      * The objects returned can be manipulated and re-attached with 
1038      * {@link #makePersistentAll(Object[])}. 
1039      * The detached instances will be
1040      * unmanaged copies of the specified parameters, and are suitable
1041      * for serialization and manipulation outside of a JDO
1042      * environment. When detaching instances, only fields in the
1043      * current {@link FetchPlan} will be traversed. Thus, to detach a
1044      * graph of objects, relations to other persistent instances must
1045      * either be in the <code>default-fetch-group</code>, or in the
1046      * current custom {@link FetchPlan}.
1047      * @param pcs the instances to detach
1048      * @return the detached instances
1049      * @throws JDOUserException if any of the instances to be detached do not
1050      * implement the javax.jdo.spi.Detachable interface.
1051      * @see #makePersistentAll(Object[])
1052      * @see #getFetchPlan
1053      * @since 2.0
1054      */
1055     <T> T[] detachCopyAll (T... pcs);
1056 
1057     /***
1058      * Put the specified key-value pair into the map of user objects.
1059      * @since 2.0
1060      */
1061     Object putUserObject (Object key, Object val);
1062 
1063     /***
1064      * Get the value for the specified key from the map of user objects.
1065      * @param key the key of the object to be returned
1066      * @return the object 
1067      * @since 2.0
1068      */
1069     Object getUserObject (Object key);
1070 
1071     /***
1072      * Remove the specified key and its value from the map of user objects.
1073      * @param key the key of the object to be removed
1074      * @since 2.0
1075      */
1076     Object removeUserObject (Object key);
1077 
1078     /***
1079      * Flushes all dirty, new, and deleted instances to the data
1080      * store. It has no effect if a transaction is not active.
1081      * <p>If a datastore transaction is active, this method
1082      * synchronizes the cache with the datastore and reports any
1083      * exceptions.</p>
1084      * <p>If an optimistic transaction is active, this method obtains
1085      * a datastore connection, synchronizes the cache with the
1086      * datastore using this connection and reports any
1087      * exceptions. The connection obtained by this method is held
1088      * until the end of the transaction.</p>
1089      * <p>If exceptions occur during flush, the implementation will
1090      * set the current transaction's <code>RollbackOnly</code> flag
1091      * (see {@link Transaction#setRollbackOnly}).</p>
1092      * @since	2.0
1093      */
1094     void flush ();
1095 
1096     /***
1097      * Validates the <code>PersistenceManager</code> cache with the
1098      * datastore. This method has no effect if a transaction is not
1099      * active.
1100      * <p>If a datastore transaction is active, this method verifies
1101      * the consistency of instances in the cache against the
1102      * datastore. An implementation might flush instances as if
1103      * {@link #flush} were called, but it is not required to do
1104      * so.</p>
1105      * <p>If an optimistic transaction is active, this method obtains
1106      * a datastore connection and verifies the consistency of the
1107      * instances in the cache against the datastore. If any
1108      * inconsistencies are detected, a {@link
1109      * JDOOptimisticVerificationException} is thrown. This exception
1110      * contains a nested {@link JDOOptimisticVerificationException}
1111      * for each object that failed the consistency check. No
1112      * datastore resources acquired during the execution of this
1113      * method are held beyond the scope of this method.</p>
1114      * @since 2.0
1115      */
1116     void checkConsistency ();
1117 
1118     /***
1119      * Returns the <code>FetchPlan</code> used by this
1120      * <code>PersistenceManager</code>.
1121      * @return the FetchPlan
1122      * @since 2.0
1123      */
1124     FetchPlan getFetchPlan ();
1125 
1126     /***
1127      * Creates an instance of a persistence-capable interface, 
1128      * or of a concrete or abstract class. 
1129      * The returned instance is transient.
1130      * @param pcClass Must be a persistence-capable interface, 
1131      * or a concrete or abstract class that is declared in the metadata.
1132      * @return the created instance
1133      * @since 2.0
1134      */
1135     <T> T newInstance (Class<T> pcClass);
1136 
1137     /***
1138      * Returns the sequence identified by <code>name</code>.
1139      * @param name the name of the Sequence
1140      * @return the Sequence
1141      * @since 2.0
1142      */
1143     Sequence getSequence (String name);
1144 
1145     /***
1146      * If this method is called while a datastore transaction is
1147      * active, the object returned will be enlisted in the current
1148      * transaction. If called in an optimistic transaction or outside
1149      * an active transaction, the object returned will not be
1150      * enlisted in any transaction.
1151      * @return the JDOConnection instance
1152      * @since 2.0
1153      */
1154     JDOConnection getDataStoreConnection ();
1155 
1156     /***
1157      * Adds the listener instance to the list of lifecycle event
1158      * listeners. The <code>classes</code> parameter identifies all
1159      * of the classes of interest. If the <code>classes</code>
1160      * parameter is specified as <code>null</code>, events for all
1161      * persistent classes and interfaces will be sent to
1162      * <code>listenerInstance</code>.
1163      * <p>The listenerInstance will be called for each event for which it
1164      * implements the corresponding listenerInstance interface.</p>
1165      * @param listener the lifecycle listener
1166      * @param classes the classes of interest to the listener
1167      * @since 2.0
1168      */
1169     void addInstanceLifecycleListener (InstanceLifecycleListener listener,
1170         Class... classes);
1171 
1172     /***
1173      * Removes the listener instance from the list of lifecycle event listeners.
1174      * @param listener the listener instance to be removed
1175      * @since 2.0
1176      */
1177     void removeInstanceLifecycleListener (InstanceLifecycleListener listener);
1178 
1179     /***
1180      * Get the Date as seen by the server. 
1181      * Clients using this method can order their operations according to 
1182      * a single time source. Implementations use the setting of the 
1183      * server time zone to prepare a Date instance that represents 
1184      * UTC time on the server. 
1185      * @return a Date instance corresponding to the UTC Date 
1186      * as seen by the server
1187      * @since 2.1
1188      */
1189     Date getServerDate();
1190 
1191     /***
1192      * Get the objects managed by this persistence manager.
1193      * @return the objects
1194      * @since 2.1
1195      */
1196     Set getManagedObjects();
1197 
1198     /***
1199      * Get the objects managed by this persistence manager having the
1200      * specified object states.
1201      * @param states The states of objects that we are interested in
1202      * @return the objects
1203      * @since 2.1
1204      */
1205     Set getManagedObjects(EnumSet<ObjectState> states);
1206 
1207     /***
1208      * Get the objects managed by this persistence manager being instances of
1209      * the specified classes.
1210      * @param classes The classes of objects that we are interested in
1211      * @return the objects
1212      * @since 2.1
1213      */
1214     Set getManagedObjects(Class... classes);
1215 
1216     /***
1217      * Get the objects managed by this persistence manager having the
1218      * specified object states and being instances of the specified classes.
1219      * @param states The states of objects that we are interested in
1220      * @param classes The classes of objects that we are interested in
1221      * @return the objects
1222      * @since 2.1
1223      */
1224     Set getManagedObjects(EnumSet<ObjectState> states, Class... classes);
1225 }