org.datanucleus
Interface StateManager

All Known Implementing Classes:
AbstractStateManager, JDOStateManagerImpl

public interface StateManager

StateManager for persistable objects. Makes the assumption that a StateManager corresponds to ONE persistable object.


Field Summary
static int EMBEDDED_COLLECTION_ELEMENT_PC
          Embedded (or serialised) Collection Element PC
static int EMBEDDED_MAP_KEY_PC
          Embedded (or serialised) Map Key PC
static int EMBEDDED_MAP_VALUE_PC
          Embedded (or serialised) Map Value PC
static int EMBEDDED_PC
          Embedded (or serialised) PC
static int PC
          PC
 
Method Summary
 void addEmbeddedOwner(StateManager ownerSM, int ownerFieldNumber)
          Method to register an owner StateManager with this embedded/serialised object.
 void attach(boolean embedded)
          Method to attach the object managed by this StateManager.
 java.lang.Object attachCopy(java.lang.Object detachedPC, boolean embedded)
          Method to attach to this the detached persistable instance
 java.lang.Object cache(CacheState state)
          Method to return an L2 cacheable object representing the managed object.
 void changeActivityState(ActivityState activityState)
          Update the acitvity state.
 void checkInheritance(FieldValues fv)
          Look to the database to determine which class this object is.
 void checkManagedRelations()
          Method to process all managed relations for this object.
 void clearFields()
          Method to clear all fields of the object.
 void clearLoadedFlags()
          Method to clear all loaded flags on the object.
 void clearManagedRelations()
          Method to clear any state related to "managed relationships" stored for the object.
 void clearNonPrimaryKeyFields()
          Method to clear all fields that are not part of the primary key of the object.
 void clearSavedFields()
          Method to clear all saved fields on the object.
 void copyFieldsFromObject(javax.jdo.spi.PersistenceCapable pc, int[] fieldNumbers)
          Convenience method to update our object with the field values from the passed object.
 void deletePersistent()
          Method to delete the object from persistence.
 void detach(FetchPlanState state)
          Method to detach the PersistenceCapable object.
 java.lang.Object detachCopy(FetchPlanState state)
          Method to make detached copy of this instance
 void disconnect()
          Disconnect the StateManager from the PersistenceManager and PC object.
 void dump(java.io.PrintWriter out)
          Diagnostic method to dump the current state to the provided PrintWriter.
 void enlistInTransaction()
           
 void evict()
          Method to change the object state to evicted.
 void evictFromTransaction()
           
 void flush()
          Method to flush all changes to the datastore.
 boolean getAllFieldsLoaded()
          Returns whether all fields are loaded.
 java.lang.Object getAssociatedValue(java.lang.Object key)
          Accessor for the value of an external field.
 AbstractClassMetaData getClassMetaData()
          Accessor for the ClassMetaData for this object.
 java.lang.String[] getDirtyFieldNames()
          Accessor for the names of all dirty fields.
 int[] getDirtyFieldNumbers()
          Accessor for the field numbers of all dirty fields in this managed instance.
 boolean[] getDirtyFields()
          Creates a copy of the internal dirtyFields array.
 StateManager[] getEmbeddedOwners()
          Accessor for the overall owner StateManagers of the managed object when embedded.
 java.lang.Object getExternalObjectId(java.lang.Object obj)
          return a copy from the object Id
 int getHighestFieldNumber()
          Accessor for the highest field number
 java.lang.Object getInternalObjectId()
          Accessor for the id of the object managed by this StateManager.
 java.lang.String[] getLoadedFieldNames()
          Accessor for the names of all loaded fields.
 int[] getLoadedFieldNumbers()
          Accessor for the field numbers of all loaded fields in this managed instance.
 boolean[] getLoadedFields()
          Accessor for the fields
 MetaDataManager getMetaDataManager()
          Accessor for the manager for MetaData.
 java.lang.Object getObject()
          Accessor for the object managed by this StateManager.
 java.lang.Object getObjectId(javax.jdo.spi.PersistenceCapable pc)
          Accessor for the object id.
 ObjectManager getObjectManager()
          Returns the ObjectManager that owns the StateManager instance
 int getPcObjectType()
          Accessor for the PC object type.
 java.lang.Object getReferencedPC()
          Accessor for the referenced PC object when we are attaching or detaching.
 RelationshipManager getRelationshipManager()
          Accessor for the relationship manager (if present).
 StoreManager getStoreManager()
          Accessor for the manager for the store.
 java.lang.Object getTransactionalVersion(java.lang.Object pc)
          Return the object representing the transactional version of the calling instance.
 java.lang.Object getVersion(javax.jdo.spi.PersistenceCapable pc)
           
 void initialiseForCachedPC(CachedPC cachedPC, java.lang.Object id, java.lang.Class pcClass)
          Initialise to create a StateManager for a PersistenceCapable object, assigning the specified id to the object.
 void initialiseForDetached(java.lang.Object pc, java.lang.Object id, java.lang.Object version)
          Initialises the StateManager to manage a PersistenceCapable object in detached state.
 void initialiseForEmbedded(java.lang.Object pc, boolean copyPc)
          Initialises a state manager to manage a PersistenceCapable instance that will be EMBEDDED/SERIALISED into another PersistenceCapable object.
 void initialiseForHollow(java.lang.Object id, FieldValues fv, java.lang.Class pcClass)
          Initialises a state manager to manage a hollow instance having the given object ID and the given (optional) field values.
 void initialiseForHollowAppId(FieldValues fv, java.lang.Class pcClass)
          Initialises a state manager to manage a HOLLOW / P_CLEAN instance having the given FieldValues.
 void initialiseForHollowPreConstructed(java.lang.Object id, java.lang.Object pc)
          Initialises a state manager to manage the given hollow instance having the given object ID.
 void initialiseForPersistentClean(java.lang.Object id, java.lang.Object pc)
          Initialises a state manager to manage the passed persistent instance having the given object ID.
 void initialiseForPersistentNew(java.lang.Object pc, FieldValues preInsertChanges)
          Initialises a state manager to manage a transient instance that is becoming newly persistent.
 void initialiseForPNewToBeDeleted(java.lang.Object pc)
          Initialises the StateManager to manage a PersistenceCapable object that is not persistent but that is about to be deleted.
 void initialiseForTransactionalTransient(java.lang.Object pc)
          Initialises a state manager to manage a Transactional Transient instance.
 boolean isDeleted(javax.jdo.spi.PersistenceCapable pc)
          Accessor for whether the managed object is deleted.
 boolean isDeleting()
          Tests whether this object is in the process of being deleted.
 boolean isDetaching()
          Tests whether this object is in the process of being detached.
 boolean isDirty()
          Returns whether the object being managed is dirty.
 boolean isEmbedded()
          Convenience accessor for whether this StateManager manages an embedded/serialised object.
 boolean isInserting()
          Tests whether this object is being inserted.
 boolean isLoaded(javax.jdo.spi.PersistenceCapable pc, int fieldNumber)
           
 boolean isNew(javax.jdo.spi.PersistenceCapable pc)
          Accessor for whether the managed object is new.
 boolean isRestoreValues()
          Accessor for the Restore Values flag
 boolean isUpdatingFieldForPostInsert()
          Convenience method to return if we are in the phase of performing postInsert updates due to related objects having been inserted and so allowing the field to be inserted.
 boolean isWaitingToBeFlushedToDatastore()
          Tests whether this object is new yet waiting to be flushed to the datastore.
 void loadField(int fieldNumber)
          Convenience method to load the specified field if not loaded.
 void loadFieldFromDatastore(int fieldNumber)
          Convenience method to load a field from the datastore.
 void loadFieldsInFetchPlan(FetchPlanState state)
          Method to load all unloaded fields in the FetchPlan.
 void loadFieldValues(FieldValues fv)
          Convenience method to load the passed field values.
 void loadUnloadedFields()
          Fetch from the database all fields that are not currently loaded regardless of whether they are in the current fetch group or not.
 void loadUnloadedFieldsInFetchPlan()
          Fetchs from the database all fields that are not currently loaded and that are in the current fetch group.
 void loadUnloadedFieldsOfClassInFetchPlan(FetchPlan fetchPlan)
          Loads all unloaded fields of the managed class that are in the current FetchPlan.
 void locate()
          Locate this object in the datastore.
 void makeDirty(int fieldNumber)
          Method to mark the specified (absolute) field number as dirty.
 void makeNontransactional()
          Method to make the managed object nontransactional.
 void makePersistent()
          Method to make the managed object persistent.
 void makePersistentTransactionalTransient()
          Method to make Transactional Transient instances persistent
 void makeTransactional()
          Method to make the managed object transactional.
 void makeTransient(FetchPlanState state)
          Method to make the managed object transient.
 void nullifyFields()
          Nullify fields with reference to PersistenceCapable or SCO instances
 void postCommit(Transaction tx)
          Convenience interceptor to allow operations to be performed after the commit is performed but before returning control to the application.
 void preBegin(Transaction tx)
          Convenience interceptor to allow operations to be performed before the begin is performed
 void preRollback(Transaction tx)
          Convenience interceptor to allow operations to be performed before any rollback is performed.
 void processManagedRelations()
          Method to process all managed relations for this object.
 java.lang.Object provideField(int fieldNumber)
          Method to return the current value of the specified field.
 void provideFields(int[] fieldNumbers, FieldManager fm)
          Method to obtain updated field values from the passed FieldManager.
 void refresh()
          Method to refresh the values of the currently loaded fields in the managed object.
 void refreshFieldsInFetchPlan()
          Refreshes from the database all fields in fetch plan.
 void refreshLoadedFields()
          Refreshes from the database all fields currently loaded.
 void registerTransactional()
          Registers the pc class in the cache
 void replaceAllLoadedSCOFieldsWithValues()
          Method to replace all loaded (wrapped) SCO fields with unwrapped values.
 void replaceAllLoadedSCOFieldsWithWrappers()
          Method to replace all loaded SCO fields with wrappers.
 void replaceField(int fieldNumber, java.lang.Object value, boolean makeDirty)
          Method to change the value of the specified field.
 void replaceFields(int[] fieldNumbers, FieldManager fm)
          Method to update the data in the object with the values from the passed FieldManager
 void replaceFields(int[] fieldNumbers, FieldManager fm, boolean replaceWhenDirty)
          Method to update the data in the object with the values from the passed FieldManager
 void replaceFieldValue(int fieldNumber, java.lang.Object newValue)
          Convenience method to change the value of a field that is assumed loaded.
 void replaceManagedPC(javax.jdo.spi.PersistenceCapable pc)
          Method to swap the managed object for the supplied object.
 void replaceNonLoadedFields(int[] fieldNumbers, FieldManager fm)
          Method to update the data in the object with the values from the passed FieldManager.
 void resetDetachState()
          Convenience method to reset the detached state in the current object.
 void restoreFields()
          Method to restore all fields of the object.
 void retrieve(boolean fgOnly)
          Method to retrieve the fields for this object.
 void retrieve(FetchPlan fetchPlan)
          Method to retrieve the object.
 void retrieveDetachState(StateManager sm)
          Convenience method to retrieve the detach state from the passed State Manager's object
 void runReachability(java.util.Set reachables)
          Method to run reachability from this StateManager.
 void saveFields()
          Method to save all fields of the object.
 void setAssociatedValue(java.lang.Object key, java.lang.Object value)
          Method to set the value for an external field stored against this object.
 void setObjectField(javax.jdo.spi.PersistenceCapable pc, int fieldNumber, java.lang.Object oldValue, java.lang.Object newValue)
           
 void setPcObjectType(int embeddedType)
          Method to set this StateManager as managing an embedded/serialised object.
 void setPostStoreNewObjectId(java.lang.Object id)
          Method to allow the setting of the id of the PC object.
 void setStoringPC()
          Method to set the storing PC flag.
 void setTransactionalVersion(java.lang.Object optimisticTransactionalVersion)
          Sets the value for the version column in a transaction not yet committed
 void setVersion(java.lang.Object version)
          Sets the value for the version column in the datastore.
 void unloadField(java.lang.String fieldName)
          Mark the specified field as not loaded so that it will be reloaded on next access.
 void unloadNonFetchPlanFields()
          Method that will unload all fields that are not in the FetchPlan.
 void unsetStoringPC()
          Method to unset the storing PC flag.
 java.lang.Object unwrapSCOField(int fieldNumber, java.lang.Object value, boolean replaceFieldIfChanged)
          Method to unwrap a SCO field (if it is wrapped currently) and return the unwrapped value.
 void updateFieldAfterInsert(java.lang.Object pc, int fieldNumber)
          Marks the given field dirty for issuing an update after the insert.
 void validate()
          Validates whether the persistence capable instance exists in the datastore.
 java.lang.Object wrapSCOField(int fieldNumber, java.lang.Object value, boolean forInsert, boolean forUpdate, boolean replaceFieldIfChanged)
          Method to wrap a SCO field (if not wrapped currently) and return the wrapped value.
 

