org.jpox
Interface StateManager

All Superinterfaces:

javax.jdo.spi.StateManager

public interface StateManager
extends javax.jdo.spi.StateManager

Extension to SUN's JDO StateManager class. This makes the assumption that a StateManager corresponds to ONE PersistenceCapable object. As a result of this assumption various methods are added to the basic JDO definition.

Version:

$Revision: 1.38.2.2 $

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.
java.lang.Object	attachCopy(javax.jdo.spi.PersistenceCapable detachedPC, boolean embedded) Method to attach to this the detached PersistenceCapable instance
void	changeActivityState(ActivityState activityState, DatastoreClass table) Update the acitvity state.
void	checkInheritance(FieldValues fv) Look to the database to determine which class this object is.
void	clearFields() Method to clear all fields of the object.
void	clearLoadedFlags() Method to clear all loaded flags on 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	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.
java.lang.Object	getAttachedPC() When an object is being attached it will temporarily have a StateManager connected, and during this time this method gives access to the attached variant of the object.
AbstractClassMetaData	getClassMetaData() Accessor for the ClassMetaData for this object.
java.lang.String[]	getDirtyFieldNames() Accessor for the names of all dirty fields.
java.lang.Object	getExternalObjectId(javax.jdo.spi.PersistenceCapable pc) 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.
CachedPC	getL2CacheableObject() Accessor for an L2 cacheable form of this object.
java.lang.String[]	getLoadedFieldNames() Accessor for the names of all loaded fields.
MetaDataManager	getMetaDataManager() Accessor for the manager for MetaData.
javax.jdo.spi.PersistenceCapable	getObject() Accessor for the object managed by this StateManager.
PersistenceManager	getPersistenceManager() Returns the PersistenceManager that owns the StateManager instance
StoreManager	getStoreManager() Accessor for the manager for the store.
java.lang.Object	getTransactionalVersion(javax.jdo.spi.PersistenceCapable pc) Return the object representing the transactional version of the calling instance.
java.lang.Object	getValueForExternalField(JavaTypeMapping mapping) Accessor for the value of an external field.
boolean	isEmbedded() Convenience accessor for whether this StateManager manages an embedded/serialised object.
boolean	isInserted(int fieldNumber) Returns whether the field of this object is inserted in the datastore.
boolean	isInserting() Tests whether this object is being inserted.
boolean	isRestoreValues() Accessor for the Restore Values flag
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(javax.jdo.FetchPlan fetchPlan) Loads all unloaded fields of the managed class that are in the current FetchPlan.
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.
java.lang.Object	newSCOEmptyInstance(int fieldNumber) Method to return an empty SCO wrapper for the specified field.
java.lang.Object	newSCOInstance(int fieldNumber, java.lang.Object value, boolean forUpdate) Method to create a new SCO wrapper for a second class field.
void	nullifyFields() Nullify fields with reference to PersistenceCapable or SCO instances
void	postCommit(javax.jdo.Transaction tx) Convenience interceptor to allow operations to be performed after the commit is performed but before returning control to the application.
void	preRollback(javax.jdo.Transaction tx) Convenience interceptor to allow operations to be performed before any rollback is performed.
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	replaceField(int fieldNumber, java.lang.Object value) 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 replaceDirtyFields) Method to update the data in the object with the values from the passed FieldManager
void	replaceNonLoadedFields(int[] fieldNumbers, FieldManager fm) Method to update the data in the object with the values from the passed FieldManager.
java.lang.Object	replaceSCOField(int fieldNumber, java.lang.Object value) Wrap a field value with a SCO instance
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(javax.jdo.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	setExternalFieldValueForMapping(JavaTypeMapping mapping, java.lang.Object value) Method to set the value for an external field stored against this object
void	setPcObjectType(int embeddedType) Method to set this StateManager as managing an embedded/serialised object.
void	setPostStoreNewObjectId(java.lang.Object id) If the id is obtained after inserting the object into the database, set new a new id for persistent classes (for example, increment).
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) Drop any loaded state for the given field, so upon next access it will get reloaded.
void	unsetStoringPC() Method to unset the storing PC flag.
void	updateFieldAfterInsert(javax.jdo.spi.PersistenceCapable 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.

Methods inherited from interface javax.jdo.spi.StateManager

getBooleanField, getByteField, getCharField, getDoubleField, getFloatField, getIntField, getLongField, getObjectField, getObjectId, getPersistenceManager, getShortField, getStringField, getTransactionalObjectId, getVersion, isDeleted, isDirty, isLoaded, isNew, isPersistent, isTransactional, makeDirty, preSerialize, providedBooleanField, providedByteField, providedCharField, providedDoubleField, providedFloatField, providedIntField, providedLongField, providedObjectField, providedShortField, providedStringField, replacingBooleanField, replacingByteField, replacingCharField, replacingDetachedState, replacingDoubleField, replacingFlags, replacingFloatField, replacingIntField, replacingLongField, replacingObjectField, replacingShortField, replacingStateManager, replacingStringField, setBooleanField, setByteField, setCharField, setDoubleField, setFloatField, setIntField, setLongField, setObjectField, setShortField, setStringField

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

getObject

javax.jdo.spi.PersistenceCapable 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(javax.jdo.spi.PersistenceCapable pc)

return a copy from the object Id

Parameters:

pc - the PersistenceCapable object

Returns:

the object id

getPersistenceManager

PersistenceManager getPersistenceManager()

Returns the PersistenceManager that owns the StateManager instance

Returns:

PersistenceManager

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(javax.jdo.spi.PersistenceCapable pc,
                            int fieldNumber)

Marks the given field dirty for issuing an update after the insert.

Parameters:

pc - The Persistence Capable object

fieldNumber - The no of field to mark as dirty.

changeActivityState

void changeActivityState(ActivityState activityState,
                         DatastoreClass table)

Update the acitvity state.

Parameters:

activityState - the activity state

table - Datastore class that has just been processed

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(javax.jdo.spi.PersistenceCapable detachedPC,
                            boolean embedded)

Method to attach to this the detached PersistenceCapable instance

Parameters:

detachedPC - the detached PersistenceCapable instance to be attached

embedded - Whether it is embedded

Returns:

The attached copy

Since:

1.1

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

Since:

1.1

detach

void detach(FetchPlanState state)

Method to detach the PersistenceCapable object.

Parameters:

state - State for the detachment process

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 javax.jdo.JDOObjectNotFoundException.

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(javax.jdo.FetchPlan fetchPlan)

Method to retrieve the object.

Parameters:

fetchPlan - the fetch plan to load fields

postCommit

void postCommit(javax.jdo.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(javax.jdo.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.

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

replaceField

void replaceField(int fieldNumber,
                  java.lang.Object value)

Method to change the value of the specified field.

Parameters:

fieldNumber - (absolute) field number of the field

value - The new value.

replaceFields

void replaceFields(int[] fieldNumbers,
                   FieldManager fm,
                   boolean replaceDirtyFields)

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

replaceDirtyFields - Whether to replace any dirty fields

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

newSCOInstance

java.lang.Object newSCOInstance(int fieldNumber,
                                java.lang.Object value,
                                boolean forUpdate)

Method to create a new SCO wrapper for a second class field.

Parameters:

fieldNumber - Number of the field

value - The value to give it

forUpdate - Whether it needs updating in the datastore

Returns:

The SCO wrapper

replaceSCOField

java.lang.Object replaceSCOField(int fieldNumber,
                                 java.lang.Object value)

Wrap a field value with a SCO instance

Parameters:

fieldNumber -

value - the value to be wrapped

Returns:

the new SCO instance

newSCOEmptyInstance

java.lang.Object newSCOEmptyInstance(int fieldNumber)

Method to return an empty SCO wrapper for the specified field.

Parameters:

fieldNumber - (absolute) field number of the SCO field to wrap

Returns:

The (empty) SCO wrapper

getAttachedPC

java.lang.Object getAttachedPC()

When an object is being attached it will temporarily have a StateManager connected, and during this time this method gives access to the attached variant of the object.

Returns:

The attached PC object (or null if not temporarily connected detached object)

isInserting

boolean isInserting()

Tests whether this object is being inserted.

Returns:

true if this instance is inserting.

isInserted

boolean isInserted(int fieldNumber)

Returns whether the field of this object is inserted in the datastore. Only applies during the makePersistent process.

Parameters:

fieldNumber - Number of the field

Returns:

Whether it is inserted to the level of this field

setPostStoreNewObjectId

void setPostStoreNewObjectId(java.lang.Object id)

If the id is obtained after inserting the object into the database, set new a new id for persistent classes (for example, increment).

Parameters:

id - the id received from the datastore

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(javax.jdo.spi.PersistenceCapable pc)

Return the object representing the transactional version of the calling instance.

Parameters:

pc - the calling PersistenceCapable instance

Returns:

the object representing the version of the calling instance

Since:

1.1.1

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

getL2CacheableObject

CachedPC getL2CacheableObject()

Accessor for an L2 cacheable form of this object.

Returns:

The L2 cacheable object

dump

void dump(java.io.PrintWriter out)

Diagnostic method to dump the current state to the provided PrintWriter.

Parameters:

out - The PrintWriter

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

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.

Since:

1.1

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(javax.jdo.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

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.

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.

Since:

1.1

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

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.

unloadField

void unloadField(java.lang.String fieldName)

Drop any loaded state for the given field, so upon next access it will get reloaded.

Parameters:

fieldName -

setExternalFieldValueForMapping

void setExternalFieldValueForMapping(JavaTypeMapping mapping,
                                     java.lang.Object value)

Method to set the value for an external field stored against this object

Parameters:

mapping - The mapping for the (external) field

value - The value that this field has

getValueForExternalField

java.lang.Object getValueForExternalField(JavaTypeMapping mapping)

Accessor for the value of an external field. This is used when inserting this object so that we can insert the external field values too.

Parameters:

mapping - The external field mapping

Returns:

The value for this mapping