javax.persistence.LockModeType Maven / Gradle / Ivy
/*
* Copyright (c) 2008, 2009, 2011 Oracle, Inc. All rights reserved.
*
* This program and the accompanying materials are made available under the
* terms of the Eclipse Public License v1.0 and Eclipse Distribution License v. 1.0
* which accompanies this distribution. The Eclipse Public License is available
* at http://www.eclipse.org/legal/epl-v10.html and the Eclipse Distribution License
* is available at http://www.eclipse.org/org/documents/edl-v10.php.
*/
package javax.persistence;
/**
* Lock modes can be specified by means of passing a LockModeType argument to one of the
* {@link javax.persistence.EntityManager} methods that take locks (lock, find, or
* refresh) or to the {@link Query#setLockMode Query.setLockMode()} or
* {@link TypedQuery#setLockMode TypedQuery.setLockMode()} method.
*
* Lock modes can be used to specify either optimistic or pessimistic locks.
*
* Optimistic locks are specified using {@link LockModeType#OPTIMISTIC LockModeType.OPTIMISTIC} and
* {@link LockModeType#OPTIMISTIC_FORCE_INCREMENT LockModeType.OPTIMISTIC_FORCE_INCREMENT}. The lock mode type
* values {@link LockModeType#READ LockModeType.READ} and {@link LockModeType#WRITE LockModeType.WRITE} are
* synonyms of OPTIMISTIC and OPTIMISTIC_FORCE_INCREMENT respectively. The latter
* are to be preferred for new applications.
*
* The semantics of requesting locks of type LockModeType.OPTIMISTIC and
* LockModeType.OPTIMISTIC_FORCE_INCREMENT are the following.
*
*
* If transaction T1 calls for a lock of type LockModeType.OPTIMISTIC on a versioned object, the
* entity manager must ensure that neither of the following phenomena can occur:
*
* - P1 (Dirty read): Transaction T1 modifies a row. Another transaction T2 then reads that row and obtains
* the modified value, before T1 has committed or rolled back. Transaction T2 eventually commits successfully;
* it does not matter whether T1 commits or rolls back and whether it does so before or after T2 commits.
* - P2 (Non-repeatable read): Transaction T1 reads a row. Another transaction T2 then modifies or
* deletes that row, before T1 has committed. Both transactions eventually commit successfully.
*
*
* Lock modes must always prevent the phenomena P1 and P2.
*
* In addition, calling a lock of type LockModeType.OPTIMISTIC_FORCE_INCREMENT on a versioned
* object, will also force an update (increment) to the entity's version column.
*
* The persistence implementation is not required to support the use of optimistic lock modes on non-versioned
* objects. When it cannot support a such lock call, it must throw the {@link PersistenceException}.
*
* The lock modes {@link LockModeType#PESSIMISTIC_READ LockModeType.PESSIMISTIC_READ},
* {@link LockModeType#PESSIMISTIC_WRITE LockModeType.PESSIMISTIC_WRITE}, and
* {@link LockModeType#PESSIMISTIC_FORCE_INCREMENT LockModeType.PESSIMISTIC_FORCE_INCREMENT} are used to
* immediately obtain long-term database locks.
*
* The semantics of requesting locks of type LockModeType.PESSIMISTIC_READ,
* LockModeType.PESSIMISTIC_WRITE, and LockModeType.PESSIMISTIC_FORCE_INCREMENT are
* the following.
*
* If transaction T1 calls for a lock of type LockModeType.PESSIMISTIC_READ or
* LockModeType.PESSIMISTIC_WRITE on an object, the entity manager must ensure that neither of
* the following phenomena can occur:
*
* - P1 (Dirty read): Transaction T1 modifies a row. Another transaction T2 then reads that row and obtains
* the modified value, before T1 has committed or rolled back.
* - P2 (Non-repeatable read): Transaction T1 reads a row. Another transaction T2 then modifies or deletes
* that row, before T1 has committed or rolled back.
*
*
* A lock with LockModeType.PESSIMISTIC_WRITE can be obtained on an entity instance to force
* serialization among transactions attempting to update the entity data. A lock with
* LockModeType.PESSIMISTIC_READ can be used to query data using repeatable-read semantics
* without the need to reread the data at the end of the transaction to obtain a lock, and without blocking
* other transactions reading the data. A lock with LockModeType.PESSIMISTIC_WRITE can be used
* when querying data and there is a high likelihood of deadlock or update failure among concurrent updating
* transactions.
*
* The persistence implementation must support use of locks of type LockModeType.PESSIMISTIC_READ
* LockModeType.PESSIMISTIC_WRITE on a non-versioned entity as well as on a versioned entity.
*
* When the lock cannot be obtained, and the database locking failure results in transaction-level rollback,
* the provider must throw the {@link PessimisticLockException} and ensure that the JTA transaction or
* EntityTransaction has been marked for rollback.
*
* When the lock cannot be obtained, and the database locking failure results in only statement-level
* rollback, the provider must throw the {@link LockTimeoutException} (and must not mark the transaction for
* rollback).
*
* @since Java Persistence 1.0
*/
public enum LockModeType {
/**
* Synonymous with OPTIMISTIC. OPTIMISTIC is to be preferred for new
* applications.
*/
READ,
/**
* Synonymous with OPTIMISTIC_FORCE_INCREMENT. OPTIMISTIC_FORCE_IMCREMENT is to
* be preferred for new applications.
*/
WRITE,
/**
* Optimistic lock.
*
* @since Java Persistence 2.0
*/
OPTIMISTIC,
/**
* Optimistic lock, with version update.
*
* @since Java Persistence 2.0
*/
OPTIMISTIC_FORCE_INCREMENT,
/**
* Pessimistic read lock.
*
* @since Java Persistence 2.0
*/
PESSIMISTIC_READ,
/**
* Pessimistic write lock.
*
* @since Java Persistence 2.0
*/
PESSIMISTIC_WRITE,
/**
* Pessimistic write lock, with version update.
*
* @since Java Persistence 2.0
*/
PESSIMISTIC_FORCE_INCREMENT,
/**
* No lock.
*
* @since Java Persistence 2.0
*/
NONE
}