Field Detail

PC

static final int PC
PC

See Also:
Constant Field Values

EMBEDDED_PC

static final int EMBEDDED_PC
Embedded (or serialised) PC

See Also:
Constant Field Values

EMBEDDED_COLLECTION_ELEMENT_PC

static final int EMBEDDED_COLLECTION_ELEMENT_PC
Embedded (or serialised) Collection Element PC

See Also:
Constant Field Values

EMBEDDED_MAP_KEY_PC

static final int EMBEDDED_MAP_KEY_PC
Embedded (or serialised) Map Key PC

See Also:
Constant Field Values

EMBEDDED_MAP_VALUE_PC

static final int EMBEDDED_MAP_VALUE_PC
Embedded (or serialised) Map Value PC

See Also:
Constant Field Values
Method Detail

initialiseForHollow

void initialiseForHollow(java.lang.Object id,
                         FieldValues fv,
                         java.lang.Class pcClass)
Initialises a state manager to manage a hollow instance having the given object ID and the given (optional) field values. This constructor is used for creating new instances of existing persistent objects, and consequently shouldnt be used when the StoreManager controls the creation of such objects (such as in an ODBMS).

Parameters:
id - the identity of the object.
fv - the initial field values of the object (optional)
pcClass - Class of the object that this will manage the state for

