KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > jdo > 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 JavaDoc;
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 JavaDoc 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 JavaDoc[] 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 JavaDoc 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 JavaDoc 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 JavaDoc[] 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc language, Object JavaDoc 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 JavaDoc 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 JavaDoc cls, Collection JavaDoc 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 JavaDoc cls, String JavaDoc 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 JavaDoc cls, Collection JavaDoc cln, String JavaDoc 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 JavaDoc 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 JavaDoc cls, String JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc getObjectById (Object JavaDoc 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 JavaDoc getObjectById (Class JavaDoc cls, Object JavaDoc 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 JavaDoc getObjectById (Object JavaDoc 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 JavaDoc getObjectId (Object JavaDoc 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 JavaDoc getTransactionalObjectId (Object JavaDoc 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 JavaDoc newObjectIdInstance (Class JavaDoc pcClass, Object JavaDoc 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 JavaDoc getObjectsById (Collection JavaDoc 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 JavaDoc getObjectsById (Collection JavaDoc 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 JavaDoc[] getObjectsById (Object JavaDoc[] 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 JavaDoc[] getObjectsById (Object JavaDoc[] 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 JavaDoc 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 JavaDoc[] 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 JavaDoc 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 JavaDoc 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 JavaDoc[] 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 JavaDoc 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 JavaDoc 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 JavaDoc[] 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 JavaDoc 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 JavaDoc 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 JavaDoc[] 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 JavaDoc 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 JavaDoc 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 JavaDoc[] 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc[] 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 JavaDoc[] 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 JavaDoc 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 JavaDoc 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 JavaDoc getObjectIdClass(Class JavaDoc 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 JavaDoc detachCopy (Object JavaDoc 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 JavaDoc detachCopyAll (Collection JavaDoc 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 JavaDoc[] detachCopyAll (Object JavaDoc [] 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 JavaDoc attachCopy (Object JavaDoc 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 JavaDoc attachCopyAll (Collection JavaDoc 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 JavaDoc[] attachCopyAll (Object JavaDoc[] 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 JavaDoc putUserObject (Object JavaDoc key, Object JavaDoc 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 JavaDoc getUserObject (Object JavaDoc 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 JavaDoc removeUserObject (Object JavaDoc 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 JavaDoc newInstance (Class JavaDoc 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 JavaDoc 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 JavaDoc[] 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
Popular Tags