001 package com.sptci.jdo;
002
003 import java.util.Collection;
004
005 import javax.jdo.Extent;
006 import javax.jdo.FetchPlan;
007 import javax.jdo.JDOException;
008 import javax.jdo.PersistenceManagerFactory;
009 import javax.jdo.Query;
010 import javax.jdo.Transaction;
011
012 import javax.jdo.datastore.JDOConnection;
013 import javax.jdo.datastore.Sequence;
014 import javax.jdo.listener.InstanceLifecycleListener;
015
016 /** A proxy around a <code>javax.jdo.PersistenceManager</code> used
017 * to ensure a <code>singleton PersistenceManager</code> instance for
018 * the entire application.
019 *
020 * @see PersistenceManagerFactory#getPersistenceManager
021 * @author Rakesh Vidyadharan 05<sup><small>th</small></sup> February, 2006
022 * <p>Copyright 2006, Sans Pareil Technologies, Inc.</p>
023 *
024 * @version $Id: PersistenceManager2.java,v 1.2 2006/02/15 00:48:39 rakesh Exp $
025 */
026 public class PersistenceManager2 implements javax.jdo.PersistenceManager
027 {
028 /**
029 * The <code>PersistenceManager</code> instance that is decorated.
030 */
031 private javax.jdo.PersistenceManager persistenceManager;
032
033 /**
034 * Create a new instance of the decorator using the specified
035 * <code>PersistenceManager</code>
036 *
037 * @param pm The object to decorate.
038 */
039 protected PersistenceManager2( javax.jdo.PersistenceManager pm )
040 {
041 this.persistenceManager = pm;
042 setMultithreaded( true );
043 }
044
045 /**
046 * A <code>PersistenceManager</code> instance can be used until it
047 * is closed.
048 *
049 * @see #close()
050 * @return <code>true</code> if this <code>PersistenceManager</code>
051 * has been closed.
052 */
053 public boolean isClosed()
054 {
055 return persistenceManager.isClosed();
056 }
057
058 /**
059 * Close this <code>PersistenceManager</code> so that no further
060 * requests may be made on it. A <code>PersistenceManager</code>
061 * instance can be used only until it is closed.
062 *
063 * <p>Closing a <code>PersistenceManager</code> might release it
064 * to the pool of available <code>PersistenceManager</code>s, or
065 * might be garbage collected, at the option of the JDO
066 * implementation. Before being used again to satisfy a
067 * <code>getPersistenceManager()</code> request, the default values
068 * for options will be restored to their values as specified in the
069 * <code>PersistenceManagerFactory</code>.</p>
070 *
071 * <p>This method closes the <code>PersistenceManager</code>.</p>
072 *
073 * <p><b>Note:</b> Over-ridden to never close the decorated
074 * <code>PersistenceManager</code>. To close the persistence manager
075 * execute {@link #getPersistenceManager}.close()</p>
076 */
077 public void close() {}
078
079 /**
080 * Return the <code>Transaction</code> instance associated with a
081 * <code>PersistenceManager</code>. There is one
082 * <code>Transaction</code> instance associated with each
083 * <code>PersistenceManager</code> instance. The
084 * <code>Transaction</code> instance supports options as well as
085 * transaction completion requests.
086 *
087 * @return the <code>Transaction</code> associated with this
088 * <code>PersistenceManager</code>.
089 */
090 public Transaction currentTransaction()
091 {
092 return persistenceManager.currentTransaction();
093 }
094
095 /**
096 * Mark an instance as no longer needed in the cache. Eviction is
097 * normally done automatically by the <code>PersistenceManager</code>
098 * at transaction completion. This method allows the application to
099 * explicitly provide a hint to the <code>PersistenceManager</code>
100 * that the instance is no longer needed in the cache.
101 *
102 * @param pc the instance to evict from the cache.
103 */
104 public void evict( Object pc )
105 {
106 persistenceManager.evict( pc );
107 }
108
109 /**
110 * Mark an array of instances as no longer needed in the cache.
111 *
112 * @see #evict(Object)
113 * @param pcs the array of instances to evict from the cache.
114 */
115 public void evictAll( Object[] pcs )
116 {
117 persistenceManager.evictAll( pcs );
118 }
119
120 /**
121 * Mark a <code>Collection</code> of instances as no longer needed in
122 * the cache.
123 *
124 * @see #evict(Object)
125 * @param pcs the <code>Collection</code> of instances to evict from
126 * the cache.
127 */
128 public void evictAll( Collection pcs )
129 {
130 persistenceManager.evictAll( pcs );
131 }
132
133 /**
134 * Mark all persistent-nontransactional instances as no longer needed
135 * in the cache. It transitions all persistent-nontransactional
136 * instances to hollow. Transactional instances are subject to
137 * eviction based on the RetainValues setting.
138 *
139 * @see #evict(Object)
140 */
141 public void evictAll()
142 {
143 persistenceManager.evictAll();
144 }
145
146 /**
147 * Refresh the state of the instance from the data store.
148 *
149 * <p>In an optimistic transaction, the state of instances in the
150 * cache might not match the state in the data store. This method
151 * is used to reload the state of the instance from the data store
152 * so that a subsequent commit is more likely to succeed.</p>
153 *
154 * <p>Outside a transaction, this method will refresh
155 * nontransactional state.</p>
156 *
157 * @param pc the instance to refresh.
158 */
159 public void refresh( Object pc )
160 {
161 persistenceManager.refresh( pc );
162 }
163
164 /**
165 * Refresh the state of an array of instances from the data store.
166 *
167 * @see #refresh(Object)
168 * @param pcs the array of instances to refresh.
169 */
170 public void refreshAll( Object[] pcs )
171 {
172 persistenceManager.refreshAll( pcs );
173 }
174
175 /**
176 * Refresh the state of a <code>Collection</code> of instances from
177 * the data store.
178 *
179 * @see #refresh(Object)
180 * @param pcs the <code>Collection</code> of instances to refresh.
181 */
182 public void refreshAll( Collection pcs )
183 {
184 persistenceManager.refreshAll( pcs );
185 }
186
187 /**
188 * Refresh the state of all applicable instances from the data store.
189 *
190 * <p>If called with an active transaction, all transactional
191 * instances will be refreshed. If called outside an active
192 * transaction, all nontransactional instances will be refreshed.</p>
193 *
194 * @see #refresh(Object)
195 */
196 public void refreshAll()
197 {
198 persistenceManager.refreshAll();
199 }
200
201 /**
202 * Create a new <code>Query</code> with no elements.
203 *
204 * @return the new <code>Query</code>.
205 */
206 public Query newQuery()
207 {
208 return persistenceManager.newQuery();
209 }
210
211 /**
212 * Create a new <code>Query</code> using elements from another
213 * <code>Query</code>. The other <code>Query</code> must have been
214 * created by the same JDO implementation. It might be active
215 * in a different <code>PersistenceManager</code> or might have been
216 * serialized and restored.
217 *
218 * <p>All of the settings of the other <code>Query</code> are copied
219 * to this <code>Query</code>, except for the candidate
220 * <code>Collection</code> or <code>Extent</code>.</p>
221 *
222 * @return the new <code>Query</code>
223 * @param compiled Another <code>Query</code> from the same JDO
224 * implementation
225 */
226 public Query newQuery( Object compiled )
227 {
228 return persistenceManager.newQuery( compiled );
229 }
230
231 /**
232 * Create a new <code>Query</code> using the specified language.
233 *
234 * @param language the language of the query parameter
235 * @param query the query, which is of a form determined by the
236 * language
237 * @return the new <code>Query</code>
238 */
239 public Query newQuery( String language, Object query )
240 {
241 return persistenceManager.newQuery( language, query );
242 }
243
244 /**
245 * Create a new <code>Query</code> specifying the <code>Class</code>
246 * of the candidate instances.
247 *
248 * @param cls the <code>Class</code> of the candidate instances
249 * @return the new <code>Query</code>
250 */
251 public Query newQuery( Class cls )
252 {
253 return persistenceManager.newQuery( cls );
254 }
255
256 /**
257 * Create a new <code>Query</code> with the <code>Class</code> of the
258 * candidate instances and candidate <code>Extent</code>.
259 *
260 * @param cln the <code>Extent</code> of candidate instances
261 * @return the new <code>Query</code>
262 */
263 public Query newQuery( Extent cln )
264 {
265 return persistenceManager.newQuery( cln );
266 }
267
268 /**
269 * Create a new <code>Query</code> with the candidate
270 * <code>Class</code> and <code>Collection</code>.
271 *
272 * @param cls the <code>Class</code> of results
273 * @param cln the <code>Collection</code> of candidate instances
274 * @return the new <code>Query</code>
275 */
276 public Query newQuery( Class cls, Collection cln )
277 {
278 return persistenceManager.newQuery( cls, cln );
279 }
280
281 /**
282 * Create a new <code>Query</code> with the <code>Class</code> of the
283 * candidate instances and filter.
284 *
285 * @param cls the <code>Class</code> of results
286 * @param filter the filter for candidate instances
287 * @return the new <code>Query</code>
288 */
289 public Query newQuery( Class cls, String filter )
290 {
291 return persistenceManager.newQuery( cls, filter );
292 }
293
294 /**
295 * Create a new <code>Query</code> with the <code>Class</code> of the
296 * candidate instances, candidate <code>Collection</code>, and filter.
297 *
298 * @param cls the <code>Class</code> of candidate instances
299 * @param cln the <code>Collection</code> of candidate instances
300 * @param filter the filter for candidate instances
301 * @return the new <code>Query</code>
302 */
303 public Query newQuery( Class cls, Collection cln, String filter )
304 {
305 return persistenceManager.newQuery( cls, cln, filter );
306 }
307
308 /**
309 * Create a new <code>Query</code> with the candidate
310 * <code>Extent</code> and filter; the class is taken from the
311 * <code>Extent</code>.
312 *
313 * @param cln the <code>Extent</code> of candidate instances
314 * @param filter the filter for candidate instances
315 * @return the new <code>Query</code>
316 */
317 public Query newQuery( Extent cln, String filter )
318 {
319 return persistenceManager.newQuery( cln, filter );
320 }
321
322 /**
323 * The <code>PersistenceManager</code> manages a collection of
324 * instances in the data store based on the class of the instances.
325 * This method returns an <code>Extent</code> of instances in the
326 * data store that might be iterated or given to a <code>Query</code>.
327 * The <code>Extent</code> itself might not reference any instances,
328 * but only hold the class name and an indicator as to whether
329 * subclasses are included in the <code>Extent</code>.
330 *
331 * <p>Note that the <code>Extent</code> might be very large.</p>
332 *
333 * @param persistenceCapableClass <code>Class</code> of instances
334 * @param subclasses whether to include instances of subclasses
335 * @return an <code>Extent</code> of the specified <code>Class</code>
336 */
337 public Extent getExtent( Class persistenceCapableClass,
338 boolean subclasses)
339 {
340 return persistenceManager.getExtent( persistenceCapableClass, subclasses );
341 }
342
343 /**
344 * This method locates a persistent instance in the cache of instances
345 * managed by this <code>PersistenceManager</code>.
346 * The <code>getObjectById</code> method attempts
347 * to find an instance in the cache with the specified JDO identity.
348 * The <code>oid</code> parameter object might have been returned by
349 * an earlier call to <code>getObjectId</code> or
350 * <code>getTransactionalObjectId</code>, or might have been
351 * constructed by the application.
352 *
353 * <p>If the <code>PersistenceManager</code> is unable to resolve the
354 * <code>oid</code> parameter to an ObjectId instance, then it throws
355 * a <code>JDOUserException</code>.</p>
356 *
357 * <p>If the <code>validate</code> flag is <code>false</code>, and
358 * there is already an instance in the cache with the same JDO
359 * identity as the <code>oid</code> parameter, then this method
360 * returns it. There is no change made to the state of the returned
361 * instance.</p>
362 *
363 * <p>If there is not an instance already in the cache with the same
364 * JDO identity as the <code>oid</code> parameter, then this method
365 * creates an instance with the specified JDO identity and returns it.
366 * If there is no transaction in progress, the returned instance will
367 * be hollow or persistent-nontransactional, at the choice of the
368 * implementation.</p>
369 *
370 * <p>If there is a transaction in progress, the returned instance
371 * will be hollow, persistent-nontransactional, or persistent-clean,
372 * at the choice of the implementation.</p>
373 *
374 * <p>It is an implementation decision whether to access the data
375 * store, if required to determine the exact class. This will be the
376 * case of inheritance, where multiple <code>PersistenceCapable</code>
377 * classes share the same ObjectId class.</p>
378 *
379 * <p>If the validate flag is <code>false</code>, and the instance
380 * does not exist in the data store, then this method might not fail.
381 * It is an implementation choice whether to fail immediately with a
382 * <code>JDODataStoreException</code>. But a subsequent access of the
383 * fields of the instance will throw a
384 * <code>JDODataStoreException</code> if the instance does not exist
385 * at that time. Further, if a relationship is established to this
386 * instance, then the transaction in which the association was made
387 * will fail.</p>
388 *
389 * <p>If the <code>validate</code> flag is <code>true</code>, and
390 * there is already a transactional instance in the cache with the
391 * same JDO identity as the <code>oid</code> parameter, then this
392 * method returns it. There is no change made to the state of
393 * the returned instance.</p>
394 *
395 * <p>If there is an instance already in the cache with the same JDO
396 * identity as the <code>oid</code> parameter, but the instance is
397 * not transactional, then it must be verified in the data store. If
398 * the instance does not exist in the datastore, then a
399 * <code>JDODataStoreException</code> is thrown.</p>
400 *
401 * <p>If there is not an instance already in the cache with the same
402 * JDO identity as the <code>oid</code> parameter, then this method
403 * creates an instance with the specified JDO identity, verifies that
404 * it exists in the data store, and returns it. If there is no
405 * transaction in progress, the returned instance will be hollow or
406 * persistent-nontransactional, at the choice of the implementation.</p>
407 *
408 * <p>If there is a data store transaction in progress, the returned
409 * instance will be persistent-clean. If there is an optimistic
410 * transaction in progress, the returned instance will be
411 * persistent-nontransactional.</p>
412 *
413 * @see #getObjectId(Object pc)
414 * @see #getTransactionalObjectId(Object pc)
415 * @return the <code>PersistenceCapable</code> instance with the
416 * specified ObjectId
417 * @param oid an ObjectId
418 * @param validate if the existence of the instance is to be validated
419 */
420 public Object getObjectById( Object oid, boolean validate )
421 {
422 return persistenceManager.getObjectById( oid, validate );
423 }
424
425 /**
426 * The ObjectId returned by this method represents the JDO identity of
427 * the instance. The ObjectId is a copy (clone) of the internal state
428 * of the instance, and changing it does not affect the JDO identity
429 * of the instance.
430 *
431 * <p>The <code>getObjectId</code> method returns an ObjectId
432 * instance that represents the object identity of the specified JDO
433 * instance. The identity is guaranteed to be unique only in the
434 * context of the JDO <code>PersistenceManager</code> that created
435 * the identity, and only for two types of JDO Identity: those that
436 * are managed by the application, and those that are managed by the
437 * data store.</p>
438 *
439 * <p>If the object identity is being changed in the transaction, by
440 * the application modifying one or more of the application key
441 * fields, then this method returns the identity as of the beginning
442 * of the transaction. The value returned by <code>getObjectId</code>
443 * will be different following <code>afterCompletion</code> processing
444 * for successful transactions.</p>
445 *
446 * <p>Within a transaction, the ObjectId returned will compare equal
447 * to the ObjectId returned by only one among all JDO instances
448 * associated with the <code>PersistenceManager</code> regardless of
449 * the type of ObjectId.</p>
450 *
451 * <p>The ObjectId does not necessarily contain any internal state
452 * of the instance, nor is it necessarily an instance of the class
453 * used to manage identity internally. Therefore, if the application
454 * makes a change to the ObjectId instance returned by this method,
455 * there is no effect on the instance from which the ObjectId was
456 * obtained.</p>
457 *
458 * <p>The <code>getObjectById</code> method can be used between
459 * instances of <code>PersistenceManager</code> of different JDO
460 * vendors only for instances of persistence capable classes using
461 * application-managed (primary key) JDO identity. If it is used for
462 * instances of classes using datastore identity, the method might
463 * succeed, but there are no guarantees that the parameter and
464 * return instances are related in any way.</p>
465 *
466 * @see #getTransactionalObjectId(Object pc)
467 * @see #getObjectById(Object oid, boolean validate)
468 * @param pc the <code>PersistenceCapable</code> instance
469 * @return the ObjectId of the instance
470 */
471 public Object getObjectId( Object pc )
472 {
473 return persistenceManager.getObjectId( pc );
474 }
475
476 /**
477 * The ObjectId returned by this method represents the JDO identity of
478 * the instance. The ObjectId is a copy (clone) of the internal state
479 * of the instance, and changing it does not affect the JDO identity
480 * of the instance.
481 *
482 * <p>If the object identity is being changed in the transaction, by
483 * the application modifying one or more of the application key
484 * fields, then this method returns the current identity in the
485 * transaction.</p>
486 *
487 * <p>If there is no transaction in progress, or if none of the key
488 * fields is being modified, then this method will return the same
489 * value as {@link #getObjectId}.</p>
490 *
491 * @see #getObjectId(Object pc)
492 * @see #getObjectById(Object oid, boolean validate)
493 * @param pc a <code>PersistenceCapable</code> instance
494 * @return the ObjectId of the instance
495 */
496 public Object getTransactionalObjectId( Object pc )
497 {
498 return persistenceManager.getTransactionalObjectId( pc );
499 }
500
501 /**
502 * This method returns an object id instance corresponding to the
503 * <code>Class</code> and <code>String</code> arguments. The
504 * <code>String</code> argument might have been the result of
505 * executing <code>toString</code> on an object id instance.
506 *
507 * @param pcClass the <code>Class</code> of the persistence-capable
508 * instance
509 * @param str the <code>String</code> form of the object id
510 * @return an instance of the object identity class
511 */
512 public Object newObjectIdInstance( Class pcClass, String str )
513 {
514 return persistenceManager.newObjectIdInstance( pcClass, str );
515 }
516
517 /**
518 * Make the transient instance persistent in this
519 * <code>PersistenceManager</code>. This method must be called in
520 * an active transaction. The <code>PersistenceManager</code> assigns
521 * an ObjectId to the instance and transitions it to persistent-new.
522 * The instance will be managed in the <code>Extent</code> associated
523 * with its <code>Class</code>. The instance will be put into the
524 * data store at commit. The closure of instances of
525 * <code>PersistenceCapable</code> classes reachable from persistent
526 * fields will be made persistent at commit. [This is known as
527 * persistence by reachability.]
528 *
529 * @param pc a transient instance of a <code>Class</code> that
530 * implements <code>PersistenceCapable</code>
531 */
532 public Object makePersistent( Object pc )
533 {
534 return persistenceManager.makePersistent( pc );
535 }
536
537 /**
538 * Make an array of instances persistent.
539 *
540 * @param pcs an array of transient instances
541 * @see #makePersistent(Object)
542 */
543 public Object[] makePersistentAll (Object[] pcs )
544 {
545 return persistenceManager.makePersistentAll( pcs );
546 }
547
548 /**
549 * Make a <code>Collection</code> of instances persistent.
550 *
551 * @param pcs a <code>Collection</code> of transient instances
552 * @see #makePersistent(Object)
553 */
554 public Collection makePersistentAll( Collection pcs )
555 {
556 return persistenceManager.makePersistentAll( pcs );
557 }
558
559 /**
560 * Delete the persistent instance from the data store.
561 * This method must be called in an active transaction.
562 * The data store object will be removed at commit. Unlike
563 * <code>makePersistent</code>, which makes the closure of the
564 * instance persistent, the closure of the instance is not deleted
565 * from the data store. This method has no effect if the instance is
566 * already deleted in the current transaction. This method throws
567 * <code>JDOUserException</code> if the instance is transient or
568 * is managed by another <code>PersistenceManager</code>.
569 *
570 * @param pc a persistent instance
571 */
572 public void deletePersistent( Object pc )
573 {
574 persistenceManager.deletePersistent( pc );
575 }
576
577 /**
578 * Delete an array of instances from the data store.
579 *
580 * @param pcs a <code>Collection</code> of persistent instances
581 * @see #deletePersistent(Object)
582 */
583 public void deletePersistentAll( Object[] pcs )
584 {
585 persistenceManager.deletePersistent( pcs );
586 }
587
588 /**
589 * Delete a <code>Collection</code> of instances from the data store.
590 *
591 * @param pcs a <code>Collection</code> of persistent instances
592 * @see #deletePersistent(Object)
593 */
594 public void deletePersistentAll( Collection pcs )
595 {
596 persistenceManager.deletePersistentAll( pcs );
597 }
598
599 /**
600 * Make an instance transient, removing it from management by this
601 * <code>PersistenceManager</code>.
602 *
603 * <p>The instance loses its JDO identity and it is no longer
604 * associated with any <code>PersistenceManager</code>. The state of
605 * fields is preserved unchanged.</p>
606 *
607 * @param pc the instance to make transient.
608 */
609 public void makeTransient( Object pc )
610 {
611 persistenceManager.makeTransient( pc );
612 }
613
614 /**
615 * Make an array of instances transient, removing them from management
616 * by this <code>PersistenceManager</code>.
617 *
618 * <p>The instances lose their JDO identity and they are no longer
619 * associated with any <code>PersistenceManager</code>. The state of
620 * fields is preserved unchanged.</p>
621 *
622 * @param pcs the instances to make transient.
623 */
624 public void makeTransientAll( Object[] pcs )
625 {
626 persistenceManager.makeTransientAll( pcs );
627 }
628
629 /**
630 * Make a <code>Collection</code> of instances transient, removing
631 * them from management by this <code>PersistenceManager</code>.
632 *
633 * <p>The instances lose their JDO identity and they are no longer
634 * associated with any <code>PersistenceManager</code>. The state of
635 * fields is preserved unchanged.</p>
636 *
637 * @param pcs the instances to make transient.
638 */
639 public void makeTransientAll( Collection pcs )
640 {
641 persistenceManager.makeTransientAll( pcs );
642 }
643
644 /**
645 * Make an instance subject to transactional boundaries.
646 *
647 * <p>Transient instances normally do not observe transaction
648 * boundaries. This method makes transient instances sensitive to
649 * transaction completion. If an instance is modified in a
650 * transaction, and the transaction rolls back,
651 * the state of the instance is restored to the state before the
652 * first change in the transaction.</p>
653 *
654 * <p>For persistent instances read in optimistic transactions, this
655 * method allows the application to make the state of the instance
656 * part of the transactional state. At transaction commit, the state
657 * of the instance in the cache is compared to the state of the
658 * instance in the data store. If they are not the same, then an
659 * exception is thrown.</p>
660 *
661 * @param pc the instance to make transactional.
662 */
663 public void makeTransactional( Object pc )
664 {
665 persistenceManager.makeTransactional( pc );
666 }
667
668 /**
669 * Make an array of instances subject to transactional boundaries.
670 *
671 * @param pcs the array of instances to make transactional.
672 * @see #makeTransactional(Object)
673 */
674 public void makeTransactionalAll( Object[] pcs )
675 {
676 persistenceManager.makeTransactionalAll( pcs );
677 }
678
679 /**
680 * Make a <code>Collection</code> of instances subject to
681 * transactional boundaries.
682 *
683 * @param pcs the <code>Collection</code> of instances to make
684 * transactional.
685 * @see #makeTransactional(Object)
686 */
687 public void makeTransactionalAll( Collection pcs )
688 {
689 persistenceManager.makeTransactionalAll( pcs );
690 }
691
692 /**
693 * Make an instance non-transactional after commit.
694 *
695 * <p>Normally, at transaction completion, instances are evicted
696 * from the cache. This method allows an application to identify an
697 * instance as not being evicted from the cache at transaction
698 * completion. Instead, the instance remains in the cache with
699 * nontransactional state.</p>
700 *
701 * @param pc the instance to make nontransactional.
702 */
703 public void makeNontransactional( Object pc )
704 {
705 persistenceManager.makeNontransactional( pc );
706 }
707
708 /**
709 * Make an array of instances non-transactional after commit.
710 *
711 * @param pcs the array of instances to make nontransactional.
712 * @see #makeNontransactional(Object)
713 */
714 public void makeNontransactionalAll( Object[] pcs )
715 {
716 persistenceManager.makeNontransactionalAll( pcs );
717 }
718
719 /**
720 * Make a <code>Collection</code> of instances non-transactional
721 * after commit.
722 *
723 * @param pcs the <code>Collection</code> of instances to make
724 * nontransactional.
725 * @see #makeNontransactional(Object)
726 */
727 public void makeNontransactionalAll( Collection pcs )
728 {
729 persistenceManager.makeNontransactionalAll( pcs );
730 }
731
732 /**
733 * Retrieve field values of an instance from the store. This tells
734 * the <code>PersistenceManager</code> that the application intends
735 * to use the instance, and its field values must be retrieved.
736 *
737 * <p>The <code>PersistenceManager</code> might use policy information
738 * about the class to retrieve associated instances.</p>
739 *
740 * @param pc the instance
741 */
742 public void retrieve( Object pc )
743 {
744 persistenceManager.retrieve( pc );
745 }
746
747 /**
748 * Retrieve field values of instances from the store. This tells
749 * the <code>PersistenceManager</code> that the application intends
750 * to use the instances, and all field values must be retrieved.
751 *
752 * <p>The <code>PersistenceManager</code> might use policy information
753 * about the class to retrieve associated instances.</p>
754 *
755 * @param pcs the instances
756 */
757 public void retrieveAll( Collection pcs )
758 {
759 persistenceManager.retrieveAll( pcs );
760 }
761
762 /**
763 * Retrieve field values of instances from the store. This tells
764 * the <code>PersistenceManager</code> that the application intends
765 * to use the instances, and all field values must be retrieved.
766 *
767 * <p>The <code>PersistenceManager</code> might use policy information
768 * about the class to retrieve associated instances.</p>
769 *
770 * @param pcs the instances
771 */
772 public void retrieveAll( Object[] pcs )
773 {
774 persistenceManager.retrieveAll( pcs );
775 }
776
777 /**
778 * The application can manage the <code>PersistenceManager</code>
779 * instances more easily by having an application object associated
780 * with each <code>PersistenceManager</code> instance.
781 *
782 * @param o the user instance to be remembered by the
783 * <code>PersistenceManager</code>
784 * @see #getUserObject
785 */
786 public void setUserObject( Object o )
787 {
788 persistenceManager.setUserObject( o );
789 }
790
791 /**
792 * The application can manage the <code>PersistenceManager</code>
793 * instances more easily by having an application object associated
794 * with each <code>PersistenceManager</code> instance.
795 *
796 * @return the user object associated with this
797 * <code>PersistenceManager</code>
798 * @see #setUserObject
799 */
800 public Object getUserObject()
801 {
802 return persistenceManager.getUserObject();
803 }
804
805 /** This method returns the <code>PersistenceManagerFactory</code>
806 * used to create this <code>PersistenceManager</code>.
807 *
808 * @return the <code>PersistenceManagerFactory</code> that created
809 * this <code>PersistenceManager</code>
810 */
811 public PersistenceManagerFactory getPersistenceManagerFactory()
812 {
813 return persistenceManager.getPersistenceManagerFactory();
814 }
815
816 /**
817 * Return the <code>Class</code> that implements the JDO Identity for
818 * the specified <code>PersistenceCapable</code> class. The
819 * application can use the returned <code>Class</code> to construct a
820 * JDO Identity instance for application identity
821 * <code>PersistenceCapable</code> classes. This JDO Identity
822 * instance can then be used to get an instance of the
823 * <code>PersistenceCapable</code> class for use in the application.
824 *
825 * <p>In order for the application to construct an instance of the
826 * ObjectId class it needs to know the class being used by the JDO
827 * implementation.</p>
828 *
829 * @param cls the <code>PersistenceCapable Class</code>
830 * @return the <code>Class</code> of the ObjectId of the parameter
831 * @see #getObjectById
832 */
833 public Class getObjectIdClass( Class cls )
834 {
835 return persistenceManager.getObjectIdClass( cls );
836 }
837
838 /**
839 * Set the Multithreaded flag for this <code>PersistenceManager</code>.
840 * Applications that use multiple threads to invoke methods or access
841 * fields from instances managed by this <code>PersistenceManager</code>
842 * must set this flag to <code>true</code>. Instances managed by this
843 * <code>PersistenceManager</code> include persistent or
844 * transactional instances of <code>PersistenceCapable</code> classes,
845 * as well as helper instances such as <code>Query</code>,
846 * <code>Transaction</code>, or <code>Extent</code>.
847 *
848 * @param flag the Multithreaded setting.
849 */
850 public void setMultithreaded( boolean flag )
851 {
852 persistenceManager.setMultithreaded( flag );
853 }
854
855 /**
856 * Get the current Multithreaded flag for this
857 * <code>PersistenceManager</code>.
858 *
859 * @see #setMultithreaded
860 * @return the Multithreaded setting.
861 */
862 public boolean getMultithreaded()
863 {
864 return persistenceManager.getMultithreaded();
865 }
866
867 /**
868 * Set the ignoreCache parameter for queries.
869 *
870 * <p>IgnoreCache set to <code>true</code> specifies that for all
871 * <code>Query</code> instances created by this
872 * <code>PersistenceManager</code>, the default is the cache should be
873 * ignored for queries.</p>
874 *
875 * @param flag the ignoreCache setting.
876 */
877 public void setIgnoreCache( boolean flag )
878 {
879 persistenceManager.setIgnoreCache( flag );
880 }
881
882 /**
883 * Get the ignoreCache setting for queries.
884 *
885 * <p>IgnoreCache set to <code>true</code> specifies that for all
886 * <code>Query</code> instances created by this
887 * <code>PersistenceManager</code>, the default is the cache should be
888 * ignored for queries.</p>
889 *
890 * @return the ignoreCache setting.
891 */
892 public boolean getIgnoreCache()
893 {
894 return persistenceManager.getIgnoreCache();
895 }
896
897 /**
898 * Returns {@link #persistenceManager}. This may be used to
899 * force close the <code>PersistenceManager</code> instance this
900 * class decorates.
901 *
902 * @return PersistenceManager The value/reference of/to persistenceManager.
903 */
904 public final javax.jdo.PersistenceManager getPersistenceManager()
905 {
906 return persistenceManager;
907 }
908
909 // JDO 2.0 methods
910
911 /**
912 * Method to register a lifecycle listener as per JDO 2.0 spec 12.15.
913 *
914 * @param listener The instance lifecycle listener to sends events to
915 * @param classes The classes that it is interested in
916 */
917 public void addInstanceLifecycleListener(
918 InstanceLifecycleListener listener, Class[] classes )
919 {
920 persistenceManager.addInstanceLifecycleListener(
921 listener, classes );
922 }
923
924 /**
925 * Method to remove a currently registered lifecycle listener, as per
926 * JDO 2.0 spec 12.15.
927 *
928 * @param listener The instance lifecycle listener to remove.
929 */
930 public void removeInstanceLifecycleListener(
931 InstanceLifecycleListener listener )
932 {
933 persistenceManager.removeInstanceLifecycleListener( listener );
934 }
935
936 /**
937 * Accessor for a connection on the datastore.
938 * See JDO 2.0 spec section 12.16
939 *
940 * @return The JDO connection to the datastore
941 */
942 public JDOConnection getDataStoreConnection()
943 {
944 return persistenceManager.getDataStoreConnection();
945 }
946
947 /**
948 * Method to retrieve a sequence by name.
949 * As per JDO2 spec section 12.14
950 * If the named sequence is not known, throws a JDOUserException.
951 *
952 * @param sequenceName Fully qualified name of the sequence
953 * @return The sequence
954 */
955 public Sequence getSequence( String sequenceName )
956 {
957 return persistenceManager.getSequence( sequenceName );
958 }
959
960 /**
961 * Method to generate an instance of an interface or abstract class.
962 * @param interfaceClass The class of the interface or abstract class
963 * defined in MetaData
964 * @return The instance
965 */
966 public Object newInstance( Class interfaceClass )
967 {
968 return persistenceManager.newInstance( interfaceClass );
969 }
970
971 /**
972 * Acessor for the current FetchPlan
973 *
974 * @return FetchPlan
975 */
976 public FetchPlan getFetchPlan()
977 {
978 return persistenceManager.getFetchPlan();
979 }
980
981 /**
982 * This method validates the cache with the datastore. It has no
983 * effect if a transaction is not active. If a datastore transaction
984 * is active, this method verifies the consistency
985 * of instances in the cache against the datastore. An implementation
986 * might flush instances
987 * as if {@link #flush} were called, but it is not required to do so.
988 * If an optimistic transaction is active, this method obtains a
989 * datastore connection and verifies the consistency of the instances
990 * in the cache against the datastore. If any
991 * inconsistencies are detected, a <code>
992 * JDOOptimisticVerificationException</code> is thrown. This
993 * exception contains a nested <code>
994 * JDOOptimisticVerificationException</code> for each object
995 * that failed the consistency check. No datastore resources acquired
996 * during the execution
997 * of this method are held beyond the scope of this method.
998 */
999 public void checkConsistency()
1000 {
1001 persistenceManager.checkConsistency();
1002 }
1003
1004 /**
1005 * This method flushes all dirty, new, and deleted instances to the
1006 * datastore. It has no effect if a transaction is not active. If a
1007 * datastore transaction is active, this method synchronizes the
1008 * cache with the datastore and reports any exceptions. If an
1009 * optimistic transaction is active, this method obtains a datastore
1010 * connection and synchronizes the
1011 * cache with the datastore using this connection. The connection
1012 * obtained by this method is held until the end of the transaction.
1013 */
1014 public void flush()
1015 {
1016 persistenceManager.flush();
1017 }
1018
1019 /**
1020 * Method to get a user object from the PersistenceManager. This is
1021 * for user objects which are stored under a key. <i>The parameter is
1022 * not inspected or used in any way by the JDO implementation. </i>
1023 *
1024 * @param key The key to store the user object under
1025 * @return The user object for that key
1026 */
1027 public Object getUserObject( Object key )
1028 {
1029 return persistenceManager.getUserObject( key );
1030 }
1031
1032 /**
1033 * Method to put a user object into the PersistenceManager. This is
1034 * so that multiple users can each have a user object for example.
1035 * <i>The parameter is not inspected or used in any way by the JDO
1036 * implementation. </i>
1037 *
1038 * @param key The key to store the user object under
1039 * @param value The object to store
1040 * @return The previous value for this key
1041 */
1042 public Object putUserObject( Object key, Object value )
1043 {
1044 return persistenceManager.putUserObject( key, value );
1045 }
1046
1047 /**
1048 * Method to remove a user object from the PersistenceManager. This is
1049 * for user objects which are stored under a key. <i>The parameter is
1050 * not inspected or used in any way by the JDO implementation. </i>
1051 *
1052 * @param key The key whose uder object is to be removed.
1053 * @return The user object that was removed
1054 */
1055 public Object removeUserObject( Object key )
1056 {
1057 return persistenceManager.removeUserObject( key );
1058 }
1059
1060 /**
1061 * JDO method to detach a persistent object.
1062 * If the object is of class that is not detachable a
1063 * <code>ClassNotDetachableException</code> will be thrown. If the
1064 * object is not persistent a <code>JDOUserException</code> is thrown.
1065 *
1066 * @param pc The object
1067 * @return The detached object
1068 */
1069 public Object detachCopy( Object pc )
1070 {
1071 return persistenceManager.detachCopy( pc );
1072 }
1073
1074 /**
1075 * Detach the specified objects from the <code>PersistenceManager
1076 * </code>. The objects returned can be manipulated and re-attached
1077 * with {@link #makePersistentAll( Object[] )}.
1078 * The detached instances will be unmanaged copies of the specified
1079 * parameters, and are suitable for serialization and manipulation
1080 * outside of a JDO environment. When detaching instances, only
1081 * fields in the current <code>FetchPlan</code> will be
1082 * traversed. Thus, to detach a graph of objects, relations to other
1083 * persistent instances must either be in the
1084 * <code>default-fetch-group</code>, or in the current custom
1085 * <code>FetchPlan</code>.
1086 *
1087 * @param pcs the instances to detach
1088 * @return the detached instances
1089 * @throws JDOUserException if any of the instances do not
1090 * @throws ClassNotDetachableException If any of the objects are of a
1091 * class that is not detachable
1092 */
1093 public Object[] detachCopyAll( Object[] pcs )
1094 {
1095 return persistenceManager.detachCopyAll( pcs );
1096 }
1097
1098 /**
1099 * Detach the specified objects from the <code>PersistenceManager</code>.
1100 *
1101 * @param pcs the instances to detach
1102 * @return the detached instances
1103 * @see #detachCopyAll( Object[] )
1104 */
1105 public Collection detachCopyAll( Collection pcs )
1106 {
1107 return persistenceManager.detachCopyAll( pcs );
1108 }
1109
1110 /**
1111 * Accessor for whether to detach all objects on commit of the
1112 * transaction.
1113 *
1114 * @return Whether to detach all on commit.
1115 */
1116 public boolean getDetachAllOnCommit()
1117 {
1118 return persistenceManager.getDetachAllOnCommit();
1119 }
1120
1121 /**
1122 * Mutator for whether to detach all objects on commit of the
1123 * transaction.
1124 *
1125 * @param flag Whether to detach all on commit.
1126 */
1127 public void setDetachAllOnCommit( boolean flag )
1128 {
1129 persistenceManager.setDetachAllOnCommit( flag );
1130 }
1131
1132 /**
1133 * Method to retrieve the fields of an object.
1134 *
1135 * @param pc The object
1136 * @param fgOnly Whether to retrieve the current fetch group fields only
1137 */
1138 public void retrieve( Object pc, boolean fgOnly )
1139 {
1140 persistenceManager.retrieve( pc, fgOnly );
1141 }
1142
1143 /**
1144 * Retrieve field values of instances from the store. This tells the
1145 * <code>PersistenceManager</code> that the application intends to
1146 * use the instances, and their field values should be retrieved. The
1147 * fields in the current fetch group must be retrieved, and the
1148 * implementation might retrieve more fields than the current fetch
1149 * group.
1150 *
1151 * <p>The <code>PersistenceManager</code> might use policy information
1152 * about the class to retrieve associated instances.</p>
1153 *
1154 * @param pcs the instances
1155 * @param fgOnly whether to retrieve only the current fetch group fields
1156 */
1157 public void retrieveAll( Object[] pcs, boolean fgOnly )
1158 {
1159 persistenceManager.retrieveAll( pcs, fgOnly );
1160 }
1161
1162 /**
1163 * Retrieve field values of instances from the store. This tells the
1164 * <code>PersistenceManager</code> that the application intends to
1165 * use the instances, and their field values should be retrieved. The
1166 * fields in the current fetch group must be retrieved, and the
1167 * implementation might retrieve more fields than the current fetch
1168 * group.
1169 *
1170 * <p>The <code>PersistenceManager</code> might use policy information
1171 * about the class to retrieve associated instances.</p>
1172 *
1173 * @param pcs the instances
1174 * @param fgOnly whether to retrieve only the current fetch-group fields
1175 */
1176 public void retrieveAll( Collection pcs, boolean fgOnly )
1177 {
1178 persistenceManager.retrieveAll( pcs, fgOnly );
1179 }
1180
1181 /**
1182 * Accessor for the objects given the object ids, validating the
1183 * objects.
1184 *
1185 * @param oids Ids of the objects.
1186 * @return The Objects with these ids (in the same order)
1187 */
1188 public Collection getObjectsById(Collection oids)
1189 {
1190 return persistenceManager.getObjectsById( oids );
1191 }
1192
1193 /**
1194 * Accessor for the objects given the object ids, validating the
1195 * objects.
1196 *
1197 * @param oids Ids of the objects.
1198 * @return The Objects with these ids (in the same order)
1199 */
1200 public Object[] getObjectsById( Object[] oids )
1201 {
1202 return persistenceManager.getObjectsById( oids );
1203 }
1204
1205 /**
1206 * Accessor for the objects given the object ids.
1207 *
1208 * @param oids Ids of the objects.
1209 * @param validate Whether to validate the object state
1210 * @return The Objects with these ids (in the same order)
1211 */
1212 public Collection getObjectsById( Collection oids, boolean validate )
1213 {
1214 return persistenceManager.getObjectsById( oids, validate );
1215 }
1216
1217 /**
1218 * Accessor for the objects given the object ids.
1219 *
1220 * @param oids Ids of the objects.
1221 * @param validate Whether to validate the object state
1222 * @return The Objects with these ids (in the same order)
1223 */
1224 public Object[] getObjectsById( Object[] oids, boolean validate )
1225 {
1226 return persistenceManager.getObjectsById( oids, validate );
1227 }
1228
1229 /**
1230 * This method returns an object id instance corresponding to the
1231 * pcClass and key arguments. A String argument might have been the
1232 * result of executing <code>toString</code> on an object id instance.
1233 * The key argument is the value of the key field for single field
1234 * identity. This method is portable for datastore identity and
1235 * application identity.
1236 *
1237 * @param pcClass Class of the PersistenceCapable to create the OID for.
1238 * @param key Value of the key for SingleFieldIdentity
1239 * @return The new object-id instance
1240 */
1241 public Object newObjectIdInstance(Class pcClass, Object key)
1242 {
1243 return persistenceManager.newObjectIdInstance( pcClass, key );
1244 }
1245
1246 /**
1247 * Accessor for an object given the object id.
1248 *
1249 * @param id Id of the object.
1250 * @return The Object
1251 */
1252 public Object getObjectById( Object id )
1253 {
1254 return persistenceManager.getObjectById( id );
1255 }
1256
1257 /**
1258 * Convenience method that exactly matches the behavior of calling
1259 * <code>pm.getObjectById (pm.newObjectIdInstance (cls, key), true)</code>
1260 * for SingleFieldIdentity.
1261 *
1262 * @param cls Class of the PersistenceCapable
1263 * @param key Value of the key field for SingleFieldIdentity
1264 * @return The object for this id.
1265 */
1266 public Object getObjectById( Class cls, Object key )
1267 {
1268 return persistenceManager.getObjectById( cls, key );
1269 }
1270
1271 /**
1272 * Extents are collections of datastore objects managed by the
1273 * datastore, not by explicit user operations on collections. Extent
1274 * capability is a boolean property of classes that are persistence
1275 * capable. If an instance of a class that has a managed extent is
1276 * made persistent via reachability, the instance is put into the
1277 * extent implicitly.
1278 *
1279 * @param pcClass The class to query
1280 * @return returns an Extent that contains all of the instances in the
1281 * parameter class, and all of the instances of the parameter class
1282 * and its subclasses.
1283 */
1284 public Extent getExtent( Class pcClass )
1285 {
1286 return persistenceManager.getExtent( pcClass );
1287 }
1288
1289 /**
1290 * Construct a query instance with the candidate class and the query
1291 * name.
1292 *
1293 * @param cls The class to query
1294 * @param queryName Name of the query.
1295 * @return The query
1296 */
1297 public Query newNamedQuery( Class cls, String queryName )
1298 {
1299 return persistenceManager.newNamedQuery( cls, queryName );
1300 }
1301
1302 /**
1303 * Construct a query instance using the specified Single-String query.
1304 *
1305 * @param query The single-string query
1306 * @return The Query
1307 */
1308 public Query newQuery( String query )
1309 {
1310 return persistenceManager.newQuery( query );
1311 }
1312
1313 /**
1314 * Method to do a refresh of objects that failed verification in the
1315 * exception.
1316 *
1317 * @param exc The JDO exception containing the objects that failed
1318 */
1319 public void refreshAll( JDOException exc )
1320 {
1321 persistenceManager.refreshAll( exc );
1322 }
1323 }