001: /**********************************************************************
002: Copyright (c) 2002 Kelly Grizzle (TJDO) and others. All rights reserved.
003: Licensed under the Apache License, Version 2.0 (the "License");
004: you may not use this file except in compliance with the License.
005: You may obtain a copy of the License at
006:
007: http://www.apache.org/licenses/LICENSE-2.0
008:
009: Unless required by applicable law or agreed to in writing, software
010: distributed under the License is distributed on an "AS IS" BASIS,
011: WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
012: See the License for the specific language governing permissions and
013: limitations under the License.
014:
015: Contributors:
016: 2003 Erik Bengtson - added getObjectByAID
017: 2004 Andy Jefferson - added MetaDataManager
018: 2005 Andy Jefferson - javadocs
019: ...
020: **********************************************************************/package org.jpox;
021:
022: import java.util.Collection;
023: import java.util.Set;
024:
025: import org.jpox.api.ApiAdapter;
026: import org.jpox.exceptions.ClassNotPersistableException;
027: import org.jpox.exceptions.JPOXOptimisticException;
028: import org.jpox.exceptions.NoPersistenceInformationException;
029: import org.jpox.metadata.MetaDataManager;
030: import org.jpox.state.CallbackHandler;
031: import org.jpox.state.FetchPlanState;
032: import org.jpox.store.FieldValues;
033: import org.jpox.store.StoreManager;
034:
035: /**
036: * Definition of an ObjectManager.
037: * Provides the basics of object persistence within JPOX Core, upon which are built
038: * javax.jdo.PersistenceManager and javax.persistence.EntityManager.
039: *
040: * @version $Revision: 1.40 $
041: **/
042: public interface ObjectManager {
043: /**
044: * Method to return the owner object.
045: * For JDO this will return the PersistenceManager owning this ObjectManager.
046: * For JPA this will return the EntityManager owning this ObjectManager.
047: * @return The owner manager object
048: */
049: Object getOwner();
050:
051: /**
052: * Method to close the ObjectManager.
053: */
054: void close();
055:
056: /**
057: * Accessor for whether this ObjectManager is closed.
058: * @return Whether this manager is closed.
059: */
060: boolean isClosed();
061:
062: /**
063: * Accessor for the current transaction for this ObjectManager.
064: * @return The current transaction
065: */
066: Transaction getTransaction();
067:
068: /**
069: * Accessor for the Store Manager.
070: * @return Store Manager
071: */
072: StoreManager getStoreManager();
073:
074: /**
075: * Accessor for the MetaData Manager.
076: * @return The MetaData Manager
077: */
078: MetaDataManager getMetaDataManager();
079:
080: /**
081: * Accessor for the context in which this ObjectManager is running.
082: * @return Returns the context.
083: */
084: OMFContext getOMFContext();
085:
086: /**
087: * Accessor for the API adapter.
088: * @return API adapter.
089: */
090: ApiAdapter getApiAdapter();
091:
092: /**
093: * Acessor for the current FetchPlan
094: * @return FetchPlan
095: */
096: FetchPlan getFetchPlan();
097:
098: /**
099: * Accessor for whether to ignore the cache.
100: * @return Whether to ignore the cache.
101: */
102: boolean getIgnoreCache();
103:
104: /**
105: * Accessor for whether the ObjectManager will detach all objects on commit
106: * @return Whether we detach all on commit
107: */
108: public boolean getDetachAllOnCommit();
109:
110: /**
111: * Accessor for whether the ObjectManager should copy on attaching.
112: * @return Whether we copy on attaching
113: */
114: public boolean getCopyOnAttach();
115:
116: /**
117: * Accessor for whether the ObjectManager is multithreaded
118: * @return Whether the ObjectManager is multithreaded
119: */
120: public boolean getMultithreaded();
121:
122: /**
123: * Method to set DetachAllOnCommit.
124: * @param flag Whether to detach all objects on commit of the transaction.
125: */
126: public void setDetachAllOnCommit(boolean flag);
127:
128: /**
129: * Method whether to copy on attaching.
130: * @param flag Whether to copy on attaching.
131: */
132: public void setCopyOnAttach(boolean flag);
133:
134: /**
135: * Method to set whether to ignore the L1 cache.
136: * @param ignore Whether to ignore the L1 cache
137: */
138: public void setIgnoreCache(boolean ignore);
139:
140: /**
141: * Method to set whether the ObjectManager should operate multithreaded
142: * @param multi Whether to operate multithreaded
143: */
144: public void setMultithreaded(boolean multi);
145:
146: /**
147: * Method to set DetachOnClose.
148: * @param flag Whether to detach all objects on close of the ObjectManager.
149: */
150: void setDetachOnClose(boolean flag);
151:
152: /**
153: * Accessor for the ClassLoader resolver to use in class loading issues.
154: * @return The ClassLoader resolver
155: */
156: ClassLoaderResolver getClassLoaderResolver();
157:
158: /**
159: * Retrieve the callback handler for this PM
160: * @return the callback handler
161: */
162: CallbackHandler getCallbackHandler();
163:
164: /**
165: * Convenience method to assert if the passed class is not persistable.
166: * @param cls The class of which we want to persist objects
167: * @throws ClassNotPersistableException When the class is not persistable
168: * @throws NoPersistenceInformationException When the class has no available persistence information
169: */
170: void assertClassPersistable(Class cls);
171:
172: /**
173: * Utility method to check if the specified class has reachable metadata or annotations.
174: * @param cls The class to check
175: * @return Whether the class has reachable metadata or annotations
176: */
177: public boolean hasPersistenceInformationForClass(Class cls);
178:
179: // -------------------------- Object Persistence operations --------------------------------
180:
181: /**
182: * Method to evict the passed object.
183: * @param pc The object
184: */
185: void evictObject(Object pc);
186:
187: /**
188: * Method to evict all objects of the specified type (and optionaly its subclasses).
189: * @param cls Type of persistable object
190: * @param subclasses Whether to include subclasses
191: */
192: void evictObjects(Class cls, boolean subclasses);
193:
194: /**
195: * Method to evict all L1 cache objects
196: */
197: void evictAllObjects();
198:
199: /**
200: * Method to refresh the passed object.
201: * @param pc The object
202: */
203: void refreshObject(Object pc);
204:
205: /**
206: * Method to refresh all L1 cache objects
207: */
208: void refreshAllObjects();
209:
210: /**
211: * Method to retrieve the passed object.
212: * @param pc The object
213: * @param fgOnly Just retrieve the current fetch group
214: */
215: void retrieveObject(Object pc, boolean fgOnly);
216:
217: /**
218: * Method to persist the passed object.
219: * @param pc The object
220: * @return The persisted object
221: */
222: Object persistObject(Object pc);
223:
224: /**
225: * Method to persist the passed object (internally).
226: * @param pc The object
227: * @param preInsertChanges Changes to be made before inserting
228: * @param ownerSM StateManager of the owner when embedded
229: * @param ownerFieldNum Field number in the owner where this is embedded (or -1 if not embedded)
230: * @param objectType Type of object (see org.jpox.StateManager, e.g StateManager.PC)
231: * @return The persisted object
232: */
233: Object persistObjectInternal(Object pc,
234: FieldValues preInsertChanges, StateManager ownerSM,
235: int ownerFieldNum, int objectType);
236:
237: /**
238: * Method to make transient the passed object.
239: * @param pc The object
240: * @param state Object containing the state of the fetchplan processing
241: */
242: void makeObjectTransient(Object pc, FetchPlanState state);
243:
244: /**
245: * Method to make the passed object transactional.
246: * @param pc The object
247: */
248: void makeObjectTransactional(Object pc);
249:
250: /**
251: * Method to make the passed object nontransactional.
252: * @param pc The object
253: */
254: void makeObjectNontransactional(Object pc);
255:
256: /**
257: * Method to delete an object from the datastore.
258: * @param obj The object
259: */
260: void deleteObject(Object obj);
261:
262: /**
263: * Method to delete the passed object (internally).
264: * @param pc The object
265: */
266: void deleteObjectInternal(Object pc);
267:
268: /**
269: * Method to delete an array of objects from the datastore.
270: * @param objs The objects to delete
271: */
272: void deleteObjects(Object[] objs);
273:
274: /**
275: * Method to delete a collection of objects from the datastore.
276: * @param objs The objects to delete
277: */
278: void deleteObjects(Collection objs);
279:
280: /**
281: * Method to attach the passed object (and related objects).
282: * Throws an exception if another (persistent) object with the same id exists in the L1 cache already.
283: * @param pc The (detached) object
284: * @param sco Whether the object has no identity (embedded or serialised)
285: */
286: void attachObject(Object pc, boolean sco);
287:
288: /**
289: * Method to attach a copy of the passed object (and related objects).
290: * @param pc The object
291: * @param sco Whether it has no identity (second-class object)
292: * @return The attached copy of the input object
293: */
294: Object attachObjectCopy(Object pc, boolean sco);
295:
296: /**
297: * Method to detach the passed object.
298: * @param pc The object to detach
299: * @param state State for the detachment process.
300: */
301: void detachObject(Object pc, FetchPlanState state);
302:
303: /**
304: * Method to detach a copy of the passed object using the provided state.
305: * @param pc The object
306: * @param state State for the detachment process
307: * @return The detached copy of the object
308: */
309: Object detachObjectCopy(Object pc, FetchPlanState state);
310:
311: /**
312: * Method to detach all objects in the PM.
313: */
314: void detachAll();
315:
316: /**
317: * Method to return if the specified object exists in the datastore.
318: * @param obj The (persistable) object
319: * @return Whether it exists
320: */
321: boolean exists(Object obj);
322:
323: /**
324: * Accessor for the currently managed objects for the current transaction.
325: * If the transaction is not active this returns null.
326: * @return Collection of managed objects enlisted in the current transaction
327: */
328: Set getManagedObjects();
329:
330: /**
331: * Accessor for the currently managed objects for the current transaction.
332: * If the transaction is not active this returns null.
333: * @param classes Classes that we want the objects for
334: * @return Collection of managed objects enlisted in the current transaction
335: */
336: Set getManagedObjects(Class[] classes);
337:
338: /**
339: * Accessor for the currently managed objects for the current transaction.
340: * If the transaction is not active this returns null.
341: * @param states States that we want the objects for
342: * @return Collection of managed objects enlisted in the current transaction
343: */
344: Set getManagedObjects(String[] states);
345:
346: /**
347: * Accessor for the currently managed objects for the current transaction.
348: * If the transaction is not active this returns null.
349: * @param states States that we want the objects for
350: * @param classes Classes that we want the objects for
351: * @return Collection of managed objects enlisted in the current transaction
352: */
353: Set getManagedObjects(String[] states, Class[] classes);
354:
355: /**
356: * Accessor for an object given the object id.
357: * @param id Id of the object.
358: * @param fv the FieldValues
359: * @return the Object
360: */
361: Object findObject(Object id, FieldValues fv);
362:
363: /**
364: * Accessor for an object given the object id.
365: * @param id Id of the object.
366: * @param validate Whether to validate the object state
367: * @param checkInheritance Whether look to the database to determine which
368: * class this object is. This parameter is a hint. Set false, if it's
369: * already determined the correct pcClass for this pc "object" in a certain
370: * level in the hierarchy. Set to true and it will look to the database.
371: * @param objectClassName Class name for the object with this id (if known, optional)
372: * @return The Object
373: */
374: Object findObject(Object id, boolean validate,
375: boolean checkInheritance, String objectClassName);
376:
377: /**
378: * Accessor for an object given the object id.
379: * @param id Id of the object.
380: * @param fv the FieldValues
381: * @param pcClass the type which the object is. This type will be used to instanciat the object
382: * @param ignoreCache true if the cache is ignored
383: * @return the Object
384: */
385: Object findObject(Object id, FieldValues fv, Class pcClass,
386: boolean ignoreCache);
387:
388: /**
389: * Accessor for an object given the object id. The object uses application identity
390: * @param fv the FieldValues containing at minimum the primary key fields
391: * @param pcClass the type which the object is
392: * @param ignoreCache true if the cache is ignored
393: * @param checkInheritance true if the cache is ignored
394: * @return the Object
395: */
396: Object findObjectUsingAID(Class pcClass, FieldValues fv,
397: boolean ignoreCache, boolean checkInheritance);
398:
399: /**
400: * This method returns an object id instance corresponding to the pcClass and key arguments.
401: * Operates in 2 modes :-
402: * <ul>
403: * <li>The class uses SingleFieldIdentity and the key is the value of the key field</li>
404: * <li>In all other cases the key is the String form of the object id instance</li>
405: * </ul>
406: * @param pcClass Class of the PersistenceCapable to create the identity for
407: * @param key Value of the key for SingleFieldIdentity (or the toString value)
408: * @return The new object-id instance
409: */
410: Object newObjectId(Class pcClass, Object key);
411:
412: /**
413: * Method to generate an instance of an interface, abstract class, or concrete PC class.
414: * @param persistenceCapable The class of the interface or abstract class, or concrete class defined in MetaData
415: * @return The instance of this type
416: */
417: Object newInstance(Class persistenceCapable);
418:
419: /**
420: * Method to enlist the specified StateManager in the current transaction.
421: * @param sm The StateManager
422: */
423: void enlistInTransaction(StateManager sm);
424:
425: /**
426: * Method to evict the specified StateManager from the current transaction.
427: * @param sm The StateManager
428: */
429: void evictFromTransaction(StateManager sm);
430:
431: /**
432: * Method to return if an object is enlisted in the current transaction.
433: * @param id Identity for the object
434: * @return Whether it is enlisted in the current transaction
435: */
436: boolean isEnlistedInTransaction(Object id);
437:
438: /**
439: * Method to find the StateManager for the passed persistable object when it is managed by this manager.
440: * @param pc The persistable object
441: * @return The StateManager
442: */
443: StateManager findStateManager(Object pc);
444:
445: /**
446: * Method to register the StateManager as being for the passed object.
447: * Used during the process of identifying StateManager for persistable object.
448: * @param sm The StateManager
449: * @param pc The object managed by the StateManager
450: */
451: void hereIsStateManager(StateManager sm, Object pc);
452:
453: /**
454: * Method to add the object managed by the specified StateManager to the cache.
455: * @param sm The StateManager
456: */
457: void addStateManager(StateManager sm);
458:
459: /**
460: * Method to remove the object managed by the specified StateManager from the cache.
461: * @param sm The StateManager
462: */
463: void removeStateManager(StateManager sm);
464:
465: /**
466: * Accessor for the StateManager of an object given the object id.
467: * @param myID Id of the object.
468: * @return The StateManager
469: */
470: StateManager getStateManagerById(Object myID);
471:
472: /**
473: * Mark the specified StateManager as dirty
474: * @param sm The StateManager
475: * @param directUpdate Whether the object has had a direct update made on it (if known)
476: */
477: void markDirty(StateManager sm, boolean directUpdate);
478:
479: /**
480: * Mark the specified StateManager as clean.
481: * @param sm The StateManager
482: */
483: void clearDirty(StateManager sm);
484:
485: /**
486: * Method to mark as clean all StateManagers of dirty objects.
487: */
488: void clearDirty();
489:
490: /**
491: * Method to mark the specified StateManager as needing an update due to managed relation constraints.
492: * @param sm The StateManager
493: */
494: void markManagedRelationDirty(StateManager sm);
495:
496: /**
497: * Returns whether this ObjectManager is currently performing the manage relationships task.
498: * @return Whether in the process of managing relations
499: */
500: boolean isManagingRelations();
501:
502: /**
503: * Tests whether this persistable object is being inserted.
504: * @param pc the object to verify the status
505: * @return true if this instance is inserting.
506: */
507: boolean isInserting(Object pc);
508:
509: /**
510: * Convenience method to find if the specified field of the specified object has been inserted yet.
511: * @param pc The object
512: * @param fieldNumber The absolute field number
513: * @return Whether it has been inserted into the datastore
514: */
515: boolean isInserted(Object pc, int fieldNumber);
516:
517: /**
518: * Convenience method to find if the specified object is inserted down to the specified class level yet.
519: * @param pc The object
520: * @param className Name of the class that we want to check the insertion level to
521: * @return Whether it has been inserted into the datastore
522: */
523: boolean isInserted(Object pc, String className);
524:
525: /**
526: * Whether the datastore operations are delayed until commit.
527: * In optimistic transactions this is automatically enabled.
528: * @return true if datastore operations are delayed until commit
529: */
530: boolean isDelayDatastoreOperationsEnabled();
531:
532: /**
533: * Method called during the rollback process, after the actual datastore rollback.
534: */
535: public void preRollback();
536:
537: /**
538: * Method called during the begin process, after the actual begin.
539: */
540: public void postBegin();
541:
542: /**
543: * Method called during the commit process, before the actual datastore commit.
544: */
545: public void preCommit();
546:
547: /**
548: * Method called during the commit process, after the actual datastore commit.
549: */
550: public void postCommit();
551:
552: /**
553: * Method called during the close process.
554: */
555: void postClose();
556:
557: /**
558: * Method callable from external APIs for user-management of flushing.
559: * Called by JDO PM.flush, or JPA EM.flush().
560: * Performs management of relations, prior to performing internal flush of all dirty/new/deleted
561: * instances to the datastore.
562: */
563: void flush();
564:
565: /**
566: * Method to flushes all dirty, new, and deleted instances to the datastore.
567: * It has no effect if a transaction is not active.
568: * If a datastore transaction is active, this method synchronizes the cache with
569: * the datastore and reports any exceptions.
570: * If an optimistic transaction is active, this method obtains a datastore connection
571: * and synchronizes the cache with the datastore using this connection.
572: * The connection obtained by this method is held until the end of the transaction.
573: * @param flushToDatastore Whether to ensure any changes reach the datastore
574: * Otherwise they will be flushed to the datastore manager and leave it to
575: * decide the opportune moment to actually flush them to teh datastore
576: * @throws JPOXOptimisticException when optimistic locking error(s) occur
577: */
578: void flushInternal(boolean flushToDatastore);
579:
580: /**
581: * Accessor for whether the ObjectManager is flushing changes to the datastore.
582: * @return Whether it is currently flushing
583: */
584: boolean isFlushing();
585:
586: /**
587: * Accessor for whether this ObjectManager is currently running detachAllOnCommit.
588: * @return Whether running detachAllOnCommit
589: */
590: boolean isRunningDetachAllOnCommit();
591:
592: // -------------------------------- Query Support -------------------------------------
593:
594: /**
595: * Accessor for a new Query.
596: * @return The new Query
597: */
598: org.jpox.store.query.Query newQuery();
599:
600: /**
601: * Accessor for the Extent for a class (and optionally its subclasses).
602: * @param candidateClass The class
603: * @param includeSubclasses Whether to include subclasses
604: * @return The Extent
605: */
606: org.jpox.store.Extent getExtent(Class candidateClass,
607: boolean includeSubclasses);
608:
609: // --------------------------------- Caching ---------------------------------------
610:
611: /**
612: * Replace the previous object id for a PC object to a new
613: * @param pc The Persistable object
614: * @param oldID the old id
615: * @param newID the new id
616: */
617: void replaceObjectId(Object pc, Object oldID, Object newID);
618:
619: /**
620: * Method to put a Persistable object associated to the StateManager into the respective cache(s).
621: * @param sm The State Manager
622: * @param level1 Whether to put in the L1 cache
623: * @param level2 Whether to put in the L2 cache
624: */
625: void putObjectIntoCache(StateManager sm, boolean level1,
626: boolean level2);
627:
628: /**
629: * Method to remove an object from the respective cache(s).
630: * @param pc The object
631: * @param id The id of the object
632: * @param level1 Whether to remove from the L1 cache
633: * @param level2 Whether to remove from the L2 cache
634: */
635: void removeObjectFromCache(Object pc, Object id, boolean level1,
636: boolean level2);
637:
638: /**
639: * Convenience method to access an object in the cache.
640: * Firstly looks in the L1 cache for this PM, and if not found looks in the L2 cache.
641: * @param id Id of the object
642: * @return Persistable object (with connected StateManager).
643: */
644: public Object getObjectFromCache(Object id);
645:
646: /**
647: * Disconnect SM instances, clear cache and reset settings
648: */
649: public void disconnectSMCache();
650:
651: // -------------------------------- Callback Interface --------------------------------------
652:
653: /**
654: * Listener of ObjectManager events
655: */
656: public interface ObjectManagerListener {
657: /**
658: * Invoked before closing the ObjectManager
659: * @param om the ObjectManager being closed
660: */
661: void objectManagerPreClose(ObjectManager om);
662: }
663:
664: /**
665: * Method to register a listener for instances of the specified classes.
666: * @param listener The listener to sends events to
667: * @param classes The classes that it is interested in
668: */
669: void addListener(Object listener, Class[] classes);
670:
671: /**
672: * Method to remove a currently registered listener.
673: * @param listener The instance lifecycle listener to remove.
674: */
675: void removeListener(Object listener);
676:
677: /**
678: * Disconnect the registered LifecycleListener
679: */
680: public void disconnectLifecycleListener();
681: }
|