EclipseLink 2.0.0, build 'v20091127-r5931' API Reference

org.eclipse.persistence.descriptors
Class FieldsLockingPolicy

java.lang.Object
  extended by org.eclipse.persistence.descriptors.FieldsLockingPolicy
All Implemented Interfaces:
java.io.Serializable, java.lang.Cloneable, org.eclipse.persistence.internal.descriptors.OptimisticLockingPolicy
Direct Known Subclasses:
AllFieldsLockingPolicy, ChangedFieldsLockingPolicy, SelectedFieldsLockingPolicy

public abstract class FieldsLockingPolicy
extends java.lang.Object
implements org.eclipse.persistence.internal.descriptors.OptimisticLockingPolicy

Purpose: An abstract superclass of some implementations of the OptimisticLockingPolicy interface. All of the subclasses of this class implement OptimisticLocking based on mapped fields in the object. These fields are only compared and not modified. Any modification (incrementing etc..) must be handled by the application.

See Also:
AllFieldsLockingPolicy, ChangedFieldsLockingPolicy, SelectedFieldsLockingPolicy, Serialized Form
Author:
Peter Krogh
Since:
TopLink 2.1

Nested Class Summary
 
Nested classes/interfaces inherited from interface org.eclipse.persistence.internal.descriptors.OptimisticLockingPolicy
org.eclipse.persistence.internal.descriptors.OptimisticLockingPolicy.LockOnChange
 
Field Summary
protected  java.util.Vector allNonPrimaryKeyFields
           
protected  ClassDescriptor descriptor
           
 
Constructor Summary
FieldsLockingPolicy()
          PUBLIC: Create a new field locking policy.
 
Method Summary
 void addLockFieldsToUpdateRow(org.eclipse.persistence.internal.sessions.AbstractRecord Record, org.eclipse.persistence.internal.sessions.AbstractSession session)
          INTERNAL: Add update fields for template row.
abstract  void addLockValuesToTranslationRow(ObjectLevelModifyQuery query)
          INTERNAL: Values to be included in the locking mechanism are added to the translation row.
protected  java.util.Vector buildAllNonPrimaryKeyFields()
          INTERNAL: Returns the fields that should be compared in the where clause.
 Expression buildDeleteExpression(org.eclipse.persistence.internal.helper.DatabaseTable table, Expression mainExpression, org.eclipse.persistence.internal.sessions.AbstractRecord row)
          INTERNAL: When given an expression, this method will return a new expression with the optimistic locking values included.
protected  Expression buildExpression(org.eclipse.persistence.internal.helper.DatabaseTable table, org.eclipse.persistence.internal.sessions.AbstractRecord transRow, org.eclipse.persistence.internal.sessions.AbstractRecord modifyRow, ExpressionBuilder builder)
          INTERNAL: returns the expression to be used in both the delete and update where clause.
 Expression buildUpdateExpression(org.eclipse.persistence.internal.helper.DatabaseTable table, Expression mainExpression, org.eclipse.persistence.internal.sessions.AbstractRecord transRow, org.eclipse.persistence.internal.sessions.AbstractRecord modifyRow)
          INTERNAL: This method must be included in any locking policy.
 java.lang.Object clone()
          INTERNAL: Clone the policy
 int compareWriteLockValues(java.lang.Object value1, java.lang.Object value2)
          INTERNAL: This method shouldn't be called if supportsWriteLockValuesComparison() returns false.
protected  java.util.Vector getAllNonPrimaryKeyFields()
          INTERNAL: Returns the fields that should be compared in the where clause.
