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
boolean	becomingDeleted() Whether this object is moving to a deleted state.
CachedPC	cache() 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
ObjectProvider	getObjectProvider()
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	isEmbedded() Convenience accessor for whether this StateManager manages an embedded/serialised object.
boolean	isFieldLoaded(int fieldNumber) Accessor for whether a field is currently loaded.
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	markForInheritanceValidation() Mark the state manager as needing to validate the inheritance of the managed object existence before loading fields.
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

CachedPC cache()

Method to return an L2 cacheable object representing the managed object.

Returns:

The object suitable for L2 caching

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.

markForInheritanceValidation

void markForInheritanceValidation()

Mark the state manager as needing to validate the inheritance of the managed object existence before loading fields.

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.

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

becomingDeleted

boolean becomingDeleted()

Whether this object is moving to a deleted state.

Returns:

Whether the object will be moved into a deleted state during this operation

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

isFieldLoaded

boolean isFieldLoaded(int fieldNumber)

Accessor for whether a field is currently loaded. Just returns the status, unlike "isLoaded" which also loads it if not.

Parameters:

fieldNumber - The (absolute) field number

Returns:

Whether it is loaded

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)

getObjectProvider

ObjectProvider getObjectProvider()