initialiseForHollowAppId

void initialiseForHollowAppId(FieldValues fv,
                              java.lang.Class pcClass)
Initialises a state manager to manage a HOLLOW / P_CLEAN instance having the given FieldValues. This constructor is used for creating new instances of existing persistent objects using application identity, and consequently shouldnt be used when the StoreManager controls the creation of such objects (such as in an ODBMS).

Parameters:
fv - the initial field values of the object.
pcClass - Class of the object that this will manage the state for

initialiseForHollowPreConstructed

void initialiseForHollowPreConstructed(java.lang.Object id,
                                       java.lang.Object pc)
Initialises a state manager to manage the given hollow instance having the given object ID. Unlike the initialiseForHollow(java.lang.Object, org.datanucleus.store.FieldValues, java.lang.Class) method, this method does not create a new instance and instead takes a pre-constructed instance.

Parameters:
id - the identity of the object.
pc - the object to be managed.

initialiseForPersistentClean

void initialiseForPersistentClean(java.lang.Object id,
                                  java.lang.Object pc)
Initialises a state manager to manage the passed persistent instance having the given object ID. Used where we have retrieved a PC object from a datastore directly (not field-by-field), for example on an object datastore. This initialiser will not add StateManagers to all related PCs. This must be done by any calling process. This simply adds the StateManager to the specified object and records the id, setting all fields of the object as loaded.

Parameters:
id - the identity of the object.
pc - The object to be managed

initialiseForEmbedded

void initialiseForEmbedded(java.lang.Object pc,
                           boolean copyPc)
Initialises a state manager to manage a PersistenceCapable instance that will be EMBEDDED/SERIALISED into another PersistenceCapable object. The instance will not be assigned an identity in the process since it is a SCO.

Parameters:
pc - The PersistenceCapable to manage (see copyPc also)
copyPc - Whether the SM should manage a copy of the passed PC or that one

initialiseForPersistentNew

void initialiseForPersistentNew(java.lang.Object pc,
                                FieldValues preInsertChanges)
Initialises a state manager to manage a transient instance that is becoming newly persistent. A new object ID for the instance is obtained from the store manager and the object is inserted in the data store.

This constructor is used for assigning state managers to existing instances that are transitioning to a persistent state.

Parameters:
pc - the instance being make persistent.
preInsertChanges - Any changes to make before inserting

initialiseForTransactionalTransient

void initialiseForTransactionalTransient(java.lang.Object pc)
Initialises a state manager to manage a Transactional Transient instance. A new object ID for the instance is obtained from the store manager and the object is inserted in the data store.

This constructor is used for assigning state managers to Transient instances that are transitioning to a transient clean state.

Parameters:
pc - the instance being make persistent.

initialiseForDetached

void initialiseForDetached(java.lang.Object pc,
                           java.lang.Object id,
                           java.lang.Object version)
Initialises the StateManager to manage a PersistenceCapable object in detached state.

Parameters:
pc - the detach object.
id - the identity of the object.
version - the detached version

initialiseForCachedPC

void initialiseForCachedPC(CachedPC cachedPC,
                           java.lang.Object id,
                           java.lang.Class pcClass)
Initialise to create a StateManager for a PersistenceCapable object, assigning the specified id to the object. This is used when getting objects out of the L2 Cache, where they have no StateManager assigned, and returning them as associated with a particular PM.

Parameters:
cachedPC - Cache object for persistable object from L2 cache
id - Id to assign to the PersistenceCapable object
pcClass - Class of the object that this will manage the state for

initialiseForPNewToBeDeleted

void initialiseForPNewToBeDeleted(java.lang.Object pc)
Initialises the StateManager to manage a PersistenceCapable object that is not persistent but that is about to be deleted. The initial state will be P_NEW, but when the delete call comes in will be P_NEW_DELETED. The object will not be enlisted in the transaction.

Parameters:
pc - the object to delete

getObject

java.lang.Object getObject()
Accessor for the object managed by this StateManager.

Returns:
The object

getInternalObjectId

java.lang.Object getInternalObjectId()
Accessor for the id of the object managed by this StateManager.

Returns:
The identity of the object

getExternalObjectId

java.lang.Object getExternalObjectId(java.lang.Object obj)
return a copy from the object Id

Parameters:
obj - the persistable object
Returns:
the object id

getObjectManager

ObjectManager getObjectManager()
Returns the ObjectManager that owns the StateManager instance

Returns:
The ObjectManager

getStoreManager

StoreManager getStoreManager()
Accessor for the manager for the store.

Returns:
Store Manager

getMetaDataManager

MetaDataManager getMetaDataManager()
Accessor for the manager for MetaData.

Returns:
MetaData manager

makeDirty

void makeDirty(int fieldNumber)
Method to mark the specified (absolute) field number as dirty.

Parameters:
fieldNumber - The (absolute) field number of the field

getDirtyFieldNames

java.lang.String[] getDirtyFieldNames()
Accessor for the names of all dirty fields.

Returns:
Names of all dirty fields

getLoadedFieldNames

java.lang.String[] getLoadedFieldNames()
Accessor for the names of all loaded fields.

Returns:
Names of all loaded fields

updateFieldAfterInsert

void updateFieldAfterInsert(java.lang.Object pc,
                            int fieldNumber)
Marks the given field dirty for issuing an update after the insert.

Parameters:
pc - The Persistable object
fieldNumber - The no of field to mark as dirty.

changeActivityState

void changeActivityState(ActivityState activityState)
Update the acitvity state.

Parameters:
activityState - the activity state

runReachability

void runReachability(java.util.Set reachables)
Method to run reachability from this StateManager.

Parameters:
reachables - List of reachable StateManagers so far

makeTransactional

void makeTransactional()
Method to make the managed object transactional.


makeNontransactional

void makeNontransactional()
Method to make the managed object nontransactional.


makeTransient

void makeTransient(FetchPlanState state)
Method to make the managed object transient.

Parameters:
state - Object containing the state of any fetch plan processing

makePersistent

void makePersistent()
Method to make the managed object persistent.


makePersistentTransactionalTransient

void makePersistentTransactionalTransient()
Method to make Transactional Transient instances persistent


deletePersistent

void deletePersistent()
Method to delete the object from persistence.


attachCopy

java.lang.Object attachCopy(java.lang.Object detachedPC,
                            boolean embedded)
Method to attach to this the detached persistable instance

Parameters:
detachedPC - the detached persistable instance to be attached
embedded - Whether it is embedded
Returns:
The attached copy

attach

void attach(boolean embedded)
Method to attach the object managed by this StateManager.

Parameters:
embedded - Whether it is embedded

detachCopy

java.lang.Object detachCopy(FetchPlanState state)
Method to make detached copy of this instance

Parameters:
state - State for the detachment process
Returns:
the detached PersistenceCapable instance

detach

void detach(FetchPlanState state)
Method to detach the PersistenceCapable object.

Parameters:
state - State for the detachment process

cache

java.lang.Object cache(CacheState state)
Method to return an L2 cacheable object representing the managed object.

Parameters:
state - The cache state
Returns:
The cacheable persistable object

validate

void validate()
Validates whether the persistence capable instance exists in the datastore. If the instance does not exist in the datastore, this method will fail raising a NucleusObjectNotFoundException.


evict

void evict()
Method to change the object state to evicted.


refresh

void refresh()
Method to refresh the values of the currently loaded fields in the managed object.


retrieve

void retrieve(boolean fgOnly)
Method to retrieve the fields for this object.

Parameters:
fgOnly - Whether to retrieve just the current fetch plan fields

retrieve

void retrieve(FetchPlan fetchPlan)
Method to retrieve the object.

Parameters:
fetchPlan - the fetch plan to load fields

preBegin

void preBegin(Transaction tx)
Convenience interceptor to allow operations to be performed before the begin is performed

Parameters:
tx - The transaction

postCommit

void postCommit(Transaction tx)
Convenience interceptor to allow operations to be performed after the commit is performed but before returning control to the application.

Parameters:
tx - The transaction

preRollback

void preRollback(Transaction tx)
Convenience interceptor to allow operations to be performed before any rollback is performed.

Parameters:
tx - The transaction

flush

void flush()
Method to flush all changes to the datastore.


getRelationshipManager

RelationshipManager getRelationshipManager()
Accessor for the relationship manager (if present).

Returns:
The Relationship manager

checkManagedRelations

void checkManagedRelations()
Method to process all managed relations for this object.


processManagedRelations

void processManagedRelations()
Method to process all managed relations for this object.


clearManagedRelations

void clearManagedRelations()
Method to clear any state related to "managed relationships" stored for the object. This removes all original values stored for bidirectional fields that were changed in the previous flush-cycle. This is called when ObjectManager.flush() completes.


provideField

java.lang.Object provideField(int fieldNumber)
Method to return the current value of the specified field.

Parameters:
fieldNumber - (absolute) field number of the field
Returns:
The current value

provideFields

void provideFields(int[] fieldNumbers,
                   FieldManager fm)
Method to obtain updated field values from the passed FieldManager.

Parameters:
fieldNumbers - The numbers of the fields
fm - The fieldManager

replaceFieldValue

void replaceFieldValue(int fieldNumber,
                       java.lang.Object newValue)
Convenience method to change the value of a field that is assumed loaded. Will mark the object/field as dirty if it isnt previously. Only for use in management of relations.

Parameters:
fieldNumber - Number of field
newValue - The new value

replaceField

void replaceField(int fieldNumber,
                  java.lang.Object value,
                  boolean makeDirty)
Method to change the value of the specified field.

Parameters:
fieldNumber - (absolute) field number of the field
value - The new value.
makeDirty - Whether to make the field dirty when replacing it

replaceFields

void replaceFields(int[] fieldNumbers,
                   FieldManager fm,
                   boolean replaceWhenDirty)
Method to update the data in the object with the values from the passed FieldManager

Parameters:
fieldNumbers - (absolute) field numbers of the fields to update
fm - The FieldManager
replaceWhenDirty - Whether to replace these fields if the field is dirty

replaceFields

void replaceFields(int[] fieldNumbers,
                   FieldManager fm)
Method to update the data in the object with the values from the passed FieldManager

Parameters:
fieldNumbers - (absolute) field numbers of the fields to update
fm - The FieldManager

replaceNonLoadedFields

void replaceNonLoadedFields(int[] fieldNumbers,
                            FieldManager fm)
Method to update the data in the object with the values from the passed FieldManager. Only non loaded fields are updated

Parameters:
fieldNumbers - (absolute) field numbers of the fields to update
fm - The FieldManager

replaceAllLoadedSCOFieldsWithWrappers

void replaceAllLoadedSCOFieldsWithWrappers()
Method to replace all loaded SCO fields with wrappers. If the loaded field already uses a SCO wrapper nothing happens to that field.


replaceAllLoadedSCOFieldsWithValues

void replaceAllLoadedSCOFieldsWithValues()
Method to replace all loaded (wrapped) SCO fields with unwrapped values. If the loaded field doesnt use a SCO wrapper nothing happens to that field.


wrapSCOField

java.lang.Object wrapSCOField(int fieldNumber,
                              java.lang.Object value,
                              boolean forInsert,
                              boolean forUpdate,
                              boolean replaceFieldIfChanged)
Method to wrap a SCO field (if not wrapped currently) and return the wrapped value. If the field is not a SCO field will just return the value. If "replaceFieldIfChanged" is set, we replace the value in the object with the wrapped value.

Parameters:
fieldNumber - Number of the field
value - The value to give it
forInsert - Whether the creation of any wrapper should insert this value into the datastore
forUpdate - Whether the creation of any wrapper should update the datastore with this value
replaceFieldIfChanged - Whether to replace the field in the object if wrapping the value
Returns:
The wrapper (or original value if not wrappable)

unwrapSCOField

java.lang.Object unwrapSCOField(int fieldNumber,
                                java.lang.Object value,
                                boolean replaceFieldIfChanged)
Method to unwrap a SCO field (if it is wrapped currently) and return the unwrapped value. If the field is not a SCO field will just return the value. If "replaceFieldIfChanged" is set, we replace the value in the object with the unwrapped value.

Parameters:
fieldNumber - The field number
value - The value to unwrap for this field
replaceFieldIfChanged - Whether to replace the field value in the object if unwrapping the value
Returns:
The unwrapped field value

getReferencedPC

java.lang.Object getReferencedPC()
Accessor for the referenced PC object when we are attaching or detaching. When attaching and this is the detached object this returns the newly attached object. When attaching and this is the newly attached object this returns the detached object. When detaching and this is the newly detached object this returns the attached object. When detaching and this is the attached object this returns the newly detached object.

Returns:
The referenced object (or null).

isWaitingToBeFlushedToDatastore

boolean isWaitingToBeFlushedToDatastore()
Tests whether this object is new yet waiting to be flushed to the datastore.

Returns:
true if this instance is waiting to be flushed

setPostStoreNewObjectId

void setPostStoreNewObjectId(java.lang.Object id)
Method to allow the setting of the id of the PC object. This is used when it is obtained after persisting the object to the datastore. In the case of RDBMS, this may be via auto-increment, or in the case of ODBMS this may be an accessor for the id after storing.

Parameters:
id - the id received from the datastore. May be an OID, or the key value for an OID, or an application id.

setVersion

void setVersion(java.lang.Object version)
Sets the value for the version column in the datastore. Update the transactional version too

Parameters:
version - The version

getTransactionalVersion

java.lang.Object getTransactionalVersion(java.lang.Object pc)
Return the object representing the transactional version of the calling instance.

Parameters:
pc - the calling persistable instance
Returns:
the object representing the version of the calling instance

setTransactionalVersion

void setTransactionalVersion(java.lang.Object optimisticTransactionalVersion)
Sets the value for the version column in a transaction not yet committed

Parameters:
optimisticTransactionalVersion -

getHighestFieldNumber

int getHighestFieldNumber()
Accessor for the highest field number

Returns:
Highest field number

getClassMetaData

AbstractClassMetaData getClassMetaData()
Accessor for the ClassMetaData for this object.

Returns:
The ClassMetaData.

nullifyFields

void nullifyFields()
Nullify fields with reference to PersistenceCapable or SCO instances


loadField

void loadField(int fieldNumber)
Convenience method to load the specified field if not loaded.

Parameters:
fieldNumber - Absolute field number

loadUnloadedFieldsInFetchPlan

void loadUnloadedFieldsInFetchPlan()
Fetchs from the database all fields that are not currently loaded and that are in the current fetch group. Called by lifecycle transitions.


loadFieldsInFetchPlan

void loadFieldsInFetchPlan(FetchPlanState state)
Method to load all unloaded fields in the FetchPlan. Recurses through the FetchPlan objects and loads fields of sub-objects where needed.

Parameters:
state - The FetchPlan state

loadUnloadedFieldsOfClassInFetchPlan

void loadUnloadedFieldsOfClassInFetchPlan(FetchPlan fetchPlan)
Loads all unloaded fields of the managed class that are in the current FetchPlan. Called by life-cycle transitions.

Parameters:
fetchPlan - The FetchPlan
Since:
1.1

loadUnloadedFields

void loadUnloadedFields()
Fetch from the database all fields that are not currently loaded regardless of whether they are in the current fetch group or not. Called by lifecycle transitions.


unloadNonFetchPlanFields

void unloadNonFetchPlanFields()
Method that will unload all fields that are not in the FetchPlan.


resetDetachState

void resetDetachState()
Convenience method to reset the detached state in the current object.


disconnect

void disconnect()
Disconnect the StateManager from the PersistenceManager and PC object.


evictFromTransaction

void evictFromTransaction()

enlistInTransaction

void enlistInTransaction()

refreshLoadedFields

void refreshLoadedFields()
Refreshes from the database all fields currently loaded. Called by life-cycle transitions.


clearSavedFields

void clearSavedFields()
Method to clear all saved fields on the object.


refreshFieldsInFetchPlan

void refreshFieldsInFetchPlan()
Refreshes from the database all fields in fetch plan. Called by life-cycle transitions.


clearNonPrimaryKeyFields

void clearNonPrimaryKeyFields()
Method to clear all fields that are not part of the primary key of the object.


restoreFields

void restoreFields()
Method to restore all fields of the object.


saveFields

void saveFields()
Method to save all fields of the object.


clearFields

void clearFields()
Method to clear all fields of the object.


registerTransactional

void registerTransactional()
Registers the pc class in the cache


isRestoreValues

boolean isRestoreValues()
Accessor for the Restore Values flag

Returns:
Whether to restore values

clearLoadedFlags

void clearLoadedFlags()
Method to clear all loaded flags on the object.


addEmbeddedOwner

void addEmbeddedOwner(StateManager ownerSM,
                      int ownerFieldNumber)
Method to register an owner StateManager with this embedded/serialised object.

Parameters:
ownerSM - The owning State Manager.
ownerFieldNumber - The field number in the owner that the embedded/serialised object is stored as

loadFieldValues

void loadFieldValues(FieldValues fv)
Convenience method to load the passed field values. Loads the fields using any required fetch plan and calls jdoPostLoad() as appropriate.

Parameters:
fv - Field Values to load (including any fetch plan to use when loading)

checkInheritance

void checkInheritance(FieldValues fv)
Look to the database to determine which class this object is. This parameter is a hint. Set false, if it's already determined the correct pcClass for this pc "object" in a certain level in the hierarchy. Set to true and it will look to the database.

Parameters:
fv - the initial field values of the object.

retrieveDetachState

void retrieveDetachState(StateManager sm)
Convenience method to retrieve the detach state from the passed State Manager's object

Parameters:
sm - The State Manager

setPcObjectType

void setPcObjectType(int embeddedType)
Method to set this StateManager as managing an embedded/serialised object.

Parameters:
embeddedType - The type of object being managed

getPcObjectType

int getPcObjectType()
Accessor for the PC object type.

Returns:
PC Object type (PC, embedded PC, etc)

getEmbeddedOwners

StateManager[] getEmbeddedOwners()
Accessor for the overall owner StateManagers of the managed object when embedded.

Returns:
Owning StateManagers when embedded (if any)

setStoringPC

void setStoringPC()
Method to set the storing PC flag.


unsetStoringPC

void unsetStoringPC()
Method to unset the storing PC flag.


isEmbedded

boolean isEmbedded()
Convenience accessor for whether this StateManager manages an embedded/serialised object.

Returns:
Whether the managed object is embedded/serialised.

setAssociatedValue

void setAssociatedValue(java.lang.Object key,
                        java.lang.Object value)
