Revision as of 10:14, 16 October 2008

Lock Modes / Pessimistic Locking

JPA 2.0 Root | Enhancement Request

Issue Summary

In JPA 2.0 the specification extends Entity Manager lock mechanism to include explicit support for pessimistic locking. EntityManager and Query APIs have been updated with an additional query hint/persistence unit property. The specification has extensive detail on expected behaviour that must be implemented.

See JPA 2.0 ED section 3.4.3, 3.4.4, 3.6.3 and 3.6.4 for details.

General Solution

As EclipseLink includes Pessimistic Locking functionality this feature should be limited to comprehensive implementation of the JPA functionality and behaviour without many core changes. Pessimistic Locking and Optimistic Locking LockModesTypes must be covered, new query hint/persistence unit timeout properties and new Exceptions must be supported. As well, current query and Entity operations support must be updated to comply with new Pessimistic locking constraints.

Open Issues

Will Target table mappings (uni-directional OneToMany, ElementCollections) require that target rows also be locked?

Usage matrix

EntityManager

find(Class<T>, Object)

1. Uses no locking
2. Will use a javax.persistence.lock.timeout setting from the EntityManager settings to be the find query timeout value. This property at this point will not tie into a pessimistic exception if an error occurs.

find(Class<T>, Object, LockModeType)

1. Uses the lock mode specified
2. If the PESSIMISTIC or PESSIMISTIC_FORCE_INCREMENT lock mode type is specified as and the javax.persistence.lock.timeout or eclipselink.jdbc.timeout hint is also specified, a javax.persistence.LockTimeoutException will be thrown if an exception is raised when issuing the locking query. If no timeout hint is specified a javax,persistence.PessimisticLockException will be thrown.
3. A javax.persistence.lock.timeout setting from the EntityManager settings will be used if available on the find query.
4. Whenever a pessimistic lock is used on an entity that contains a version attribute, that attribute will be updated (incremented)

find(Class<T>, Object, LockModeType, Map)

1. Uses the lock mode specified
2. If the PESSIMISTIC or PESSIMISTIC_FORCE_INCREMENT lock mode type is specified as and the javax.persistence.lock.timeout or eclipselink.jdbc.timeout hint is also specified, a javax.persistence.LockTimeoutException will be thrown if an exception is raised when issuing the #locking query. If no timeout hint is specified a javax,persistence.PessimisticLockException will be thrown.
3. A javax.persistence.lock.timeout setting from the EntityManager settings will be not be used as it is assumed that the properties that are passed in are the strict set to be used with the find query.
4. Whenever a pessimistic lock is used on an entity that contains a version attribute, that attribute will be updated (incremented)

lock(Object, LockModeType)

1. Uses the lock mode specified
2. If the PESSIMISTIC or PESSIMISTIC_FORCE_INCREMENT lock mode type is specified as and the javax.persistence.lock.timeout or eclipselink.jdbc.timeout hint is also specified, a javax.persistence.LockTimeoutException will be thrown if an exception is raised when issuing the locking query. If no timeout hint is specified a javax,persistence.PessimisticLockException will be thrown.
3. A javax.persistence.lock.timeout setting from the EntityManager settings will be used if available on the lock query.
4. Whenever a pessimistic lock is used on an entity that contains a version attribute, that attribute will be updated (incremented)

lock(Object, LockModeType, Map)

1. Uses the lock mode specified
2. If the PESSIMISTIC or PESSIMISTIC_FORCE_INCREMENT lock mode type is specified as and the javax.persistence.lock.timeout or eclipselink.jdbc.timeout hint is also specified, a javax.persistence.LockTimeoutException will be thrown if an exception is raised when issuing the locking query. If no timeout hint is specified a javax,persistence.PessimisticLockException will be thrown.
3. A javax.persistence.lock.timeout setting from the EntityManager settings will be not be used as it is assumed that the properties that are passed in are the strict set to be used with the find query.
4. Whenever a pessimistic lock is used on an entity that contains a version attribute, that attribute will be updated (incremented)

Important Notes

1. Pessimistically locked object with version must still have version updated when entity is updated.
2. A considerable amount of behaviour definition will be found in the java docs of the EntityManger and Query APIs
   1. for instance upon issuing a pessimistic lock call on find if the version from the database does not match that of the persistence context then an exception must be raised

Work Required

1. Develop tests for testing access type settings

   approx 3 days

2. Update Processing to process entire table

   approx 2 days - optimistic modes

   approx 4 days - pessimistic modes