PersistenceManager


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>JDODataStoreException</code>. But a subsequent access of the fields of the
281      * instance will throw a <code>JDODataStoreException</code> if the instance does not
282      * exist at that time. Further, if a relationship is established to this
283      * instance, then the transaction in which the association was made will
284      * fail.
285      * <P>If the <code>validate</code> flag is <code>true</code>, and there is already a transactional
286      * instance in the cache with the same JDO identity as the <code>oid</code> parameter,
287      * then this method returns it. There is no change made to the state of
288      * the returned instance.
289      * <P>If there is an instance already in the cache with the same JDO
290      * identity as the <code>oid</code> parameter, but the instance is not transactional,
291      * then it must be verified in the data store. If the instance does not
292      * exist in the datastore, then a <code>JDODataStoreException</code> is thrown.
293      * <P>If there is not an instance already in the cache with the same JDO
294      * identity as the <code>oid</code> parameter, then this method creates an instance
295      * with the specified JDO identity, verifies that it exists in the data
296      * store, and returns it. If there is no transaction in progress, the
297      * returned instance will be hollow or persistent-nontransactional,
298      * at the choice of the implementation.
299      * <P>If there is a data store transaction in progress, the returned
300      * instance will be persistent-clean.
301      * If there is an optimistic transaction in progress, the returned
302      * instance will be persistent-nontransactional.
303      * @see #getObjectId(Object pc)
304      * @see #getTransactionalObjectId(Object pc)
305      * @return the <code>PersistenceCapable</code> instance with the specified ObjectId
306      * @param oid an ObjectId
307      * @param validate if the existence of the instance is to be validated
308      */
309     Object   getObjectById (Object   oid, boolean validate);
310 
311     /**
312      * Looks up the instance of the given type with the given key.
313      * @param cls The type of object to load
314      * @param key either the string representation of the object id, or
315      * an object representation of a single field identity key
316      * @return the corresponding persistent instance
317      * @since 2.0
318      */
319     Object   getObjectById (Class   cls, Object   key);
320 
321     /**
322      * Looks up the instance corresponding to the specified oid. This is
323      * equivalent to <code>getObjectById(oid, true);
324      * @param oid The object id of the object to load
325      * @return the corresponding persistent instance
326      */
327     Object   getObjectById (Object   oid);
328 
329     /** The ObjectId returned by this method represents the JDO identity of
330      * the instance.  The ObjectId is a copy (clone) of the internal state
331      * of the instance, and changing it does not affect the JDO identity of
332      * the instance.  
333      * <P>The <code>getObjectId</code> method returns an ObjectId instance that represents
334      * the object identity of the specified JDO instance. The identity is
335      * guaranteed to be unique only in the context of the JDO
336      * <code>PersistenceManager</code> that created the identity, and only for two types
337      * of JDO Identity: those that are managed by the application, and
338      * those that are managed by the data store.
339      * <P>If the object identity is being changed in the transaction, by the
340      * application modifying one or more of the application key fields,
341      * then this method returns the identity as of the beginning of the
342      * transaction. The value returned by <code>getObjectId</code> will be different
343      * following <code>afterCompletion</code> processing for successful transactions.
344      * <P>Within a transaction, the ObjectId returned will compare equal to
345      * the ObjectId returned by only one among all JDO instances associated
346      * with the <code>PersistenceManager</code> regardless of the type of ObjectId.
347      * <P>The ObjectId does not necessarily contain any internal state of the
348      * instance, nor is it necessarily an instance of the class used to
349      * manage identity internally. Therefore, if the application makes a
350      * change to the ObjectId instance returned by this method, there is
351      * no effect on the instance from which the ObjectId was obtained.
352      * <P>The <code>getObjectById</code> method can be used between instances of
353      * <code>PersistenceManager</code> of different JDO vendors only for instances of
354      * persistence capable classes using application-managed (primary key)
355      * JDO identity. If it is used for instances of classes using datastore
356      * identity, the method might succeed, but there are no guarantees that
357      * the parameter and return instances are related in any way.
358      * @see #getTransactionalObjectId(Object pc)
359      * @see #getObjectById(Object oid, boolean validate)
360      * @param pc the <code>PersistenceCapable</code> instance
361      * @return the ObjectId of the instance
362      */
363     Object   getObjectId (Object   pc);
364     
365     /** The ObjectId returned by this method represents the JDO identity of
366      * the instance.  The ObjectId is a copy (clone) of the internal state
367      * of the instance, and changing it does not affect the JDO identity of
368      * the instance.
369      * <P>If the object identity is being changed in the transaction, by the
370      * application modifying one or more of the application key fields,
371      * then this method returns the current identity in the transaction.
372      * <P>If there is no transaction in progress, or if none of the key fields
373      * is being modified, then this method will return the same value as
374      * <code>getObjectId</code>.
375      * @see #getObjectId(Object pc)
376      * @see #getObjectById(Object oid, boolean validate)
377      * @param pc a <code>PersistenceCapable</code> instance
378      * @return the ObjectId of the instance
379      */
380     Object   getTransactionalObjectId (Object   pc);
381 
382     /** 
383      * This method returns an object id instance corresponding to the pcClass
384      * and key arguments.
385      * @param pcClass the <code>Class</code> of the persistence-capable instance
386      * @param key the value of the key field for single-field identity.
387      * @return an instance of the object identity class
388      */
389     Object   newObjectIdInstance (Class   pcClass, Object   key);
390     
391     /**
392      * Return the objects with the given oids.
393      * @param oids the oids of the objects to return
394      * @param validate if true, the existance of the objects in
395      *     the datastore will be validated.
396      * @return the objects that were looked up, in the
397      *     same order as the oids parameter.
398      * @see #getObjectById(Object,boolean)
399      * @since 2.0
400      */
401     Collection   getObjectsById (Collection   oids, boolean validate);
402 
403     /**
404      * Return the objects with the given oids. This method is equivalent 
405      * to calling {@link #getObjectsById(Collection, boolean)}
406      * with the validate flag true.
407      * @param oids the oids of the objects to return
408      * @return the objects that were looked up, in the
409      *     same order as the oids parameter.
410      * @see #getObjectsById(Collection,boolean)
411      * @since 2.0
412      */
413     Collection   getObjectsById (Collection   oids);
414 
415     /**
416      * Return the objects with the given oids.
417      * @param oids the oids of the objects to return
418      * @param validate if true, the existance of the objects in
419      *     the datastore will be validated.
420      * @return the objects that were looked up, in the
421      *     same order as the oids parameter.
422      * @see #getObjectById(Object,boolean)
423      * @since 2.0
424      */
425     Object  [] getObjectsById (Object  [] oids, boolean validate);
426 
427     /**
428      * Return the objects with the given oids. This method is equivalent
429      * to calling {@link #getObjectsById(Object[],boolean)} 
430      * with the validate flag true.
431      * @param oids the oids of the objects to return
432      * @return the objects that were looked up, in the
433      *     same order as the oids parameter.
434      * @see #getObjectsById(Object[],boolean)
435      * @since 2.0
436      */
437     Object  [] getObjectsById (Object  [] oids);
438 
439     /** Make the transient instance persistent in this <code>PersistenceManager</code>.
440      * This method must be called in an active transaction.
441      * The <code>PersistenceManager</code> assigns an ObjectId to the instance and
442      * transitions it to persistent-new.
443      * The instance will be managed in the <code>Extent</code> associated with its <code>Class</code>.
444      * The instance will be put into the data store at commit.
445      * The closure of instances of <code>PersistenceCapable</code> classes
446      * reachable from persistent
447      * fields will be made persistent at commit.  [This is known as 
448      * persistence by reachability.]
449      * @param pc a transient instance of a <code>Class</code> that implements
450      * <code>PersistenceCapable</code>
451      */
452     void makePersistent (Object   pc);
453     
454     /** Make an array of instances persistent.
455      * @param pcs an array of transient instances
456      * @see #makePersistent(Object pc)
457      */
458     void makePersistentAll (Object  [] pcs);
459     
460     /** Make a <code>Collection</code> of instances persistent.
461      * @param pcs a <code>Collection</code> of transient instances
462      * @see #makePersistent(Object pc)
463      */
464     void makePersistentAll (Collection   pcs);
465     
466     /** Delete the persistent instance from the data store.
467      * This method must be called in an active transaction.
468      * The data store object will be removed at commit.
469      * Unlike <code>makePersistent</code>, which makes the closure of the instance persistent,
470      * the closure of the instance is not deleted from the data store.
471      * This method has no effect if the instance is already deleted in the
472      * current transaction.
473      * This method throws <code>JDOUserException</code> if the instance is transient or 
474      * is managed by another <code>PersistenceManager</code>.
475      *
476      * @param pc a persistent instance
477      */
478     void deletePersistent (Object   pc);
479     
480     /** Delete an array of instances from the data store.
481      * @param pcs a <code>Collection</code> of persistent instances
482      * @see #deletePersistent(Object pc)
483      */
484     void deletePersistentAll (Object  [] pcs);
485     
486     /** Delete a <code>Collection</code> of instances from the data store.
487      * @param pcs a <code>Collection</code> of persistent instances
488      * @see #deletePersistent(Object pc)
489      */
490     void deletePersistentAll (Collection   pcs);
491     
492     /** Make an instance transient, removing it from management by this
493      * <code>PersistenceManager</code>.
494      *
495      * <P>The instance loses its JDO identity and it is no longer associated
496      * with any <code>PersistenceManager</code>.  The state of fields is preserved unchanged.
497      * @param pc the instance to make transient.
498      */
499     void makeTransient (Object   pc);
500     
501     /** Make an array of instances transient, removing them from management by this
502      * <code>PersistenceManager</code>.
503      *
504      * <P>The instances lose their JDO identity and they are no longer associated
505      * with any <code>PersistenceManager</code>.  The state of fields is preserved unchanged.
506      * @param pcs the instances to make transient.
507      */
508     void makeTransientAll (Object  [] pcs);
509     
510     /** Make a <code>Collection</code> of instances transient, removing them from
511      * management by this <code>PersistenceManager</code>.
512      *
513      * <P>The instances lose their JDO identity and they are no longer associated
514      * with any <code>PersistenceManager</code>.  The state of fields is preserved unchanged.
515      * @param pcs the instances to make transient.
516      */ 
517     void makeTransientAll (Collection   pcs);
518     
519     /** Make an instance subject to transactional boundaries.
520      *
521      * <P>Transient instances normally do not observe transaction boundaries.
522      * This method makes transient instances sensitive to transaction completion.
523      * If an instance is modified in a transaction, and the transaction rolls back,
524      * the state of the instance is restored to the state before the first change
525      * in the transaction.
526      *
527      * <P>For persistent instances read in optimistic transactions, this method
528      * allows the application to make the state of the instance part of the
529      * transactional state.  At transaction commit, the state of the instance in
530      * the cache is compared to the state of the instance in the data store.  If they
531      * are not the same, then an exception is thrown.
532      * @param pc the instance to make transactional.
533      */
534     void makeTransactional (Object   pc);
535 
536     /** Make an array of instances subject to transactional boundaries.
537      * @param pcs the array of instances to make transactional.
538      * @see #makeTransactional(Object pc)
539      */
540     void makeTransactionalAll (Object  [] pcs);
541 
542     /** Make a <code>Collection</code> of instances subject to transactional boundaries.
543      * @param pcs the <code>Collection</code> of instances to make transactional.
544      * @see #makeTransactional(Object pc)
545      */
546     void makeTransactionalAll (Collection   pcs);
547     
548     /** Make an instance non-transactional after commit.
549      *
550      * <P>Normally, at transaction completion, instances are evicted from the
551      * cache.  This method allows an application to identify an instance as
552      * not being evicted from the cache at transaction completion.  Instead,
553      * the instance remains in the cache with nontransactional state.
554      *
555      * @param pc the instance to make nontransactional.
556      */
557     void makeNontransactional (Object   pc);
558     
559     /** Make an array of instances non-transactional after commit.
560      *
561      * @param pcs the array of instances to make nontransactional.
562      * @see #makeNontransactional(Object pc)
563      */
564     void makeNontransactionalAll (Object  [] pcs);
565     
566     /** Make a <code>Collection</code> of instances non-transactional after commit.
567      *
568      * @param pcs the <code>Collection</code> of instances to make nontransactional.
569      * @see #makeNontransactional(Object pc)
570      */
571     void makeNontransactionalAll (Collection   pcs);
572     
573     /** Retrieve field values of an instance from the store.  This tells
574      * the <code>PersistenceManager</code> that the application intends to use the
575      * instance, and its field values must be retrieved.
576      * <P>The <code>PersistenceManager</code> might use policy information about the
577      * class to retrieve associated instances.
578      * @param pc the instance
579      */
580     void retrieve (Object   pc);
581     
582     /** Retrieve field values of instances from the store.  This tells
583      * the <code>PersistenceManager</code> that the application intends to use the
584      * instances, and all field values must be retrieved.
585      * <P>The <code>PersistenceManager</code> might use policy information about the
586      * class to retrieve associated instances.
587      * @param pcs the instances
588      */
589     void retrieveAll (Collection   pcs);
590     
591     /** Retrieve field values of instances from the store.  This tells
592      * the <code>PersistenceManager</code> that the application intends to use the
593      * instances, and their field values should be retrieved.  The fields
594      * in the default fetch group must be retrieved, and the implementation
595      * might retrieve more fields than the default fetch group.
596      * <P>The <code>PersistenceManager</code> might use policy information about the
597      * class to retrieve associated instances.
598      * @param pcs the instances
599      * @param DFGOnly whether to retrieve only the default fetch group fields
600      * @since 1.0.1
601      */
602     void retrieveAll (Collection   pcs, boolean DFGOnly);
603     
604     /** Retrieve field values of instances from the store.  This tells
605      * the <code>PersistenceManager</code> that the application intends to use the
606      * instances, and all field values must be retrieved.
607      * <P>The <code>PersistenceManager</code> might use policy information about the
608      * class to retrieve associated instances.
609      * @param pcs the instances
610      */
611     void retrieveAll (Object  [] pcs);
612            
613     /** Retrieve field values of instances from the store.  This tells
614      * the <code>PersistenceManager</code> that the application intends to use the
615      * instances, and their field values should be retrieved.  The fields
616      * in the default fetch group must be retrieved, and the implementation
617      * might retrieve more fields than the default fetch group.
618      * <P>The <code>PersistenceManager</code> might use policy information about the
619      * class to retrieve associated instances.
620      * @param pcs the instances
621      * @param DFGOnly whether to retrieve only the default fetch group fields
622      * @since 1.0.1
623      */
624     void retrieveAll (Object  [] pcs, boolean DFGOnly);
625            
626     /** The application can manage the <code>PersistenceManager</code> instances
627      * more easily by having an application object associated with each
628      * <code>PersistenceManager</code> instance.
629      * @param o the user instance to be remembered by the <code>PersistenceManager</code>
630      * @see #getUserObject
631      */
632     void setUserObject (Object   o);
633     
634     /** The application can manage the <code>PersistenceManager</code> instances
635      * more easily by having an application object associated with each
636      * <code>PersistenceManager</code> instance.
637      * @return the user object associated with this <code>PersistenceManager</code>
638      * @see #setUserObject
639      */
640     Object   getUserObject ();
641      
642     /** This method returns the <code>PersistenceManagerFactory</code> used to create
643      * this <code>PersistenceManager</code>.  
644      * @return the <code>PersistenceManagerFactory</code> that created
645      * this <code>PersistenceManager</code>
646      */
647     PersistenceManagerFactory getPersistenceManagerFactory();
648 
649     /** Return the <code>Class</code> that implements the JDO Identity for the
650      * specified <code>PersistenceCapable</code> class.  The application can use the
651      * returned <code>Class</code> to construct a JDO Identity instance for
652      * application identity <code>PersistenceCapable</code> classes.  This JDO Identity
653      * instance can then be used to get an instance of the
654      * <code>PersistenceCapable</code> class for use in the application.
655      *
656      * <P>In order for the application to construct an instance of the ObjectId class
657      * it needs to know the class being used by the JDO implementation.
658      * @param cls the <code>PersistenceCapable Class</code>
659      * @return the <code>Class</code> of the ObjectId of the parameter
660      * @see #getObjectById
661      */
662     Class   getObjectIdClass(Class   cls);
663   
664     /** Set the Multithreaded flag for this <code>PersistenceManager</code>.  Applications
665      * that use multiple threads to invoke methods or access fields from 
666      * instances managed by this <code>PersistenceManager</code> must set this flag to <code>true</code>.
667      * Instances managed by this <code>PersistenceManager</code> include persistent or
668      * transactional instances of <code>PersistenceCapable</code> classes, as well as 
669      * helper instances such as <code>Query</code>, <code>Transaction</code>, or <code>Extent</code>.
670      * @param flag the Multithreaded setting.
671      */
672     void setMultithreaded (boolean flag);
673   
674     /** Get the current Multithreaded flag for this <code>PersistenceManager</code>.  
675      * @see #setMultithreaded
676      * @return the Multithreaded setting.
677      */
678     boolean getMultithreaded();
679     
680     /** Set the ignoreCache parameter for queries.
681      *
682      * <P>IgnoreCache set to <code>true</code> specifies that for all <code>Query</code> instances created by this
683      * <code>PersistenceManager</code>, the default is the cache should be ignored for queries.
684      * @param flag the ignoreCache setting.
685      */
686     void setIgnoreCache(boolean flag);
687   
688     /** Get the ignoreCache setting for queries.
689      *
690      * <P>IgnoreCache set to <code>true</code> specifies that for all <code>Query</code> instances created by this
691      * <code>PersistenceManager</code>, the default is the cache should be ignored for queries.
692      * @return the ignoreCache setting.
693      */
694    boolean getIgnoreCache();
695     /**
696      * Detach the specified object from the <code>PersistenceManager</code>.
697      * @param pc the instance to detach
698      * @return the detached instance
699      * @see #detachCopyAll(Object[])
700      * @since 2.0
701      */
702     Object   detachCopy (Object   pc);
703 
704     /**
705      * Detach the specified objects from the <code>PersistenceManager</code>.
706      * @param pcs the instances to detach
707      * @return the detached instances
708      * @see #detachCopyAll(Object[])
709      * @since 2.0
710      */
711     Collection   detachCopyAll (Collection   pcs);
712 
713     /**
714      * Detach the specified objects from the
715      * <code>PersistenceManager</code>. The objects returned can be
716      * manipulated and re-attached with 
717      * {@link #attachCopyAll(Object[], boolean)}. 
718      * The detached instances will be
719      * unmanaged copies of the specified parameters, and are suitable
720      * for serialization and manipulation outside of a JDO
721      * environment. When detaching instances, only fields in the
722      * current {@link FetchPlan} will be traversed. Thus, to detach a
723      * graph of objects, relations to other persistent instances must
724      * either be in the <code>default-fetch-group</code>, or in the
725      * current custom {@link FetchPlan}.
726      * @param pcs the instances to detach
727      * @return the detached instances
728      * @throws JDOUserException if any of the instances do not
729      * @see #attachCopyAll(Object[], boolean)
730      * @see #getFetchPlan
731      * @since 2.0
732      */
733     Object  [] detachCopyAll (Object   [] pcs);
734 
735     /**
736      * Import the specified object into the
737      * <code>PersistenceManager</code>.
738      * @param pc instance to import
739      * @param makeTransactional if <code>true</code>, this method will
740      *     mark transactional the persistent instances corresponding
741      *     to all instances in the closure of the detached graph.
742      * @return the re-attached instance
743      * @see #attachCopyAll(Object[],boolean)
744      * @since       2.0
745      */
746     Object   attachCopy (Object   pc, boolean makeTransactional);
747 
748     /**
749      * Import the specified objects into the
750      * <code>PersistenceManager</code>.
751      * @param pcs Collection of instances to import
752      * @param makeTransactional if <code>true</code>, this method will
753      *     mark transactional the persistent instances corresponding
754      *     to all instances in the closure of the detached graph.
755      * @return the re-attached instances
756      * @see #attachCopyAll(Object[],boolean)
757      * @since 2.0
758      */
759     Collection   attachCopyAll (Collection   pcs, boolean makeTransactional);
760 
761     /**
762      * Import the specified objects into the
763      * <code>PersistenceManager</code>. Instances that were
764      * previously detached from this or another
765      * <code>PersistenceManager</code> will have their changed merged
766      * into the persistent instances. Instances that are new will be
767      * persisted as new instances.
768      * @param pcs array of instances to import
769      * @param makeTransactional if <code>true</code>, this method will
770      *     mark transactional the persistent instances corresponding
771      *     to all instances in the closure of the detached graph.
772      * @return the re-attached instances
773      * @see #detachCopyAll(Object[])
774      * @since 2.0
775      */
776     Object  [] attachCopyAll (Object  [] pcs, boolean makeTransactional);
777 
778     /**
779      * Put the specified key-value pair into the map of user objects.
780      * @since 2.0
781      */
782     Object   putUserObject (Object   key, Object   val);
783 
784     /**
785      * Get the value for the specified key from the map of user objects.
786      * @param key the key of the object to be returned
787      * @return the object 
788      * @since 2.0
789      */
790     Object   getUserObject (Object   key);
791 
792     /**
793      * Remove the specified key and its value from the map of user objects.
794      * @param key the key of the object to be removed
795      * @since 2.0
796      */
797     Object   removeUserObject (Object   key);
798 
799     /**
800      * Flushes all dirty, new, and deleted instances to the data
801      * store. It has no effect if a transaction is not active.
802      * <p>If a datastore transaction is active, this method
803      * synchronizes the cache with the datastore and reports any
804      * exceptions.</p>
805      * <p>If an optimistic transaction is active, this method obtains
806      * a datastore connection, synchronizes the cache with the
807      * datastore using this connection and reports any
808      * exceptions. The connection obtained by this method is held
809      * until the end of the transaction.</p>
810      * <p>If exceptions occur during flush, the implementation will
811      * set the current transaction's <code>RollbackOnly</code> flag
812      * (see {@link Transaction#setRollbackOnly}).</p>
813      * @since   2.0
814      */
815     void flush ();
816 
817     /**
818      * Validates the <code>PersistenceManager</code> cache with the
819      * datastore. This method has no effect if a transaction is not
820      * active.
821      * <p>If a datastore transaction is active, this method verifies
822      * the consistency of instances in the cache against the
823      * datastore. An implementation might flush instances as if
824      * {@link #flush} were called, but it is not required to do
825      * so.</p>
826      * <p>If an optimistic transaction is active, this method obtains
827      * a datastore connection and verifies the consistency of the
828      * instances in the cache against the datastore. If any
829      * inconsistencies are detected, a {@link
830      * JDOOptimisticVerificationException} is thrown. This exception
831      * contains a nested {@link JDOOptimisticVerificationException}
832      * for each object that failed the consistency check. No
833      * datastore resources acquired during the execution of this
834      * method are held beyond the scope of this method.</p>
835      * @since 2.0
836      */
837     void checkConsistency ();
838 
839     /**
840      * Returns the <code>FetchPlan</code> used by this
841      * <code>PersistenceManager</code>.
842      * @return the FetchPlan
843      * @since 2.0
844      */
845     FetchPlan getFetchPlan ();
846 
847     /**
848      * Creates an instance of a persistence-capable interface or
849      * abstract class. The returned instance is transient.
850      * @param pcClass Must be an abstract class or interface 
851      *     that is declared in the metadata.
852      * @return the created instance
853      * @since 2.0
854      */
855     Object   newInstance (Class   pcClass);
856 
857     /**
858      * Returns the sequence identified by <code>name</code>.
859      * @param name the name of the Sequence
860      * @return the Sequence
861      * @since 2.0
862      */
863     Sequence getSequence (String   name);
864 
865     /**
866      * If this method is called while a datastore transaction is
867      * active, the object returned will be enlisted in the current
868      * transaction. If called in an optimistic transaction or outside
869      * an active transaction, the object returned will not be
870      * enlisted in any transaction.
871      * @return the JDOConnection instance
872      * @since 2.0
873      */
874     JDOConnection getDataStoreConnection ();
875 
876     /**
877      * Adds the listener instance to the list of lifecycle event
878      * listeners. The <code>classes</code> parameter identifies all
879      * of the classes of interest. If the <code>classes</code>
880      * parameter is specified as <code>null</code>, events for all
881      * persistent classes and interfaces will be sent to
882      * <code>listenerInstance</code>.
883      * <p>The listenerInstance will be called for each event for which it
884      * implements the corresponding listenerInstance interface.</p>
885      * @param listener the lifecycle listener
886      * @param classes the classes of interest to the listener
887      * @since 2.0
888      */
889     void addInstanceLifecycleListener (InstanceLifecycleListener listener,
890         Class  [] classes);
891 
892     /**
893      * Removes the listener instance from the list of lifecycle event listeners.
894      * @param listener the listener instance to be removed
895      * @since 2.0
896      */
897     void removeInstanceLifecycleListener (InstanceLifecycleListener listener);
898 }
899
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags