oracle.toplink.essentials.descriptors

Class VersionLockingPolicy

java.lang.Object

oracle.toplink.essentials.descriptors.VersionLockingPolicy

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, OptimisticLockingPolicy

Direct Known Subclasses:

TimestampLockingPolicy

public class VersionLockingPolicy
extends java.lang.Object
implements OptimisticLockingPolicy, java.io.Serializable

Purpose: Used to allow a single version number to be used for optimistic locking.

Since:

TOPLink/Java 2.0

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
protected Expression	cachedExpression
protected ClassDescriptor	descriptor
static int	IN_CACHE
static int	IN_OBJECT
protected int	lockValueStored
protected DatabaseField	writeLockField

Constructor Summary

Constructors

Constructor and Description
VersionLockingPolicy() PUBLIC: Create a new VersionLockingPolicy.
VersionLockingPolicy(DatabaseField field) PUBLIC: Create a new VersionLockingPolicy.
VersionLockingPolicy(java.lang.String fieldName) PUBLIC: Create a new VersionLockingPolicy.

Method Summary

Modifier and Type	Method and Description
void	addLockFieldsToUpdateRow(AbstractRecord databaseRow, AbstractSession session) INTERNAL: Add update fields for template row.
void	addLockValuesToTranslationRow(ObjectLevelModifyQuery query) INTERNAL: This method adds the lock value to the translation row of the passed in query.
Expression	buildDeleteExpression(DatabaseTable table, Expression mainExpression, AbstractRecord row) INTERNAL: When given an expression, this method will return a new expression with the optimistic locking values included.
protected Expression	buildExpression() INTERNAL: Returns an expression that will be used for both the update and delete where clause
Expression	buildUpdateExpression(DatabaseTable table, Expression mainExpression, AbstractRecord row, AbstractRecord row2) INTERNAL: When given an expression, this method will return a new expression with the optimistic locking values included.
java.lang.Object	clone() INTERNAL: Clone the policy
int	compareWriteLockValues(java.lang.Object value1, java.lang.Object value2) INTERNAL: This method compares two writeLockValues.
java.lang.Object	getBaseValue() INTERNAL: This is the base value that is older than all other values, it is used in the place of null in some situations.
protected java.lang.Class	getDefaultLockingFieldType() INTERNAL: Return the default version locking filed java type, default is BigDecimal
protected ClassDescriptor	getDescriptor() INTERNAL:
protected java.lang.Object	getInitialWriteValue(AbstractSession session) INTERNAL: returns the initial locking value
protected java.lang.Object	getNewLockValue(ModifyQuery query) INTERNAL: This method gets the write lock value from either the cache or the object stored in the query.
protected java.util.Vector	getUnmappedFields() INTERNAL: This method returns any of the fields that are not mapped in the object.
java.lang.Object	getValueToPutInCache(AbstractRecord row, AbstractSession session) INTERNAL: Return the value that should be stored in the identity map.
int	getVersionDifference(java.lang.Object currentValue, java.lang.Object domainObject, java.util.Vector primaryKeys, AbstractSession session) PUBLIC: Return the number of versions different between these objects.
DatabaseField	getWriteLockField() INTERNAL: Return the write lock field.
java.lang.String	getWriteLockFieldName() PUBLIC: Return the field name of the field that stores the write lock value.
Expression	getWriteLockUpdateExpression(ExpressionBuilder builder) INTERNAL: Retrun an expression that updates the write lock
java.lang.Object	getWriteLockValue(java.lang.Object domainObject, java.util.Vector primaryKey, AbstractSession session) INTERNAL: This method will return the optimistic lock value for the object
protected java.lang.Number	incrementWriteLockValue(java.lang.Number numberValue) INTERNAL: adds 1 to the value passed in
void	initialize(AbstractSession session) INTERNAL: It is responsible for initializing the policy;
void	initializeProperties() INTERNAL: It is responsible for initializing the policy properties;
boolean	isChildWriteLockValueGreater(AbstractSession session, java.util.Vector primaryKey, java.lang.Class original, ObjectChangeSet changeSet) INTERNAL: Update the parent write lock value if the unit of works has been incremented.
boolean	isChildWriteLockValueGreater(UnitOfWorkImpl uow, java.util.Vector primaryKey, java.lang.Class original) INTERNAL: Update the parent write lock value if the unit of works has been incremented.
boolean	isNewerVersion(AbstractRecord databaseRow, java.lang.Object domainObject, java.util.Vector primaryKey, AbstractSession session) INTERNAL: Compares the value from the row and from the object (or cache).
boolean	isNewerVersion(java.lang.Object currentValue, java.lang.Object domainObject, java.util.Vector primaryKey, AbstractSession session) INTERNAL: Compares the value with the value from the object (or cache).
boolean	isStoredInCache() PUBLIC: Return true if the lock value is stored in the cache.
boolean	isStoredInObject() PUBLIC: Return true if the lock value is stored in the object.
protected java.lang.Object	lockValueFromObject(java.lang.Object domainObject) INTERNAL: retrieves the lock value from the object.
protected DatabaseMapping	mappingFromLockField() INTERNAL: returns the mapping from the writelock field.
void	mergeIntoParentCache(UnitOfWorkImpl uow, java.util.Vector primaryKey, java.lang.Object object) INTERNAL: Only applicable when the value is stored in the cache.
void	prepareFetchGroupForReadQuery(FetchGroup fetchGroup, ObjectLevelReadQuery query) INTERNAL: Prepare fetch group for read query
void	setDescriptor(ClassDescriptor descriptor) INTERNAL:
void	setIsStoredInCache(boolean isStoredInCache) PUBLIC: Set whether to store the lock in the cache or in the object.
void	setupWriteFieldsForInsert(ObjectLevelModifyQuery query) INTERNAL: This method must be included in any locking policy.
void	setWriteLockField(DatabaseField writeLockField) ADVANCED: Set the write lock field.
void	setWriteLockFieldName(java.lang.String writeLockFieldName) PUBLIC: Set the write lock field name.
void	storeInCache() PUBLIC: Configure the version lock value to be stored in the cache.
void	storeInObject() PUBLIC: Configure the version lock value to be stored in the object.
void	updateRowAndObjectForUpdate(ObjectLevelModifyQuery query, java.lang.Object domainObject) INTERNAL: This method updates the modify row, and the domain object with the new lock value.
protected void	updateWriteLockValueForWrite(ObjectLevelModifyQuery query, java.lang.Object lockValue) INTERNAL: Update the row, object and change set with the version value.
void	validateDelete(int rowCount, java.lang.Object object, WriteObjectQuery query) INTERNAL: Check the row count for lock failure.
void	validateUpdate(int rowCount, java.lang.Object object, WriteObjectQuery owner) INTERNAL: Check the row count for lock failure.
void	writeLockValueIntoRow(ObjectLevelModifyQuery query, java.lang.Object domainObject) INTERNAL: This method updates the modify row with the old lock value.

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

