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