Method to set the value for an external field stored against this object. This is for a situation such as in ORM where this object can have an "external" foreign-key provided by an owning object (e.g 1-N uni relation and this is the element with no knowledge of the owner, so the associated value is the FK value).

Parameters:
key - The key for this associated information
value - The value to store

getAssociatedValue

java.lang.Object getAssociatedValue(java.lang.Object key)
Accessor for the value of an external field. This is for a situation such as in ORM where this object can have an "external" foreign-key provided by an owning object (e.g 1-N uni relation and this is the element with no knowledge of the owner, so the associated value is the FK value).

Parameters:
key - The key for this associated information
Returns:
The value stored (if any) against this key

loadFieldFromDatastore

void loadFieldFromDatastore(int fieldNumber)
Convenience method to load a field from the datastore. Used in attaching fields and checking their old values (so we don't want any postLoad method being called). TODO Merge this with one of the loadXXXFields methods.

Parameters:
fieldNumber - The field number.

isInserting

boolean isInserting()
Tests whether this object is being inserted.

Returns:
true if this instance is inserting.

isDeleting

boolean isDeleting()
Tests whether this object is in the process of being deleted.

Returns:
true if this instance is being deleted.

isDetaching

boolean isDetaching()
Tests whether this object is in the process of being detached.

Returns:
true if this instance is being detached.

isDirty

boolean isDirty()
Returns whether the object being managed is dirty.

Returns:
whether at least one field is dirty by checking the dirty flag.

isUpdatingFieldForPostInsert

boolean isUpdatingFieldForPostInsert()
Convenience method to return if we are in the phase of performing postInsert updates due to related objects having been inserted and so allowing the field to be inserted.

Returns:
Whether we are updating for postInsert

locate

void locate()
Locate this object in the datastore.

Throws:
NucleusObjectNotFoundException - if the object doesnt exist.

getAllFieldsLoaded

boolean getAllFieldsLoaded()
Returns whether all fields are loaded.

Returns:
Returns true if all fields are loaded.

getDirtyFields

boolean[] getDirtyFields()
Creates a copy of the internal dirtyFields array. TODO Change this to return an array of the field numbers that are dirty

Returns:
a copy of the internal dirtyFields array.

getDirtyFieldNumbers

int[] getDirtyFieldNumbers()
Accessor for the field numbers of all dirty fields in this managed instance.

Returns:
Field numbers of all (currently) dirty fields

getLoadedFieldNumbers

int[] getLoadedFieldNumbers()
Accessor for the field numbers of all loaded fields in this managed instance.

Returns:
Field numbers of all (currently) loaded fields

getLoadedFields

boolean[] getLoadedFields()
Accessor for the fields

Returns:
boolean array of loaded state in order of absolute field numbers

unloadField

void unloadField(java.lang.String fieldName)
Mark the specified field as not loaded so that it will be reloaded on next access.

Parameters:
fieldName - Name of the field

copyFieldsFromObject

void copyFieldsFromObject(javax.jdo.spi.PersistenceCapable pc,
                          int[] fieldNumbers)
Convenience method to update our object with the field values from the passed object. Objects need to be of the same type, and the other object should not have a StateManager.

Parameters:
pc - The object that we should copy fields from

dump

void dump(java.io.PrintWriter out)
Diagnostic method to dump the current state to the provided PrintWriter.

Parameters:
out - The PrintWriter

isDeleted

boolean isDeleted(javax.jdo.spi.PersistenceCapable pc)
Accessor for whether the managed object is deleted.

Parameters:
pc - The PC object
Returns:
Whether it is deleted

isNew

boolean isNew(javax.jdo.spi.PersistenceCapable pc)
Accessor for whether the managed object is new.

Parameters:
pc - The PC object
Returns:
Whether it is new

getObjectId

java.lang.Object getObjectId(javax.jdo.spi.PersistenceCapable pc)
Accessor for the object id.

Parameters:
pc - The PC object
Returns:
The (external) id

replaceManagedPC

void replaceManagedPC(javax.jdo.spi.PersistenceCapable pc)
Method to swap the managed object for the supplied object. This is of particular use for object datastores where the datastore is responsible for creating the in-memory object and where we have a temporary object that we want to swap for the datastore generated object. Makes no change to what fields are loaded/dirty etc, just swaps the managed object.

Parameters:
pc - The PersistenceCapable to use

getVersion

java.lang.Object getVersion(javax.jdo.spi.PersistenceCapable pc)

isLoaded

boolean isLoaded(javax.jdo.spi.PersistenceCapable pc,
                 int fieldNumber)

setObjectField

void setObjectField(javax.jdo.spi.PersistenceCapable pc,
                    int fieldNumber,
                    java.lang.Object oldValue,
                    java.lang.Object newValue)


Copyright © 2009. All Rights Reserved.