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