writeLockField

protected DatabaseField writeLockField

lockValueStored

protected int lockValueStored

descriptor

protected ClassDescriptor descriptor

cachedExpression

protected transient Expression cachedExpression

IN_CACHE

public static final int IN_CACHE

See Also:

Constant Field Values

IN_OBJECT

public static final int IN_OBJECT

See Also:

Constant Field Values

Constructor Detail

VersionLockingPolicy

public VersionLockingPolicy()

PUBLIC: Create a new VersionLockingPolicy. Defaults to storing the lock value in the cache.

VersionLockingPolicy

public VersionLockingPolicy(java.lang.String fieldName)

PUBLIC: Create a new VersionLockingPolicy. Defaults to storing the lock value in the cache.

Parameters:

fieldName - specifies the field name for the write lock field.

VersionLockingPolicy

public VersionLockingPolicy(DatabaseField field)

PUBLIC: Create a new VersionLockingPolicy. Defaults to storing the lock value in the cache.

Parameters:

the - write lock field.

Method Detail

addLockFieldsToUpdateRow

public void addLockFieldsToUpdateRow(AbstractRecord databaseRow,
                                     AbstractSession session)

INTERNAL: Add update fields for template row. These are any unmapped fields required to write in an update.

Specified by:

addLockFieldsToUpdateRow in interface OptimisticLockingPolicy

addLockValuesToTranslationRow

public void addLockValuesToTranslationRow(ObjectLevelModifyQuery query)

INTERNAL: This method adds the lock value to the translation row of the passed in query. depending on the storage flag, the value is either retrieved from the cache of the object.

Specified by:

addLockValuesToTranslationRow in interface OptimisticLockingPolicy

buildDeleteExpression

public Expression buildDeleteExpression(DatabaseTable table,
                                        Expression mainExpression,
                                        AbstractRecord row)

INTERNAL: When given an expression, this method will return a new expression with the optimistic locking values included. The values are taken from the passed in database row. This expression will be used in a delete call.

Specified by:

buildDeleteExpression in interface OptimisticLockingPolicy

buildExpression

protected Expression buildExpression()

INTERNAL: Returns an expression that will be used for both the update and delete where clause

buildUpdateExpression

public Expression buildUpdateExpression(DatabaseTable table,
                                        Expression mainExpression,
                                        AbstractRecord row,
                                        AbstractRecord row2)

INTERNAL: When given an expression, this method will return a new expression with the optimistic locking values included. The values are taken from the passed in database row. This expression will be used in an update call.

Specified by:

buildUpdateExpression in interface OptimisticLockingPolicy

clone

public java.lang.Object clone()

INTERNAL: Clone the policy

Specified by:

clone in interface OptimisticLockingPolicy

Overrides:

clone in class java.lang.Object

compareWriteLockValues

public int compareWriteLockValues(java.lang.Object value1,
                                  java.lang.Object value2)

INTERNAL: This method compares two writeLockValues. The writeLockValues should be non-null and of type Number. Returns: -1 if value1 is less (older) than value2; 0 if value1 equals value2; 1 if value1 is greater (newer) than value2. Throws: NullPointerException if the passed value is null; ClassCastException if the passed value is of a wrong type.

Specified by:

compareWriteLockValues in interface OptimisticLockingPolicy

getDefaultLockingFieldType

protected java.lang.Class getDefaultLockingFieldType()

INTERNAL: Return the default version locking filed java type, default is BigDecimal

getBaseValue

public java.lang.Object getBaseValue()

INTERNAL: This is the base value that is older than all other values, it is used in the place of null in some situations.

Specified by:

getBaseValue in interface OptimisticLockingPolicy

getDescriptor

protected ClassDescriptor getDescriptor()

INTERNAL:

getInitialWriteValue

protected java.lang.Object getInitialWriteValue(AbstractSession session)

INTERNAL: returns the initial locking value

getNewLockValue

protected java.lang.Object getNewLockValue(ModifyQuery query)

INTERNAL: This method gets the write lock value from either the cache or the object stored in the query. It then returns the new incremented value.

getUnmappedFields

protected java.util.Vector getUnmappedFields()

INTERNAL: This method returns any of the fields that are not mapped in the object. In the case of the value being stored in the cache, a vector with one value is returned. In the case of being stored in the object, an empty vector is returned.

getValueToPutInCache

public java.lang.Object getValueToPutInCache(AbstractRecord row,
                                             AbstractSession session)

INTERNAL: Return the value that should be stored in the identity map. If the value is stored in the object, then return a null.

Specified by:

getValueToPutInCache in interface OptimisticLockingPolicy

getVersionDifference

public int getVersionDifference(java.lang.Object currentValue,
                                java.lang.Object domainObject,
                                java.util.Vector primaryKeys,
                                AbstractSession session)

PUBLIC: Return the number of versions different between these objects.

Specified by:

getVersionDifference in interface OptimisticLockingPolicy

Parameters:

currentValue - the new lock value

domainObject - the object containing the version to be compared to

primaryKeys - a vector containing the primary keys of the domainObject

session - the session to be used with the comparison

getWriteLockField

public DatabaseField getWriteLockField()

INTERNAL: Return the write lock field.

Specified by:

getWriteLockField in interface OptimisticLockingPolicy

getWriteLockFieldName

public java.lang.String getWriteLockFieldName()

PUBLIC: Return the field name of the field that stores the write lock value.

getWriteLockUpdateExpression

public Expression getWriteLockUpdateExpression(ExpressionBuilder builder)

INTERNAL: Retrun an expression that updates the write lock

Specified by:

getWriteLockUpdateExpression in interface OptimisticLockingPolicy

getWriteLockValue

public java.lang.Object getWriteLockValue(java.lang.Object domainObject,
                                          java.util.Vector primaryKey,
                                          AbstractSession session)

INTERNAL: This method will return the optimistic lock value for the object

Specified by:

getWriteLockValue in interface OptimisticLockingPolicy

incrementWriteLockValue

protected java.lang.Number incrementWriteLockValue(java.lang.Number numberValue)

INTERNAL: adds 1 to the value passed in

initialize

public void initialize(AbstractSession session)

INTERNAL: It is responsible for initializing the policy;

Specified by:

initialize in interface OptimisticLockingPolicy

initializeProperties

public void initializeProperties()

INTERNAL: It is responsible for initializing the policy properties;

Specified by:

initializeProperties in interface OptimisticLockingPolicy

isChildWriteLockValueGreater

public boolean isChildWriteLockValueGreater(AbstractSession session,
                                            java.util.Vector primaryKey,
                                            java.lang.Class original,
                                            ObjectChangeSet changeSet)

INTERNAL: Update the parent write lock value if the unit of works has been incremented.

Specified by:

isChildWriteLockValueGreater in interface OptimisticLockingPolicy

isChildWriteLockValueGreater

public boolean isChildWriteLockValueGreater(UnitOfWorkImpl uow,
                                            java.util.Vector primaryKey,
                                            java.lang.Class original)

INTERNAL: Update the parent write lock value if the unit of works has been incremented.

Specified by:

isChildWriteLockValueGreater in interface OptimisticLockingPolicy

isNewerVersion

