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