001: /**********************************************************************
002: Copyright (c) 2002 Kelly Grizzle 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:
016: Contributors:
017: 2002 Mike Martin - unknown changes
018: 2003 Erik Bengtson - removed exist() operation
019: 2004 Andy Jefferson - added getHighestFieldNumber()
020: 2005 Andy Jefferson - javadocs
021: 2007 Xuan Baldauf - Contrib of notifyMadePersistentClean() (needed by DB4O plugin).
022: 2007 Xuan Baldauf - Contrib of internalAreAllFieldsLoaded(), internalIsAtLeastOneFieldDirty(), internalIsAtLeastOneFieldDirtyVerify(), createDirtyFieldsBitmapCopy() (needed by DB4O plugin).
023: ...
024: **********************************************************************/package org.jpox;
025:
026: import java.io.PrintWriter;
027: import java.util.Set;
028:
029: import javax.jdo.spi.PersistenceCapable;
030:
031: import org.jpox.cache.CachedPC;
032: import org.jpox.exceptions.JPOXObjectNotFoundException;
033: import org.jpox.metadata.AbstractClassMetaData;
034: import org.jpox.metadata.MetaDataManager;
035: import org.jpox.state.ActivityState;
036: import org.jpox.state.FetchPlanState;
037: import org.jpox.state.RelationshipManager;
038: import org.jpox.store.DatastoreClass;
039: import org.jpox.store.FieldValues;
040: import org.jpox.store.StoreManager;
041: import org.jpox.store.fieldmanager.FieldManager;
042: import org.jpox.store.mapping.JavaTypeMapping;
043:
044: /**
045: * StateManager for JPOX persistent objects. Makes the assumption that a StateManager corresponds to
046: * ONE persistable object.
047: *
048: * @version $Revision: 1.84 $
049: **/
050: public interface StateManager {
051: // Types of PC objects that can be managed by this StateManager
052: /** PC **/
053: public static int PC = 0;
054: /** Embedded (or serialised) PC **/
055: public static int EMBEDDED_PC = 1;
056: /** Embedded (or serialised) Collection Element PC **/
057: public static int EMBEDDED_COLLECTION_ELEMENT_PC = 2;
058: /** Embedded (or serialised) Map Key PC **/
059: public static int EMBEDDED_MAP_KEY_PC = 3;
060: /** Embedded (or serialised) Map Value PC **/
061: public static int EMBEDDED_MAP_VALUE_PC = 4;
062:
063: /**
064: * Initialises a state manager to manage a hollow instance having the given object ID and the given
065: * (optional) field values. This constructor is used for creating new instances of existing persistent
066: * objects, and consequently shouldnt be used when the StoreManager controls the creation of such objects
067: * (such as in an ODBMS).
068: * @param id the identity of the object.
069: * @param fv the initial field values of the object (optional)
070: * @param pcClass Class of the object that this will manage the state for
071: */
072: void initialiseForHollow(Object id, FieldValues fv, Class pcClass);
073:
074: /**
075: * Initialises a state manager to manage a HOLLOW / P_CLEAN instance having the given FieldValues.
076: * This constructor is used for creating new instances of existing persistent objects using application
077: * identity, and consequently shouldnt be used when the StoreManager controls the creation of such objects
078: * (such as in an ODBMS).
079: * @param fv the initial field values of the object.
080: * @param pcClass Class of the object that this will manage the state for
081: */
082: void initialiseForHollowAppId(FieldValues fv, Class pcClass);
083:
084: /**
085: * Initialises a state manager to manage the given hollow instance having the given object ID.
086: * Unlike the {@link #initialiseForHollow} method, this method does not create a new instance and instead
087: * takes a pre-constructed instance.
088: * @param id the identity of the object.
089: * @param pc the object to be managed.
090: */
091: void initialiseForHollowPreConstructed(Object id, Object pc);
092:
093: /**
094: * Initialises a state manager to manage the passed persistent instance having the given object ID.
095: * Used where we have retrieved a PC object from a datastore directly (not field-by-field), for example on
096: * an object datastore. This initialiser will not add StateManagers to all related PCs. This must be done by
097: * any calling process. This simply adds the StateManager to the specified object and records the id, setting
098: * all fields of the object as loaded.
099: * @param id the identity of the object.
100: * @param pc The object to be managed
101: */
102: void initialiseForPersistentClean(Object id, Object pc);
103:
104: /**
105: * Initialises a state manager to manage a PersistenceCapable instance that will be EMBEDDED/SERIALISED
106: * into another PersistenceCapable object. The instance will not be assigned an identity in the process
107: * since it is a SCO.
108: * @param pc The PersistenceCapable to manage (see copyPc also)
109: * @param copyPc Whether the SM should manage a copy of the passed PC or that one
110: */
111: void initialiseForEmbedded(Object pc, boolean copyPc);
112:
113: /**
114: * Initialises a state manager to manage a transient instance that is becoming newly persistent.
115: * A new object ID for the instance is obtained from the store manager and the object is inserted
116: * in the data store.
117: * <p>This constructor is used for assigning state managers to existing
118: * instances that are transitioning to a persistent state.
119: * @param pc the instance being make persistent.
120: * @param preInsertChanges Any changes to make before inserting
121: */
122: void initialiseForPersistentNew(Object pc,
123: FieldValues preInsertChanges);
124:
125: /**
126: * Initialises a state manager to manage a Transactional Transient instance.
127: * A new object ID for the instance is obtained from the store manager and the object is inserted in the data store.
128: * <p>
129: * This constructor is used for assigning state managers to Transient
130: * instances that are transitioning to a transient clean state.
131: * @param pc the instance being make persistent.
132: */
133: void initialiseForTransactionalTransient(Object pc);
134:
135: /**
136: * Initialises the StateManager to manage a PersistenceCapable object in detached state.
137: * @param pc the detach object.
138: * @param id the identity of the object.
139: * @param version the detached version
140: * @since 1.1
141: */
142: void initialiseForDetached(Object pc, Object id, Object version);
143:
144: /**
145: * Initialise to create a StateManager for a PersistenceCapable object, assigning the specified id to the object.
146: * This is used when getting objects out of the L2 Cache, where they have no StateManager assigned, and returning
147: * them as associated with a particular PM.
148: * @param pc The PersistenceCapable object
149: * @param id Id to assign to the PersistenceCapable object
150: * @param loaded The list of loaded fields (when put in the cache)
151: * @param pcClass Class of the object that this will manage the state for
152: */
153: void initialiseForCachedPC(Object pc, Object id, boolean loaded[],
154: Class pcClass);
155:
156: /**
157: * Initialises the StateManager to manage a PersistenceCapable object that is not persistent but that
158: * is about to be deleted. The initial state will be P_NEW, but when the delete call comes in will be
159: * P_NEW_DELETED. The object will not be enlisted in the transaction.
160: * @param pc the object to delete
161: * @since 1.2
162: */
163: void initialiseForPNewToBeDeleted(Object pc);
164:
165: /**
166: * Accessor for the object managed by this StateManager.
167: * @return The object
168: */
169: Object getObject();
170:
171: /**
172: * Accessor for the id of the object managed by this StateManager.
173: * @return The identity of the object
174: */
175: Object getInternalObjectId();
176:
177: /**
178: * return a copy from the object Id
179: * @param obj the persistable object
180: * @return the object id
181: */
182: Object getExternalObjectId(Object obj);
183:
184: /**
185: * Returns the ObjectManager that owns the StateManager instance
186: * @return The ObjectManager
187: */
188: ObjectManager getObjectManager();
189:
190: /**
191: * Accessor for the manager for the store.
192: * @return Store Manager
193: */
194: StoreManager getStoreManager();
195:
196: /**
197: * Accessor for the manager for MetaData.
198: * @return MetaData manager
199: */
200: MetaDataManager getMetaDataManager();
201:
202: /**
203: * Method to mark the specified (absolute) field number as dirty.
204: * @param fieldNumber The (absolute) field number of the field
205: */
206: void makeDirty(int fieldNumber);
207:
208: /**
209: * Accessor for the names of all dirty fields.
210: * @return Names of all dirty fields
211: */
212: String[] getDirtyFieldNames();
213:
214: /**
215: * Accessor for the names of all loaded fields.
216: * @return Names of all loaded fields
217: */
218: String[] getLoadedFieldNames();
219:
220: /**
221: * Marks the given field dirty for issuing an update after the insert.
222: * @param pc The Persistable object
223: * @param fieldNumber The no of field to mark as dirty.
224: */
225: void updateFieldAfterInsert(Object pc, int fieldNumber);
226:
227: /**
228: * Update the acitvity state.
229: * @param activityState the activity state
230: * @param table Datastore class that has just been processed
231: */
232: void changeActivityState(ActivityState activityState,
233: DatastoreClass table);
234:
235: /**
236: * Method to run reachability from this StateManager.
237: * @param reachables List of reachable StateManagers so far
238: */
239: void runReachability(Set reachables);
240:
241: /**
242: * Method to make the managed object transactional.
243: */
244: void makeTransactional();
245:
246: /**
247: * Method to make the managed object nontransactional.
248: */
249: void makeNontransactional();
250:
251: /**
252: * Method to make the managed object transient.
253: * @param state Object containing the state of any fetch plan processing
254: */
255: void makeTransient(FetchPlanState state);
256:
257: /**
258: * Method to make the managed object persistent.
259: */
260: void makePersistent();
261:
262: /**
263: * Method to make Transactional Transient instances persistent
264: */
265: void makePersistentTransactionalTransient();
266:
267: /**
268: * Method to delete the object from persistence.
269: */
270: void deletePersistent();
271:
272: /**
273: * Method to attach to this the detached persistable instance
274: * @param detachedPC the detached persistable instance to be attached
275: * @param embedded Whether it is embedded
276: * @return The attached copy
277: * @since 1.1
278: */
279: Object attachCopy(Object detachedPC, boolean embedded);
280:
281: /**
282: * Method to attach the object managed by this StateManager.
283: * @param embedded Whether it is embedded
284: * @since 1.2
285: */
286: void attach(boolean embedded);
287:
288: /**
289: * Method to make detached copy of this instance
290: * @param state State for the detachment process
291: * @return the detached PersistenceCapable instance
292: * @since 1.1
293: */
294: Object detachCopy(FetchPlanState state);
295:
296: /**
297: * Method to detach the PersistenceCapable object.
298: * @param state State for the detachment process
299: */
300: void detach(FetchPlanState state);
301:
302: /**
303: * Validates whether the persistence capable instance exists in the
304: * datastore. If the instance does not exist in the datastore, this method
305: * will fail raising a JPOXObjectNotFoundException.
306: */
307: void validate();
308:
309: /**
310: * Method to change the object state to evicted.
311: */
312: void evict();
313:
314: /**
315: * Method to refresh the values of the currently loaded fields in the managed object.
316: */
317: void refresh();
318:
319: /**
320: * Method to retrieve the fields for this object.
321: * @param fgOnly Whether to retrieve just the current fetch plan fields
322: */
323: void retrieve(boolean fgOnly);
324:
325: /**
326: * Method to retrieve the object.
327: * @param fetchPlan the fetch plan to load fields
328: **/
329: void retrieve(FetchPlan fetchPlan);
330:
331: /**
332: * Convenience interceptor to allow operations to be performed before the begin is performed
333: * @param tx The transaction
334: */
335: void preBegin(Transaction tx);
336:
337: /**
338: * Convenience interceptor to allow operations to be performed after the commit is performed
339: * but before returning control to the application.
340: * @param tx The transaction
341: */
342: void postCommit(Transaction tx);
343:
344: /**
345: * Convenience interceptor to allow operations to be performed before any rollback is
346: * performed.
347: * @param tx The transaction
348: */
349: void preRollback(Transaction tx);
350:
351: /**
352: * Method to flush all changes to the datastore.
353: */
354: void flush();
355:
356: /**
357: * Accessor for the relationship manager (if present).
358: * @return The Relationship manager
359: */
360: RelationshipManager getRelationshipManager();
361:
362: /**
363: * Method to process all managed relations for this object.
364: */
365: void checkManagedRelations();
366:
367: /**
368: * Method to process all managed relations for this object.
369: */
370: void processManagedRelations();
371:
372: /**
373: * Method to clear any state related to "managed relationships" stored for the object.
374: * This removes all original values stored for bidirectional fields that were changed in the
375: * previous flush-cycle. This is called when ObjectManager.flush() completes.
376: */
377: void clearManagedRelations();
378:
379: /**
380: * Method to return the current value of the specified field.
381: * @param fieldNumber (absolute) field number of the field
382: * @return The current value
383: */
384: Object provideField(int fieldNumber);
385:
386: /**
387: * Method to obtain updated field values from the passed FieldManager.
388: * @param fieldNumbers The numbers of the fields
389: * @param fm The fieldManager
390: */
391: void provideFields(int fieldNumbers[], FieldManager fm);
392:
393: /**
394: * Convenience method to change the value of a field that is assumed loaded.
395: * Will mark the object/field as dirty if it isnt previously.
396: * Only for use in management of relations.
397: * @param fieldNumber Number of field
398: * @param newValue The new value
399: */
400: void replaceFieldValue(int fieldNumber, Object newValue);
401:
402: /**
403: * Method to change the value of the specified field.
404: * @param fieldNumber (absolute) field number of the field
405: * @param value The new value.
406: * @param makeDirty Whether to make the field dirty when replacing it
407: */
408: void replaceField(int fieldNumber, Object value, boolean makeDirty);
409:
410: /**
411: * Method to update the data in the object with the values from the passed FieldManager
412: * @param fieldNumbers (absolute) field numbers of the fields to update
413: * @param fm The FieldManager
414: * @param replaceWhenDirty Whether to replace these fields if the field is dirty
415: */
416: void replaceFields(int fieldNumbers[], FieldManager fm,
417: boolean replaceWhenDirty);
418:
419: /**
420: * Method to update the data in the object with the values from the passed FieldManager
421: * @param fieldNumbers (absolute) field numbers of the fields to update
422: * @param fm The FieldManager
423: */
424: void replaceFields(int fieldNumbers[], FieldManager fm);
425:
426: /**
427: * Method to update the data in the object with the values from the passed
428: * FieldManager. Only non loaded fields are updated
429: * @param fieldNumbers (absolute) field numbers of the fields to update
430: * @param fm The FieldManager
431: */
432: void replaceNonLoadedFields(int fieldNumbers[], FieldManager fm);
433:
434: /**
435: * Method to replace all loaded SCO fields with wrappers.
436: * If the loaded field already uses a SCO wrapper nothing happens to that field.
437: */
438: void replaceAllLoadedSCOFieldsWithWrappers();
439:
440: /**
441: * Method to replace all loaded (wrapped) SCO fields with unwrapped values.
442: * If the loaded field doesnt use a SCO wrapper nothing happens to that field.
443: */
444: void replaceAllLoadedSCOFieldsWithValues();
445:
446: /**
447: * Method to wrap a SCO field (if not wrapped currently) and return the wrapped value.
448: * If the field is not a SCO field will just return the value.
449: * If "replaceFieldIfChanged" is set, we replace the value in the object with the wrapped value.
450: * @param fieldNumber Number of the field
451: * @param value The value to give it
452: * @param forInsert Whether the creation of any wrapper should insert this value into the datastore
453: * @param forUpdate Whether the creation of any wrapper should update the datastore with this value
454: * @param replaceFieldIfChanged Whether to replace the field in the object if wrapping the value
455: * @return The wrapper (or original value if not wrappable)
456: */
457: Object wrapSCOField(int fieldNumber, Object value,
458: boolean forInsert, boolean forUpdate,
459: boolean replaceFieldIfChanged);
460:
461: /**
462: * Method to unwrap a SCO field (if it is wrapped currently) and return the unwrapped value.
463: * If the field is not a SCO field will just return the value.
464: * If "replaceFieldIfChanged" is set, we replace the value in the object with the unwrapped value.
465: * @param fieldNumber The field number
466: * @param value The value to unwrap for this field
467: * @param replaceFieldIfChanged Whether to replace the field value in the object if unwrapping the value
468: * @return The unwrapped field value
469: */
470: Object unwrapSCOField(int fieldNumber, Object value,
471: boolean replaceFieldIfChanged);
472:
473: /**
474: * Accessor for the referenced PC object when we are attaching or detaching.
475: * When attaching and this is the detached object this returns the newly attached object.
476: * When attaching and this is the newly attached object this returns the detached object.
477: * When detaching and this is the newly detached object this returns the attached object.
478: * When detaching and this is the attached object this returns the newly detached object.
479: * @return The referenced object (or null).
480: */
481: Object getReferencedPC();
482:
483: /**
484: * Tests whether this object is new yet waiting to be flushed to the datastore.
485: * @return true if this instance is waiting to be flushed
486: */
487: boolean isWaitingToBeFlushedToDatastore();
488:
489: /**
490: * Method to allow the setting of the id of the PC object. This is used when it is obtained after persisting
491: * the object to the datastore. In the case of RDBMS, this may be via auto-increment, or in the case of ODBMS
492: * this may be an accessor for the id after storing.
493: * @param id the id received from the datastore. May be an OID, or the key value for an OID, or an application id.
494: */
495: void setPostStoreNewObjectId(Object id);
496:
497: /**
498: * Sets the value for the version column in the datastore. Update the transactional version too
499: * @param version The version
500: */
501: void setVersion(Object version);
502:
503: /**
504: * Return the object representing the transactional version of the calling instance.
505: * @param pc the calling persistable instance
506: * @return the object representing the version of the calling instance
507: * @since 1.1.1
508: */
509: Object getTransactionalVersion(Object pc);
510:
511: /**
512: * Sets the value for the version column in a transaction not yet committed
513: * @param optimisticTransactionalVersion
514: */
515: void setTransactionalVersion(Object optimisticTransactionalVersion);
516:
517: /**
518: * Accessor for the highest field number
519: * @return Highest field number
520: */
521: int getHighestFieldNumber();
522:
523: /**
524: * Accessor for an L2 cacheable form of this object.
525: * @return The L2 cacheable object
526: */
527: CachedPC getL2CacheableObject();
528:
529: /**
530: * Accessor for the ClassMetaData for this object.
531: * @return The ClassMetaData.
532: **/
533: AbstractClassMetaData getClassMetaData();
534:
535: /**
536: * Nullify fields with reference to PersistenceCapable or SCO instances
537: */
538: void nullifyFields();
539:
540: /**
541: * Convenience method to load the specified field if not loaded.
542: * @param fieldNumber Absolute field number
543: */
544: void loadField(int fieldNumber);
545:
546: /**
547: * Fetchs from the database all fields that are not currently loaded and that are in the current
548: * fetch group. Called by lifecycle transitions.
549: * @since 1.1
550: */
551: void loadUnloadedFieldsInFetchPlan();
552:
553: /**
554: * Method to load all unloaded fields in the FetchPlan.
555: * Recurses through the FetchPlan objects and loads fields of sub-objects where needed.
556: * @param state The FetchPlan state
557: */
558: void loadFieldsInFetchPlan(FetchPlanState state);
559:
560: /**
561: * Loads all unloaded fields of the managed class that are in the current FetchPlan.
562: * Called by life-cycle transitions.
563: * @param fetchPlan The FetchPlan
564: * @since 1.1
565: */
566: void loadUnloadedFieldsOfClassInFetchPlan(FetchPlan fetchPlan);
567:
568: /**
569: * Fetch from the database all fields that are not currently loaded regardless of whether
570: * they are in the current fetch group or not. Called by lifecycle transitions.
571: * @since 1.1
572: */
573: void loadUnloadedFields();
574:
575: /**
576: * Method that will unload all fields that are not in the FetchPlan.
577: * @since 1.2
578: */
579: void unloadNonFetchPlanFields();
580:
581: /**
582: * Convenience method to reset the detached state in the current object.
583: */
584: void resetDetachState();
585:
586: /**
587: * Disconnect the StateManager from the PersistenceManager and PC object.
588: */
589: void disconnect();
590:
591: //called by lifecycle ops
592: void evictFromTransaction();
593:
594: void enlistInTransaction();
595:
596: /**
597: * Refreshes from the database all fields currently loaded.
598: * Called by life-cycle transitions.
599: */
600: void refreshLoadedFields();
601:
602: /**
603: * Method to clear all saved fields on the object.
604: **/
605: void clearSavedFields();
606:
607: /**
608: * Refreshes from the database all fields in fetch plan.
609: * Called by life-cycle transitions.
610: */
611: void refreshFieldsInFetchPlan();
612:
613: /**
614: * Method to clear all fields that are not part of the primary key of the object.
615: **/
616: void clearNonPrimaryKeyFields();
617:
618: /**
619: * Method to restore all fields of the object.
620: **/
621: void restoreFields();
622:
623: /**
624: * Method to save all fields of the object.
625: **/
626: void saveFields();
627:
628: /**
629: * Method to clear all fields of the object.
630: **/
631: void clearFields();
632:
633: /**
634: * Registers the pc class in the cache
635: */
636: void registerTransactional();
637:
638: /**
639: * Accessor for the Restore Values flag
640: * @return Whether to restore values
641: */
642: boolean isRestoreValues();
643:
644: /**
645: * Method to clear all loaded flags on the object.
646: **/
647: void clearLoadedFlags();
648:
649: //used by SCO classes
650: /**
651: * Method to register an owner StateManager with this embedded/serialised object.
652: * @param ownerSM The owning State Manager.
653: * @param ownerFieldNumber The field number in the owner that the embedded/serialised object is stored as
654: */
655: void addEmbeddedOwner(StateManager ownerSM, int ownerFieldNumber);
656:
657: //used by PM classes
658: /**
659: * Convenience method to load the passed field values.
660: * Loads the fields using any required fetch plan and calls jdoPostLoad() as appropriate.
661: * @param fv Field Values to load (including any fetch plan to use when loading)
662: */
663: void loadFieldValues(FieldValues fv);
664:
665: /**
666: * Look to the database to determine which
667: * class this object is. This parameter is a hint. Set false, if it's
668: * already determined the correct pcClass for this pc "object" in a certain
669: * level in the hierarchy. Set to true and it will look to the database.
670: * @param fv the initial field values of the object.
671: */
672: void checkInheritance(FieldValues fv);
673:
674: //used by JPOXHelper
675: /**
676: * Convenience method to retrieve the detach state from the passed State Manager's object
677: * @param sm The State Manager
678: */
679: void retrieveDetachState(org.jpox.StateManager sm);
680:
681: //used by embedded mappings
682: /**
683: * Method to set this StateManager as managing an embedded/serialised object.
684: * @param embeddedType The type of object being managed
685: */
686: void setPcObjectType(int embeddedType);
687:
688: /**
689: * Accessor for the PC object type.
690: * @return PC Object type (PC, embedded PC, etc)
691: */
692: int getPcObjectType();
693:
694: /**
695: * Accessor for the overall owner StateManagers of the managed object when embedded.
696: * @return Owning StateManagers when embedded (if any)
697: */
698: StateManager[] getEmbeddedOwners();
699:
700: //used by container mappings
701: /**
702: * Method to set the storing PC flag.
703: */
704: void setStoringPC();
705:
706: /**
707: * Method to unset the storing PC flag.
708: */
709: void unsetStoringPC();
710:
711: //used by scostore
712: /**
713: * Convenience accessor for whether this StateManager manages an embedded/serialised object.
714: * @return Whether the managed object is embedded/serialised.
715: */
716: boolean isEmbedded();
717:
718: /**
719: * Method to set the value for an external field stored against this object
720: * @param mapping The mapping for the (external) field
721: * @param value The value that this field has
722: */
723: void setExternalFieldValueForMapping(JavaTypeMapping mapping,
724: Object value);
725:
726: /**
727: * Accessor for the value of an external field.
728: * This is used when inserting this object so that we can insert the external field values too.
729: * @param mapping The external field mapping
730: * @return The value for this mapping
731: */
732: Object getValueForExternalField(JavaTypeMapping mapping);
733:
734: /**
735: * Convenience method to load a field from the datastore.
736: * Used in attaching fields and checking their old values (so we dont
737: * want any postLoad method being called).
738: * TODO Merge this with one of the loadXXXFields methods.
739: * @param fieldNumber The field number.
740: */
741: void loadFieldFromDatastore(int fieldNumber);
742:
743: /**
744: * Tests whether this object is being inserted.
745: * @return true if this instance is inserting.
746: */
747: boolean isInserting();
748:
749: /**
750: * Returns whether the specified field of this object is inserted in the datastore.
751: * Only applies during the makePersistent process.
752: * @param fieldNumber Number of the field
753: * @return Whether it is inserted to the level of this field
754: */
755: boolean isInserted(int fieldNumber);
756:
757: /**
758: * Returns whether this object is inserted in the datastore far enough to be considered
759: * of the supplied type. For example if we have base class A, B extends A and this object
760: * is a B, and we pass in A here then this returns whether the A part of the object is now
761: * inserted.
762: * @param className Name of class that we want to check the insertion level for.
763: * @return Whether the object is inserted in the datastore to this level
764: */
765: boolean isInserted(String className);
766:
767: /**
768: * Tests whether this object is in the process of being deleted.
769: * @return true if this instance is being deleted.
770: */
771: boolean isDeleting();
772:
773: /**
774: * Returns whether the object being managed is dirty.
775: * @return whether at least one field is dirty by checking the dirty flag.
776: */
777: public boolean isDirty();
778:
779: /**
780: * Locate this object in the datastore.
781: * @throws JPOXObjectNotFoundException if the object doesnt exist.
782: */
783: void locate();
784:
785: /**
786: * Returns whether all fields are loaded.
787: * @return Returns true if all fields are loaded.
788: */
789: public boolean getAllFieldsLoaded();
790:
791: /**
792: * Creates a copy of the internal dirtyFields array.
793: * TODO Change this to return an array of the field numbers that are dirty
794: * @return a copy of the internal dirtyFields array.
795: */
796: public boolean[] getDirtyFields();
797:
798: /**
799: * Accessor for the field numbers of all dirty fields in this managed instance.
800: * @return Field numbers of all (currently) dirty fields
801: */
802: public int[] getDirtyFieldNumbers();
803:
804: /**
805: * Accessor for the field numbers of all loaded fields in this managed instance.
806: * @return Field numbers of all (currently) loaded fields
807: */
808: public int[] getLoadedFieldNumbers();
809:
810: /**
811: * Mark the specified field as not loaded so that it will be reloaded on next access.
812: * @param fieldName Name of the field
813: */
814: void unloadField(String fieldName);
815:
816: /**
817: * Diagnostic method to dump the current state to the provided PrintWriter.
818: * @param out The PrintWriter
819: */
820: void dump(PrintWriter out);
821:
822: // ---------------------------------- JDO-specific ------------------------------------
823: // TODO Move these to JDOStateManagerImpl or similar
824: /**
825: * Accessor for whether the managed object is deleted.
826: * @param pc The PC object
827: * @return Whether it is deleted
828: */
829: boolean isDeleted(PersistenceCapable pc);
830:
831: /**
832: * Accessor for whether the managed object is new.
833: * @param pc The PC object
834: * @return Whether it is new
835: */
836: boolean isNew(PersistenceCapable pc);
837:
838: /**
839: * Accessor for the object id.
840: * @param pc The PC object
841: * @return The (external) id
842: */
843: Object getObjectId(PersistenceCapable pc);
844:
845: /**
846: * Method to swap the managed object for the supplied object.
847: * This is of particular use for object datastores where the datastore is responsible for creating
848: * the in-memory object and where we have a temporary object that we want to swap for the datastore
849: * generated object. Makes no change to what fields are loaded/dirty etc, just swaps the managed object.
850: * @param pc The PersistenceCapable to use
851: */
852: void replaceManagedPC(PersistenceCapable pc);
853:
854: Object getVersion(PersistenceCapable pc);
855:
856: boolean isLoaded(PersistenceCapable pc, int fieldNumber);
857:
858: void setObjectField(PersistenceCapable pc, int fieldNumber,
859: Object oldValue, Object newValue);
860: }
|