jakarta.persistence.LockModeType Maven / Gradle / Ivy
Show all versions of jakarta.persistence-api Show documentation
/*
* Copyright (c) 2008, 2020 Oracle and/or its affiliates. All rights reserved.
*
* This program and the accompanying materials are made available under the
* terms of the Eclipse Public License v. 2.0 which is available at
* http://www.eclipse.org/legal/epl-2.0,
* or the Eclipse Distribution License v. 1.0 which is available at
* http://www.eclipse.org/org/documents/edl-v10.php.
*
* SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
*/
// Contributors:
// Linda DeMichiel - 2.1
// Linda DeMichiel - 2.0
package jakarta.persistence;
/**
* Lock modes can be specified by means of passing a LockModeType
* argument to one of the {@link 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 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 2.0
*/
OPTIMISTIC,
/**
* Optimistic lock, with version update.
*
* @since 2.0
*/
OPTIMISTIC_FORCE_INCREMENT,
/**
*
* Pessimistic read lock.
*
* @since 2.0
*/
PESSIMISTIC_READ,
/**
* Pessimistic write lock.
*
* @since 2.0
*/
PESSIMISTIC_WRITE,
/**
* Pessimistic write lock, with version update.
*
* @since 2.0
*/
PESSIMISTIC_FORCE_INCREMENT,
/**
* No lock.
*
* @since 2.0
*/
NONE
}