View Javadoc

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