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