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