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 /**
957 * Specify a timeout interval (milliseconds) for any datastore read
958 * operations associated with this persistence manager. To unset
959 * the explicit timeout, specify null. For no timeout, specify 0.
960 * Read operations include, for example, those associated with query,
961 * getObjectById, refresh, retrieve, and extent iteration operations.
962 * If the datastore granularity is larger than milliseconds, the
963 * timeout value will be rounded up to the nearest supported datastore
964 * value.
965 * If a read operation hasn't completed within this interval, the operation
966 * will throw a JDODatastoreException.
967 * If multiple datastore operations are required to complete the query,
968 * the timeout value applies to each of them individually.
969 * If the datastore and JDO implementation support timeouts, then
970 * javax.jdo.option.DatastoreTimeout is returned by
971 * PersistenceManagerFactory.supportedOptions().
972 * If timeouts are not supported,this method will throw
973 * JDOUnsupportedOptionException.
974 * @since 3.0
975 * @param interval the timeout interval (milliseconds)
976 */
977 void setDatastoreReadTimeoutMillis(Integer interval);
978
979 /** Get the effective timeout setting for datastore read operations
980 * associated with this persistence manager.
981 * If the timeout has not been set on this persistence manager explicitly,
982 * the default read timeout value from the persistence manager factory
983 * is returned.
984 * @see #setDatastoreReadTimeoutMillis(Integer)
985 * @see PersistenceManagerFactory#setDatastoreReadTimeoutMillis(Integer)
986 * @return the effective timeout setting (milliseconds).
987 * @since 3.0
988 */
989 Integer getDatastoreReadTimeoutMillis();
990
991 /**
992 * Specify a timeout interval (milliseconds) for any write operations
993 * associated with this persistence manager. To unset the explicit timeout,
994 * specify null. For no timeout, specify 0.
995 * Datastore write operations include, for example, operations associated
996 * with flush, commit, and delete by query.
997 * If the datastore granularity is larger than milliseconds, the
998 * timeout value will be rounded up to the nearest supported datastore
999 * value.
1000 * If a write operation hasn't completed within this interval, methods
1001 * will throw a JDODatastoreException.
1002 * If multiple datastore operations are required to complete the method,
1003 * the timeout value applies to each of them individually.
1004 * If the datastore and JDO implementation support timeouts, then
1005 * javax.jdo.option.DatastoreTimeout is returned by
1006 * PersistenceManagerFactory.supportedOptions().
1007 * If timeouts are not supported,this method will throw
1008 * JDOUnsupportedOptionException.
1009 * @since 3.0
1010 * @param interval the timeout interval (milliseconds)
1011 */
1012 void setDatastoreWriteTimeoutMillis(Integer interval);
1013
1014 /** Get the effective timeout setting for write operations.
1015 * If the timeout has not been set on this persistence manager explicitly,
1016 * the default datastore write timeout value from the persistence manager
1017 * factory is returned.
1018 * @see #setDatastoreWriteTimeoutMillis(Integer)
1019 * @see PersistenceManagerFactory#setDatastoreWriteTimeoutMillis(Integer)
1020 * @return the effective timeout setting (milliseconds).
1021 * @since 3.0
1022 */
1023 Integer getDatastoreWriteTimeoutMillis();
1024
1025 /** Gets the detachAllOnCommit setting.
1026 * @see #setDetachAllOnCommit(boolean)
1027 * @since 2.0
1028 * @return the detachAllOnCommit setting.
1029 */
1030 boolean getDetachAllOnCommit();
1031
1032 /** Sets the detachAllOnCommit setting.
1033 *
1034 * <P>DetachAllOnCommit set to <code>false</code> specifies that the
1035 * state of persistent instances in the cache after commit is defined
1036 * by the <code>retainValues</code> flag. With this flag set to true,
1037 * during beforeCompletion all cached instances are prepared for
1038 * detachment according to the fetch plan in effect at commit. Loading
1039 * fields and unloading fields required by the fetch plan is done after
1040 * calling the user's <code>beforeCompletion</code> callback. During
1041 * <code>afterCompletion</code>, before calling the user's
1042 * <code>afterCompletion</code> callback, all detachable persistent
1043 * instances in the cache transition to detached; non-detachable
1044 * persistent instances transition to transient; and detachable
1045 * instances can be serialized as detached instances. Transient
1046 * transactional instances are unaffected by this flag.
1047 *
1048 * @see #getDetachAllOnCommit()
1049 * @since 2.0
1050 */
1051 void setDetachAllOnCommit(boolean flag);
1052
1053 /** Gets the copyOnAttach setting.
1054 * @see #setCopyOnAttach(boolean)
1055 * @since 2.1
1056 * @return the copyOnAttach setting.
1057 */
1058 boolean getCopyOnAttach();
1059
1060 /** Sets the copyOnAttach setting.
1061 *
1062 * <P>CopyOnAttach set to <code>true</code> specifies that during
1063 * makePersistent, copies are made of detached parameter instances.
1064 * With this flag set to <code>false</code>, detached parameter
1065 * instances are attached directly and change their state from
1066 * detached-clean to persistent-clean or from detached-dirty to
1067 * persistent-dirty.
1068 *
1069 * @see #getCopyOnAttach()
1070 * @since 2.1
1071 */
1072 void setCopyOnAttach(boolean flag);
1073
1074 /**
1075 * Detach the specified instance from the <code>PersistenceManager</code>.
1076 * The flags for detachment (DETACH_LOAD_FIELDS and DETACH_UNLOAD_FIELDS)
1077 * and the active fetch groups determine the scope of fetching for the
1078 * graph of instances reachable from the pc parameter. The state of fields
1079 * in the affected instances is as specified by the FetchPlan.
1080 * @param pc the instance to detach
1081 * @return the detached instance
1082 * @see #detachCopyAll(Object[])
1083 * @since 2.0
1084 */
1085 <T> T detachCopy (T pc);
1086
1087 /**
1088 * Detach the specified instances from the <code>PersistenceManager</code>.
1089 * The flags for detachment (DETACH_LOAD_FIELDS and DETACH_UNLOAD_FIELDS)
1090 * and the active fetch groups determine the scope of fetching for the
1091 * graph of instances reachable from the pcs parameter. The state of fields
1092 * in the affected instances is as specified by the FetchPlan.
1093 * @param pcs the instances to detach
1094 * @return the detached instances
1095 * @see #detachCopyAll(Object[])
1096 * @since 2.0
1097 */
1098 <T> Collection<T> detachCopyAll (Collection<T> pcs);
1099
1100 /**
1101 * Detach the specified instances from the <code>PersistenceManager</code>.
1102 * The flags for detachment (DETACH_LOAD_FIELDS and DETACH_UNLOAD_FIELDS)
1103 * and the active fetch groups determine the scope of fetching for the
1104 * graph of instances reachable from the pcs parameter. The state of fields
1105 * in the affected instances is as specified by the FetchPlan.
1106 * The objects returned can be manipulated and re-attached with
1107 * {@link #makePersistentAll(Object[])}.
1108 * The detached instances will be
1109 * unmanaged copies of the specified parameters, and are suitable
1110 * for serialization and manipulation outside of a JDO
1111 * environment. When detaching instances, only fields in the
1112 * current {@link FetchPlan} will be traversed. Thus, to detach a
1113 * graph of objects, relations to other persistent instances must
1114 * either be in the <code>default-fetch-group</code>, or in the
1115 * current custom {@link FetchPlan}.
1116 * @param pcs the instances to detach
1117 * @return the detached instances
1118 * @throws JDOUserException if any of the instances to be detached do not
1119 * implement the javax.jdo.spi.Detachable interface.
1120 * @see #makePersistentAll(Object[])
1121 * @see #getFetchPlan
1122 * @since 2.0
1123 */
1124 <T> T[] detachCopyAll (T... pcs);
1125
1126 /**
1127 * Put the specified key-value pair into the map of user objects.
1128 * @since 2.0
1129 */
1130 Object putUserObject (Object key, Object val);
1131
1132 /**
1133 * Get the value for the specified key from the map of user objects.
1134 * @param key the key of the object to be returned
1135 * @return the object
1136 * @since 2.0
1137 */
1138 Object getUserObject (Object key);
1139
1140 /**
1141 * Remove the specified key and its value from the map of user objects.
1142 * @param key the key of the object to be removed
1143 * @since 2.0
1144 */
1145 Object removeUserObject (Object key);
1146
1147 /**
1148 * Flushes all dirty, new, and deleted instances to the data
1149 * store. It has no effect if a transaction is not active.
1150 * <p>If a datastore transaction is active, this method
1151 * synchronizes the cache with the datastore and reports any
1152 * exceptions.</p>
1153 * <p>If an optimistic transaction is active, this method obtains
1154 * a datastore connection, synchronizes the cache with the
1155 * datastore using this connection and reports any
1156 * exceptions. The connection obtained by this method is held
1157 * until the end of the transaction.</p>
1158 * <p>If exceptions occur during flush, the implementation will
1159 * set the current transaction's <code>RollbackOnly</code> flag
1160 * (see {@link Transaction#setRollbackOnly}).</p>
1161 * @since 2.0
1162 */
1163 void flush ();
1164
1165 /**
1166 * Validates the <code>PersistenceManager</code> cache with the
1167 * datastore. This method has no effect if a transaction is not
1168 * active.
1169 * <p>If a datastore transaction is active, this method verifies
1170 * the consistency of instances in the cache against the
1171 * datastore. An implementation might flush instances as if
1172 * {@link #flush} were called, but it is not required to do
1173 * so.</p>
1174 * <p>If an optimistic transaction is active, this method obtains
1175 * a datastore connection and verifies the consistency of the
1176 * instances in the cache against the datastore. If any
1177 * inconsistencies are detected, a {@link
1178 * JDOOptimisticVerificationException} is thrown. This exception
1179 * contains a nested {@link JDOOptimisticVerificationException}
1180 * for each object that failed the consistency check. No
1181 * datastore resources acquired during the execution of this
1182 * method are held beyond the scope of this method.</p>
1183 * @since 2.0
1184 */
1185 void checkConsistency ();
1186
1187 /**
1188 * Returns the <code>FetchPlan</code> used by this
1189 * <code>PersistenceManager</code>.
1190 * @return the FetchPlan
1191 * @since 2.0
1192 */
1193 FetchPlan getFetchPlan ();
1194
1195 /**
1196 * Creates an instance of a persistence-capable interface,
1197 * or of a concrete or abstract class.
1198 * The returned instance is transient.
1199 * @param pcClass Must be a persistence-capable interface,
1200 * or a concrete or abstract class that is declared in the metadata.
1201 * @return the created instance
1202 * @since 2.0
1203 */
1204 <T> T newInstance (Class<T> pcClass);
1205
1206 /**
1207 * Returns the sequence identified by <code>name</code>.
1208 * @param name the name of the Sequence
1209 * @return the Sequence
1210 * @since 2.0
1211 */
1212 Sequence getSequence (String name);
1213
1214 /**
1215 * If this method is called while a datastore transaction is
1216 * active, the object returned will be enlisted in the current
1217 * transaction. If called in an optimistic transaction or outside
1218 * an active transaction, the object returned will not be
1219 * enlisted in any transaction.
1220 * @return the JDOConnection instance
1221 * @since 2.0
1222 */
1223 JDOConnection getDataStoreConnection ();
1224
1225 /**
1226 * Adds the listener instance to the list of lifecycle event
1227 * listeners. The <code>classes</code> parameter identifies all
1228 * of the classes of interest. If the <code>classes</code>
1229 * parameter is specified as <code>null</code>, events for all
1230 * persistent classes and interfaces will be sent to
1231 * <code>listenerInstance</code>.
1232 * <p>The listenerInstance will be called for each event for which it
1233 * implements the corresponding listenerInstance interface.</p>
1234 * @param listener the lifecycle listener
1235 * @param classes the classes of interest to the listener
1236 * @since 2.0
1237 */
1238 void addInstanceLifecycleListener (InstanceLifecycleListener listener,
1239 Class... classes);
1240
1241 /**
1242 * Removes the listener instance from the list of lifecycle event listeners.
1243 * @param listener the listener instance to be removed
1244 * @since 2.0
1245 */
1246 void removeInstanceLifecycleListener (InstanceLifecycleListener listener);
1247
1248 /**
1249 * Get the Date as seen by the server.
1250 * Clients using this method can order their operations according to
1251 * a single time source. Implementations use the setting of the
1252 * server time zone to prepare a Date instance that represents
1253 * UTC time on the server.
1254 * @return a Date instance corresponding to the UTC Date
1255 * as seen by the server
1256 * @since 2.1
1257 */
1258 Date getServerDate();
1259
1260 /**
1261 * Get the objects managed by this persistence manager.
1262 * @return the objects
1263 * @since 2.1
1264 */
1265 Set getManagedObjects();
1266
1267 /**
1268 * Get the objects managed by this persistence manager having the
1269 * specified object states.
1270 * @param states The states of objects that we are interested in
1271 * @return the objects
1272 * @since 2.1
1273 */
1274 Set getManagedObjects(EnumSet<ObjectState> states);
1275
1276 /**
1277 * Get the objects managed by this persistence manager being instances of
1278 * the specified classes.
1279 * @param classes The classes of objects that we are interested in
1280 * @return the objects
1281 * @since 2.1
1282 */
1283 Set getManagedObjects(Class... classes);
1284
1285 /**
1286 * Get the objects managed by this persistence manager having the
1287 * specified object states and being instances of the specified classes.
1288 * @param states The states of objects that we are interested in
1289 * @param classes The classes of objects that we are interested in
1290 * @return the objects
1291 * @since 2.1
1292 */
1293 Set getManagedObjects(EnumSet<ObjectState> states, Class... classes);
1294
1295 /**
1296 * Get a modifiable <code>FetchGroup</code> for the Class and name.
1297 * If a modifiable <code>FetchGroup</code> already exists in the
1298 * <code>PersistenceManager</code> scope, return it.
1299 * If not, create and populate a new <code>FetchGroup</code> from the
1300 * existing definition in the {@link PersistenceManager} or
1301 * {@link PersistenceManagerFactory}. If the definition for the
1302 * <code>FetchGroup</code> is not in scope in either the
1303 * <code>PersistenceManager</code> or
1304 * <code>PersistenceManagerFactory</code>, create it with no members.
1305 * The <code>FetchGroup</code> immediately
1306 * becomes active and in scope of the PersistenceManager, and hides
1307 * the corresponding fetch group in the PersistenceManagerFactory.
1308 * @param cls the class or interface for the <code>FetchGroup</code>
1309 * @param name the name of the fetch group
1310 * @return the FetchGroup
1311 * @throws JDOUserException if the class is not a persistence-capable
1312 * class or interface
1313 * @since 2.2
1314 */
1315 FetchGroup getFetchGroup(Class cls, String name);
1316 }