protected  java.util.Vector getAllNonPrimaryKeyFields(org.eclipse.persistence.internal.helper.DatabaseTable table)
          INTERNAL: filter the fields based on the passed in table.
 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 abstract  java.util.Vector getFieldsToCompare(org.eclipse.persistence.internal.helper.DatabaseTable table, org.eclipse.persistence.internal.sessions.AbstractRecord transRow, org.eclipse.persistence.internal.sessions.AbstractRecord modifyRow)
          INTERNAL: Returns the fields that should be compared in the where clause.
 org.eclipse.persistence.internal.descriptors.OptimisticLockingPolicy.LockOnChange getLockOnChangeMode()
          ADVANCED: returns the LockOnChange mode for this policy.
 java.lang.Object getValueToPutInCache(org.eclipse.persistence.internal.sessions.AbstractRecord row, org.eclipse.persistence.internal.sessions.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, org.eclipse.persistence.internal.sessions.AbstractSession session)
          INTERNAL: Return the number of version difference between the two states of the object.
 org.eclipse.persistence.internal.helper.DatabaseField getWriteLockField()
          INTERNAL: Return the write lock field.
 Expression getWriteLockUpdateExpression(ExpressionBuilder builder, org.eclipse.persistence.internal.sessions.AbstractSession session)
          INTERNAL:
 java.lang.Object getWriteLockValue(java.lang.Object domainObject, java.util.Vector primaryKey, org.eclipse.persistence.internal.sessions.AbstractSession session)
          INTERNAL: This method will return the optimistic lock value for the object
 void initialize(org.eclipse.persistence.internal.sessions.AbstractSession session)
          INTERNAL: It is responsible for initializing the policy;
 void initializeProperties()
          INTERNAL: It is responsible for initializing the policy;
 boolean isCascaded()
          PUBLIC: Return true if the policy uses cascade locking.
 boolean isNewerVersion(org.eclipse.persistence.internal.sessions.AbstractRecord Record, java.lang.Object domainObject, java.util.Vector primaryKey, org.eclipse.persistence.internal.sessions.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, org.eclipse.persistence.internal.sessions.AbstractSession session)
          INTERNAL: Compares the value and the value from the object (or cache).
protected  boolean isPrimaryKey(org.eclipse.persistence.internal.helper.DatabaseField dbField)
          INTERNAL: Returns whether or not this field is a primary key.
 boolean isStoredInCache()
          PUBLIC: Return true if the lock value is stored in the cache.
 void mergeIntoParentCache(org.eclipse.persistence.internal.sessions.UnitOfWorkImpl uow, java.util.Vector primaryKey, java.lang.Object object)
          INTERNAL: Only applicable when the value is stored in the cache.
protected  void setAllNonPrimaryKeyFields(java.util.Vector allNonPrimaryKeyFields)
          INTERNAL: Set method for all the primary keys
 void setDescriptor(ClassDescriptor descriptor)
          INTERNAL: Set method for the descriptor
 void setLockOnChangeMode(org.eclipse.persistence.internal.descriptors.OptimisticLockingPolicy.LockOnChange lockOnChangeMode)
          ADVANCED: Sets the LockOnChange mode for this policy.
 void setupWriteFieldsForInsert(ObjectLevelModifyQuery query)
          INTERNAL: Put the initial writelock value into the modifyRow.
 boolean shouldUpdateVersionOnMappingChange()
          INTERNAL: Returns true if the policy has been set to set an optimistic read lock when any mapping changes.
 boolean shouldUpdateVersionOnOwnedMappingChange()
          INTERNAL: Returns true if the policy has been set to set an optimistic read lock when a owning mapping changes.
 boolean supportsWriteLockValuesComparison()
          INTERNAL: Indicates whether compareWriteLockValues method is supported by the policy.
 void updateRowAndObjectForUpdate(ObjectLevelModifyQuery query, java.lang.Object domainObject)
          INTERNAL: Nothing to do because all updates are handled by the application
 void validateDelete(int rowCount, java.lang.Object object, DeleteObjectQuery query)
          INTERNAL: Check the row count for lock failure.
 void validateUpdate(int rowCount, java.lang.Object object, WriteObjectQuery query)
          INTERNAL: Check the row count for lock failure.
protected  void verifyUsage(org.eclipse.persistence.internal.sessions.AbstractSession session)
          INTERNAL: throw an exception if not inside a unit of work at this point
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

descriptor

protected ClassDescriptor descriptor

allNonPrimaryKeyFields

protected java.util.Vector allNonPrimaryKeyFields
Constructor Detail

FieldsLockingPolicy

public FieldsLockingPolicy()
PUBLIC: Create a new field locking policy. A field locking policy is based on locking on a subset of fields by comparing with their previous values to detect field-level collisions. Note: the unit of work must be used for all updates when using field locking.

Method Detail

addLockFieldsToUpdateRow

public void addLockFieldsToUpdateRow(org.eclipse.persistence.internal.sessions.AbstractRecord Record,
                                     org.eclipse.persistence.internal.sessions.AbstractSession session)
