Class VersionLockingPolicy

  • All Implemented Interfaces:
    Serializable, Cloneable, org.eclipse.persistence.internal.descriptors.OptimisticLockingPolicy
    Direct Known Subclasses:
    TimestampLockingPolicy

    public class VersionLockingPolicy
    extends Object
    implements org.eclipse.persistence.internal.descriptors.OptimisticLockingPolicy, Serializable

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

    Since:
    TOPLink/Java 2.0
    See Also:
    Serialized Form
    • Nested Class Summary

      • Nested classes/interfaces inherited from interface org.eclipse.persistence.internal.descriptors.OptimisticLockingPolicy

        org.eclipse.persistence.internal.descriptors.OptimisticLockingPolicy.LockOnChange
    • Field Summary

      Fields 
      Modifier and Type Field Description
      static int IN_CACHE  
      static int IN_OBJECT  
    • Constructor Summary

      Constructors 
      Constructor Description
      VersionLockingPolicy()
      PUBLIC: Create a new VersionLockingPolicy.
      VersionLockingPolicy​(String fieldName)
      PUBLIC: Create a new VersionLockingPolicy.
      VersionLockingPolicy​(org.eclipse.persistence.internal.helper.DatabaseField field)
      PUBLIC: Create a new VersionLockingPolicy.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void addLockFieldsToUpdateRow​(org.eclipse.persistence.internal.sessions.AbstractRecord databaseRow, org.eclipse.persistence.internal.sessions.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​(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.
      Expression buildUpdateExpression​(org.eclipse.persistence.internal.helper.DatabaseTable table, Expression mainExpression, org.eclipse.persistence.internal.sessions.AbstractRecord row, org.eclipse.persistence.internal.sessions.AbstractRecord row2)
      INTERNAL: When given an expression, this method will return a new expression with the optimistic locking values included.
      Object clone()
      INTERNAL: Clone the policy
      int compareWriteLockValues​(Object value1, Object value2)
      INTERNAL: This method compares two writeLockValues.
      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.
      org.eclipse.persistence.internal.descriptors.OptimisticLockingPolicy.LockOnChange getLockOnChangeMode()
      ADVANCED: returns the LockOnChange mode for this policy.
      Object getNewLockValue​(ModifyQuery query)
      INTERNAL: This method gets the write lock value from either the cache or the object stored in the query.
      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​(Object currentValue, Object domainObject, Object primaryKeys, org.eclipse.persistence.internal.sessions.AbstractSession session)
      PUBLIC: Return the number of versions different between these objects.
      AbstractDirectMapping getVersionMapping()
      INTERNAL: Returns the mapping that will be used to access the version value from an object.
      org.eclipse.persistence.internal.helper.DatabaseField getWriteLockField()
      INTERNAL: Return the write lock field.
      String getWriteLockFieldName()
      PUBLIC: Return the field name of the field that stores the write lock value.
      Expression getWriteLockUpdateExpression​(ExpressionBuilder builder, org.eclipse.persistence.internal.sessions.AbstractSession session)
      INTERNAL: Retrun an expression that updates the write lock
      Object getWriteLockValue​(Object domainObject, Object 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 properties;
      boolean isCascaded()
      PUBLIC: Return true if the policy uses cascade locking.
      boolean isNewerVersion​(Object firstLockFieldValue, Object secondWriteLockFieldValue)
      INTERNAL: Compares two values.
      boolean isNewerVersion​(Object currentValue, Object domainObject, Object primaryKey, org.eclipse.persistence.internal.sessions.AbstractSession session)
      INTERNAL: Compares the value with the value from the object (or cache).
      boolean isNewerVersion​(org.eclipse.persistence.internal.sessions.AbstractRecord databaseRow, Object domainObject, Object primaryKey, org.eclipse.persistence.internal.sessions.AbstractSession session)
      INTERNAL: Compares the value from the row and 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.
      void mergeIntoParentCache​(org.eclipse.persistence.internal.identitymaps.CacheKey unitOfWorkCacheKey, org.eclipse.persistence.internal.identitymaps.CacheKey parentSessionCacheKey)
      INTERNAL: This method should merge changes from the parent into the child.
      void mergeIntoParentCache​(org.eclipse.persistence.internal.sessions.UnitOfWorkImpl uow, Object primaryKey, Object object)
      INTERNAL: Only applicable when the value is stored in the cache.
      void setDescriptor​(ClassDescriptor descriptor)
      INTERNAL:
      void setIsCascaded​(boolean isCascaded)
      PUBLIC: Set whether to use cascade locking on the policy.
      void setIsStoredInCache​(boolean isStoredInCache)
      PUBLIC: Set whether to store the lock in the cache or in the object.
      void setLockOnChangeMode​(org.eclipse.persistence.internal.descriptors.OptimisticLockingPolicy.LockOnChange lockOnChangeMode)
      ADVANCED: Sets the LockOnChange mode for this policy.
      void setupWriteFieldsForInsert​(ObjectLevelModifyQuery query)
      INTERNAL: This method must be included in any locking policy.
      void setWriteLockField​(org.eclipse.persistence.internal.helper.DatabaseField writeLockField)
      ADVANCED: Set the write lock field.
      void setWriteLockFieldName​(String writeLockFieldName)
      PUBLIC: Set the write lock field name.
      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.
      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.
      boolean supportsWriteLockValuesComparison()
      INTERNAL: Indicates that compareWriteLockValues method is supported by the policy.
      void updateObjectWithWriteValue​(ObjectLevelModifyQuery query, Object lockValue)  
      void updateRowAndObjectForUpdate​(ObjectLevelModifyQuery query, Object domainObject)
      INTERNAL: This method updates the modify row, and the domain object with the new lock value.
      void validateDelete​(int rowCount, Object object, DeleteObjectQuery query)
      INTERNAL: Check the row count for lock failure.
      void validateUpdate​(int rowCount, Object object, WriteObjectQuery query)
      INTERNAL: Check the row count for lock failure.
      void writeLockValueIntoRow​(ObjectLevelModifyQuery query, Object domainObject)
      INTERNAL: This method updates the modify row with the old lock value.
    • Constructor Detail

      • VersionLockingPolicy

        public VersionLockingPolicy()
        PUBLIC: Create a new VersionLockingPolicy. Defaults to storing the lock value in the cache.
      • VersionLockingPolicy

        public VersionLockingPolicy​(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​(org.eclipse.persistence.internal.helper.DatabaseField field)
        PUBLIC: Create a new VersionLockingPolicy. Defaults to storing the lock value in the cache.
        Parameters:
        field - the write lock field.
    • Method Detail

      • addLockFieldsToUpdateRow

        public void addLockFieldsToUpdateRow​(org.eclipse.persistence.internal.sessions.AbstractRecord databaseRow,
                                             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.
        Specified by:
        addLockFieldsToUpdateRow in interface org.eclipse.persistence.internal.descriptors.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 org.eclipse.persistence.internal.descriptors.OptimisticLockingPolicy
      • 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
      • buildUpdateExpression

        public Expression buildUpdateExpression​(org.eclipse.persistence.internal.helper.DatabaseTable table,
                                                Expression mainExpression,
                                                org.eclipse.persistence.internal.sessions.AbstractRecord row,
                                                org.eclipse.persistence.internal.sessions.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 org.eclipse.persistence.internal.descriptors.OptimisticLockingPolicy
      • clone

        public Object clone()
        INTERNAL: Clone the policy
        Specified by:
        clone in interface org.eclipse.persistence.internal.descriptors.OptimisticLockingPolicy
      • supportsWriteLockValuesComparison

        public boolean supportsWriteLockValuesComparison()
        INTERNAL: Indicates that compareWriteLockValues method is supported by the policy.
        Specified by:
        supportsWriteLockValuesComparison in interface org.eclipse.persistence.internal.descriptors.OptimisticLockingPolicy
      • compareWriteLockValues

        public int compareWriteLockValues​(Object value1,
                                          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 org.eclipse.persistence.internal.descriptors.OptimisticLockingPolicy
      • getBaseValue

        public 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
      • 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
      • getNewLockValue

        public 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.
      • getValueToPutInCache

        public 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​(Object currentValue,
                                        Object domainObject,
                                        Object primaryKeys,
                                        org.eclipse.persistence.internal.sessions.AbstractSession session)
        PUBLIC: Return the number of versions different between these objects.
        Specified by:
        getVersionDifference in interface org.eclipse.persistence.internal.descriptors.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 org.eclipse.persistence.internal.helper.DatabaseField getWriteLockField()
        INTERNAL: Return the write lock field.
        Specified by:
        getWriteLockField in interface org.eclipse.persistence.internal.descriptors.OptimisticLockingPolicy
      • getWriteLockFieldName

        public String getWriteLockFieldName()
        PUBLIC: Return the field name of the field that stores the write lock value.
      • getWriteLockUpdateExpression

        public Expression getWriteLockUpdateExpression​(ExpressionBuilder builder,
                                                       org.eclipse.persistence.internal.sessions.AbstractSession session)
        INTERNAL: Retrun an expression that updates the write lock
        Specified by:
        getWriteLockUpdateExpression in interface org.eclipse.persistence.internal.descriptors.OptimisticLockingPolicy
      • getWriteLockValue

        public Object getWriteLockValue​(Object domainObject,
                                        Object 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 properties;
        Specified by:
        initializeProperties in interface org.eclipse.persistence.internal.descriptors.OptimisticLockingPolicy
      • isCascaded

        public boolean isCascaded()
        PUBLIC: Return true if the policy uses cascade locking.
        Specified by:
        isCascaded in interface org.eclipse.persistence.internal.descriptors.OptimisticLockingPolicy
      • isNewerVersion

        public boolean isNewerVersion​(Object currentValue,
                                      Object domainObject,
                                      Object primaryKey,
                                      org.eclipse.persistence.internal.sessions.AbstractSession session)
        INTERNAL: Compares the value with the value from the object (or cache). Will return true if the currentValue is newer than the domainObject.
        Specified by:
        isNewerVersion in interface org.eclipse.persistence.internal.descriptors.OptimisticLockingPolicy
      • isNewerVersion

        public boolean isNewerVersion​(org.eclipse.persistence.internal.sessions.AbstractRecord databaseRow,
                                      Object domainObject,
                                      Object 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 row is newer than the object.
        Specified by:
        isNewerVersion in interface org.eclipse.persistence.internal.descriptors.OptimisticLockingPolicy
      • isNewerVersion

        public boolean isNewerVersion​(Object firstLockFieldValue,
                                      Object secondWriteLockFieldValue)
        INTERNAL: Compares two values. Will return true if the firstLockFieldValue is newer than the secondWriteLockFieldValue.
      • 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
      • isStoredInObject

        public boolean isStoredInObject()
        PUBLIC: Return true if the lock value is stored in the object.
      • getVersionMapping

        public AbstractDirectMapping getVersionMapping()
        INTERNAL: Returns the mapping that will be used to access the version value from an object.
      • mergeIntoParentCache

        public void mergeIntoParentCache​(org.eclipse.persistence.internal.sessions.UnitOfWorkImpl uow,
                                         Object primaryKey,
                                         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 org.eclipse.persistence.internal.descriptors.OptimisticLockingPolicy
      • mergeIntoParentCache

        public void mergeIntoParentCache​(org.eclipse.persistence.internal.identitymaps.CacheKey unitOfWorkCacheKey,
                                         org.eclipse.persistence.internal.identitymaps.CacheKey parentSessionCacheKey)
        INTERNAL: This method should merge changes from the parent into the child. #see this method in VersionLockingPolicy
        Specified by:
        mergeIntoParentCache in interface org.eclipse.persistence.internal.descriptors.OptimisticLockingPolicy
      • setDescriptor

        public void setDescriptor​(ClassDescriptor descriptor)
        INTERNAL:
        Specified by:
        setDescriptor in interface org.eclipse.persistence.internal.descriptors.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.
      • setIsCascaded

        public void setIsCascaded​(boolean isCascaded)
        PUBLIC: Set whether to use cascade locking on the policy.
        Parameters:
        isCascaded - set this to true if you would like cascade the locking and set it to false if you would like no cascade locking.
      • 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 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.
        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.
        Specified by:
        shouldUpdateVersionOnMappingChange 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.
        Specified by:
        setLockOnChangeMode in interface org.eclipse.persistence.internal.descriptors.OptimisticLockingPolicy
      • setWriteLockField

        public void setWriteLockField​(org.eclipse.persistence.internal.helper.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​(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 EclipseLink and should not be updated by the application.
      • updateRowAndObjectForUpdate

        public void updateRowAndObjectForUpdate​(ObjectLevelModifyQuery query,
                                                Object domainObject)
        INTERNAL: This method updates the modify row, and the domain object with the new lock value.
        Specified by:
        updateRowAndObjectForUpdate in interface org.eclipse.persistence.internal.descriptors.OptimisticLockingPolicy
      • writeLockValueIntoRow

        public void writeLockValueIntoRow​(ObjectLevelModifyQuery query,
                                          Object domainObject)
        INTERNAL: This method updates the modify row with the old lock value.
      • validateDelete

        public void validateDelete​(int rowCount,
                                   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,
                                   Object object,
                                   WriteObjectQuery query)
        INTERNAL: Check the row count for lock failure.
        Specified by:
        validateUpdate in interface org.eclipse.persistence.internal.descriptors.OptimisticLockingPolicy