public boolean isNewerVersion(java.lang.Object currentValue,
                              java.lang.Object domainObject,
                              java.util.Vector primaryKey,
                              AbstractSession session)

INTERNAL: Compares the value with the value from the object (or cache). Will return true if the object is newer.

Specified by:

isNewerVersion in interface OptimisticLockingPolicy

isNewerVersion

public boolean isNewerVersion(AbstractRecord databaseRow,
                              java.lang.Object domainObject,
                              java.util.Vector primaryKey,
                              AbstractSession session)

INTERNAL: Compares the value from the row and from the object (or cache). Will return true if the object is newer than the row.

Specified by:

isNewerVersion in interface OptimisticLockingPolicy

isStoredInCache

public boolean isStoredInCache()

PUBLIC: Return true if the lock value is stored in the cache.

isStoredInObject

public boolean isStoredInObject()

PUBLIC: Return true if the lock value is stored in the object.

lockValueFromObject

protected java.lang.Object lockValueFromObject(java.lang.Object domainObject)

INTERNAL: retrieves the lock value from the object.

mappingFromLockField

protected DatabaseMapping mappingFromLockField()

INTERNAL: returns the mapping from the writelock field. returns null if not found

mergeIntoParentCache

public void mergeIntoParentCache(UnitOfWorkImpl uow,
                                 java.util.Vector primaryKey,
                                 java.lang.Object object)

INTERNAL: Only applicable when the value is stored in the cache. Will merge with the parent unit of work.

Specified by:

mergeIntoParentCache in interface OptimisticLockingPolicy

setDescriptor

public void setDescriptor(ClassDescriptor descriptor)

INTERNAL:

Specified by:

setDescriptor in interface OptimisticLockingPolicy

setIsStoredInCache

public void setIsStoredInCache(boolean isStoredInCache)

PUBLIC: Set whether to store the lock in the cache or in the object.

Parameters:

isStoredInCache - set this to true if you would like to store lock in the cache and set it to false if you would like to store it in the object.

setupWriteFieldsForInsert

public void setupWriteFieldsForInsert(ObjectLevelModifyQuery query)

INTERNAL: This method must be included in any locking policy. Put the initial writelock value into the modifyRow.

Specified by:

setupWriteFieldsForInsert in interface OptimisticLockingPolicy

updateWriteLockValueForWrite

protected void updateWriteLockValueForWrite(ObjectLevelModifyQuery query,
                                            java.lang.Object lockValue)

INTERNAL: Update the row, object and change set with the version value. This handles the version being mapped in nested aggregates, writable or read-only.

setWriteLockField

public void setWriteLockField(DatabaseField writeLockField)

ADVANCED: Set the write lock field. This can be used for advanced field types, such as XML nodes, or to set the field type.

setWriteLockFieldName

public void setWriteLockFieldName(java.lang.String writeLockFieldName)

PUBLIC: Set the write lock field name.

Parameters:

writeLockFieldName - the name of the field to lock against.

storeInCache

public void storeInCache()

PUBLIC: Configure the version lock value to be stored in the cache. This allows for the object not to require to store its version value as an attribute. Note: if using a stateless model where the object can be passed to a client and then later updated in a different transaction context, then the version lock value should not be stored in the cache, but in the object to ensure it is the correct value for that object. This is the default.

storeInObject

public void storeInObject()

PUBLIC: Configure the version lock value to be stored in the object. The object must define a mapping and an attribute to store the version value. Note: the value will be updated internally by TopLink and should not be updated by the application.

updateRowAndObjectForUpdate

public void updateRowAndObjectForUpdate(ObjectLevelModifyQuery query,
                                        java.lang.Object domainObject)

INTERNAL: This method updates the modify row, and the domain object with the new lock value. #see this method in VersionLockingPolicy

Specified by:

updateRowAndObjectForUpdate in interface OptimisticLockingPolicy

writeLockValueIntoRow

public void writeLockValueIntoRow(ObjectLevelModifyQuery query,
                                  java.lang.Object domainObject)

INTERNAL: This method updates the modify row with the old lock value.

validateDelete

public void validateDelete(int rowCount,
                           java.lang.Object object,
                           WriteObjectQuery query)

INTERNAL: Check the row count for lock failure.

Specified by:

validateDelete in interface OptimisticLockingPolicy

validateUpdate

public void validateUpdate(int rowCount,
                           java.lang.Object object,
                           WriteObjectQuery owner)

INTERNAL: Check the row count for lock failure.

Specified by:

validateUpdate in interface OptimisticLockingPolicy

prepareFetchGroupForReadQuery

public void prepareFetchGroupForReadQuery(FetchGroup fetchGroup,
                                          ObjectLevelReadQuery query)

INTERNAL: Prepare fetch group for read query

Specified by:

prepareFetchGroupForReadQuery in interface OptimisticLockingPolicy