INTERNAL: Add update fields for template row. These are any unmapped fields required to write in an update. Since all fields are mapped, there is nothing required.

Specified by:
addLockFieldsToUpdateRow in interface org.eclipse.persistence.internal.descriptors.OptimisticLockingPolicy

addLockValuesToTranslationRow

public abstract void addLockValuesToTranslationRow(ObjectLevelModifyQuery query)
INTERNAL: Values to be included in the locking mechanism are added to the translation row. Set the translation row to all the original field values.

Specified by:
addLockValuesToTranslationRow in interface org.eclipse.persistence.internal.descriptors.OptimisticLockingPolicy

buildAllNonPrimaryKeyFields

protected java.util.Vector buildAllNonPrimaryKeyFields()
INTERNAL: Returns the fields that should be compared in the where clause. In this case, it is all the fields, except for the primary key and class indicator fields. This is called durring lazy initialization


buildDeleteExpression

public Expression buildDeleteExpression(org.eclipse.persistence.internal.helper.DatabaseTable table,
                                        Expression mainExpression,
                                        org.eclipse.persistence.internal.sessions.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 org.eclipse.persistence.internal.descriptors.OptimisticLockingPolicy

buildExpression

protected Expression buildExpression(org.eclipse.persistence.internal.helper.DatabaseTable table,
                                     org.eclipse.persistence.internal.sessions.AbstractRecord transRow,
                                     org.eclipse.persistence.internal.sessions.AbstractRecord modifyRow,
                                     ExpressionBuilder builder)
INTERNAL: returns the expression to be used in both the delete and update where clause.


buildUpdateExpression

public Expression buildUpdateExpression(org.eclipse.persistence.internal.helper.DatabaseTable table,
                                        Expression mainExpression,
                                        org.eclipse.persistence.internal.sessions.AbstractRecord transRow,
                                        org.eclipse.persistence.internal.sessions.AbstractRecord modifyRow)
INTERNAL: This method must be included in any locking policy. 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:
buildUpdateExpression in interface org.eclipse.persistence.internal.descriptors.OptimisticLockingPolicy

clone

public java.lang.Object clone()
INTERNAL: Clone the policy

Specified by:
clone in interface org.eclipse.persistence.internal.descriptors.OptimisticLockingPolicy
Overrides:
clone in class java.lang.Object

supportsWriteLockValuesComparison

public boolean supportsWriteLockValuesComparison()
INTERNAL: Indicates whether compareWriteLockValues method is supported by the policy. Numeric or timestamp lock values could be compared: for every pair of values v1 and v2 - either v1v2. However it's impossible to compare values for FieldsLockingPolicy for two reasons: 1. there is no "linear order": v1v2 is not defined: either v1==v2 or v1!=v2; 2. locking value is not a single field which is not part of mapped object value but rather a set of object's mapped fields. That means any object's mapped attribute change is potentially a change of the locking value. For ChangedFieldsLockingPolicy every mapped attribute's change is a change of locking value. The pattern used by versioning: "if the original locking value is unchanged then the object hasn't been changed outside of the application", which allows to distinguish between the change made inside and outside the application, doesn't work for fields locking. It degenerates into useless pattern: "if the original locking value is unchanged then the object hasn't been changed". Use compareWriteLockValues method only if this method returns true.

Specified by:
supportsWriteLockValuesComparison in interface org.eclipse.persistence.internal.descriptors.OptimisticLockingPolicy

compareWriteLockValues

public int compareWriteLockValues(java.lang.Object value1,
                                  java.lang.Object value2)
INTERNAL: This method shouldn't be called if supportsWriteLockValuesComparison() returns false. This method compares two writeLockValues. The writeLockValues should be non-null and of the correct type. 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 org.eclipse.persistence.internal.descriptors.OptimisticLockingPolicy

getAllNonPrimaryKeyFields

protected java.util.Vector getAllNonPrimaryKeyFields()
INTERNAL: Returns the fields that should be compared in the where clause. In this case, it is all the fields, except for the primary key and class indicator field.


getAllNonPrimaryKeyFields

protected java.util.Vector getAllNonPrimaryKeyFields(org.eclipse.persistence.internal.helper.DatabaseTable table)
INTERNAL: filter the fields based on the passed in table. Only return fields of this table.


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 org.eclipse.persistence.internal.descriptors.OptimisticLockingPolicy

getFieldsToCompare

protected abstract java.util.Vector getFieldsToCompare(org.eclipse.persistence.internal.helper.DatabaseTable table,
                                                       org.eclipse.persistence.internal.sessions.AbstractRecord transRow,
                                                       org.eclipse.persistence.internal.sessions.AbstractRecord modifyRow)
INTERNAL: Returns the fields that should be compared in the where clause. This method must be implemented by the subclass


getWriteLockField

public org.eclipse.persistence.internal.helper.DatabaseField getWriteLockField()
INTERNAL: Return the write lock field.

Specified by:
getWriteLockField in interface org.eclipse.persistence.internal.descriptors.OptimisticLockingPolicy

getWriteLockUpdateExpression

public Expression getWriteLockUpdateExpression(ExpressionBuilder builder,
                                               org.eclipse.persistence.internal.sessions.AbstractSession session)
INTERNAL:

Specified by:
getWriteLockUpdateExpression in interface org.eclipse.persistence.internal.descriptors.OptimisticLockingPolicy

getLockOnChangeMode

public org.eclipse.persistence.internal.descriptors.OptimisticLockingPolicy.LockOnChange getLockOnChangeMode()
ADVANCED: returns the LockOnChange mode for this policy. This mode specifies if a Optimistic Write lock should be enforced on this entity when a set of mappings are changed. Unfortunately this locking policy can not enforce an optimistic write lock unless a FK or DTF field has changed so this type returns LockOnChange.NONE

Specified by:
getLockOnChangeMode in interface org.eclipse.persistence.internal.descriptors.OptimisticLockingPolicy

getValueToPutInCache

public java.lang.Object getValueToPutInCache(org.eclipse.persistence.internal.sessions.AbstractRecord row,
                                             org.eclipse.persistence.internal.sessions.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 org.eclipse.persistence.internal.descriptors.OptimisticLockingPolicy

getVersionDifference

public int getVersionDifference(java.lang.Object currentValue,
                                java.lang.Object domainObject,
                                java.util.Vector primaryKeys,
                                org.eclipse.persistence.internal.sessions.AbstractSession session)
INTERNAL: Return the number of version difference between the two states of the object.

Specified by:
getVersionDifference in interface org.eclipse.persistence.internal.descriptors.OptimisticLockingPolicy

getWriteLockValue

public java.lang.Object getWriteLockValue(java.lang.Object domainObject,
                                          java.util.Vector primaryKey,
                                          org.eclipse.persistence.internal.sessions.AbstractSession session)
INTERNAL: This method will return the optimistic lock value for the object

Specified by:
getWriteLockValue in interface org.eclipse.persistence.internal.descriptors.OptimisticLockingPolicy

initialize

public void initialize(org.eclipse.persistence.internal.sessions.AbstractSession session)
INTERNAL: It is responsible for initializing the policy;

Specified by:
initialize in interface org.eclipse.persistence.internal.descriptors.OptimisticLockingPolicy

initializeProperties

public void initializeProperties()
INTERNAL: It is responsible for initializing the policy;

Specified by:
initializeProperties in interface org.eclipse.persistence.internal.descriptors.OptimisticLockingPolicy

isStoredInCache

public boolean isStoredInCache()
PUBLIC: Return true if the lock value is stored in the cache.

Specified by:
isStoredInCache in interface org.eclipse.persistence.internal.descriptors.OptimisticLockingPolicy

isCascaded

public boolean isCascaded()
PUBLIC: Return true if the policy uses cascade locking. Currently, not supported on this policy at this time.

Specified by:
isCascaded in interface org.eclipse.persistence.internal.descriptors.OptimisticLockingPolicy

isNewerVersion

public boolean isNewerVersion(java.lang.Object currentValue,
                              java.lang.Object domainObject,
                              java.util.Vector primaryKey,
                              org.eclipse.persistence.internal.sessions.AbstractSession session)
INTERNAL: Compares the value and the value from the object (or cache). Will return true if the object is newer than the row.

Specified by:
isNewerVersion in interface org.eclipse.persistence.internal.descriptors.OptimisticLockingPolicy

isNewerVersion

public boolean isNewerVersion(org.eclipse.persistence.internal.sessions.AbstractRecord Record,
                              java.lang.Object domainObject,
                              java.util.Vector primaryKey,
                              org.eclipse.persistence.internal.sessions.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 org.eclipse.persistence.internal.descriptors.OptimisticLockingPolicy

isPrimaryKey

protected boolean isPrimaryKey(org.eclipse.persistence.internal.helper.DatabaseField dbField)
INTERNAL: Returns whether or not this field is a primary key. This method will also return true for secondary table primarykeys


mergeIntoParentCache

public void mergeIntoParentCache(org.eclipse.persistence.internal.sessions.UnitOfWorkImpl uow,
                                 java.util.Vector primaryKey,
                                 java.lang.Object object)
INTERNAL: Only applicable when the value is stored in the cache.

Specified by:
mergeIntoParentCache in interface org.eclipse.persistence.internal.descriptors.OptimisticLockingPolicy

setAllNonPrimaryKeyFields

protected void setAllNonPrimaryKeyFields(java.util.Vector allNonPrimaryKeyFields)
INTERNAL: Set method for all the primary keys


setDescriptor

public void setDescriptor(ClassDescriptor descriptor)
INTERNAL: Set method for the descriptor

Specified by:
setDescriptor in interface org.eclipse.persistence.internal.descriptors.OptimisticLockingPolicy

setLockOnChangeMode

public void setLockOnChangeMode(org.eclipse.persistence.internal.descriptors.OptimisticLockingPolicy.LockOnChange lockOnChangeMode)
ADVANCED: Sets the LockOnChange mode for this policy. This mode specifies if a Optimistic Write lock should be enforced on this entity when set of mappings are changed. Unfortunately this locking policy can not always force an optimistic lock unless the core fields have changed

Specified by:
setLockOnChangeMode in interface org.eclipse.persistence.internal.descriptors.OptimisticLockingPolicy

setupWriteFieldsForInsert

public void setupWriteFieldsForInsert(ObjectLevelModifyQuery query)
INTERNAL: Put the initial writelock value into the modifyRow. There is nothing to do because all the lock values are in the mappings.

Specified by:
setupWriteFieldsForInsert in interface org.eclipse.persistence.internal.descriptors.OptimisticLockingPolicy

updateRowAndObjectForUpdate

public void updateRowAndObjectForUpdate(ObjectLevelModifyQuery query,
                                        java.lang.Object domainObject)
INTERNAL: Nothing to do because all updates are handled by the application

Specified by:
updateRowAndObjectForUpdate in interface org.eclipse.persistence.internal.descriptors.OptimisticLockingPolicy

shouldUpdateVersionOnOwnedMappingChange

public boolean shouldUpdateVersionOnOwnedMappingChange()
INTERNAL: Returns true if the policy has been set to set an optimistic read lock when a owning mapping changes. Unfortunately this locking policy can not always force an optimistic lock unless the core fields have changed

Specified by:
shouldUpdateVersionOnOwnedMappingChange in interface org.eclipse.persistence.internal.descriptors.OptimisticLockingPolicy

shouldUpdateVersionOnMappingChange

public boolean shouldUpdateVersionOnMappingChange()
INTERNAL: Returns true if the policy has been set to set an optimistic read lock when any mapping changes. Unfortunately this locking policy can not always force an optimistic lock unless the core fields have changed

Specified by:
shouldUpdateVersionOnMappingChange in interface org.eclipse.persistence.internal.descriptors.OptimisticLockingPolicy

validateDelete

public void validateDelete(int rowCount,
                           java.lang.Object object,
                           DeleteObjectQuery query)
INTERNAL: Check the row count for lock failure.

Specified by:
validateDelete in interface org.eclipse.persistence.internal.descriptors.OptimisticLockingPolicy

validateUpdate

public void validateUpdate(int rowCount,
                           java.lang.Object object,
                           WriteObjectQuery query)
INTERNAL: Check the row count for lock failure.

Specified by:
validateUpdate in interface org.eclipse.persistence.internal.descriptors.OptimisticLockingPolicy

verifyUsage

protected void verifyUsage(org.eclipse.persistence.internal.sessions.AbstractSession session)
INTERNAL: throw an exception if not inside a unit of work at this point


EclipseLink 2.0.0, build 'v20091127-r5931' API Reference