| /******************************************************************************* |
| * Copyright (c) 2008 - 2014 Oracle Corporation. 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. |
| * |
| * Contributors: |
| * Linda DeMichiel - Java Persistence 2.1 |
| * Linda DeMichiel - Java Persistence 2.0 |
| * |
| ******************************************************************************/ |
| package javax.persistence; |
| |
| /** |
| * Lock modes can be specified by means of passing a <code>LockModeType</code> |
| * argument to one of the {@link javax.persistence.EntityManager} methods that take locks |
| * (<code>lock</code>, <code>find</code>, or <code>refresh</code>) or |
| * to the {@link Query#setLockMode Query.setLockMode()} or |
| * {@link TypedQuery#setLockMode TypedQuery.setLockMode()} method. |
| * |
| * <p> Lock modes can be used to specify either optimistic or pessimistic locks. |
| * |
| * <p> 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 <code>OPTIMISTIC</code> and |
| * <code>OPTIMISTIC_FORCE_INCREMENT</code> respectively. The latter |
| * are to be preferred for new applications. |
| * |
| * <p> The semantics of requesting locks of type |
| * <code>LockModeType.OPTIMISTIC</code> and |
| * <code>LockModeType.OPTIMISTIC_FORCE_INCREMENT</code> are the |
| * following. |
| * |
| * <p> If transaction T1 calls for a lock of type |
| * <code>LockModeType.OPTIMISTIC</code> on a versioned object, |
| * the entity manager must ensure that neither of the following |
| * phenomena can occur: |
| * <ul> |
| * <li> 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. |
| * </li> |
| * <li> 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. |
| * </li> |
| * </ul> |
| * |
| * <p> Lock modes must always prevent the phenomena P1 and P2. |
| * |
| * <p> In addition, calling a lock of type |
| * <code>LockModeType.OPTIMISTIC_FORCE_INCREMENT</code> on a versioned object, |
| * will also force an update (increment) to the entity's version |
| * column. |
| * |
| * <p> 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}. |
| * |
| * <p>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. |
| * |
| * <p> The semantics of requesting locks of type |
| * <code>LockModeType.PESSIMISTIC_READ</code>, <code>LockModeType.PESSIMISTIC_WRITE</code>, and |
| * <code>LockModeType.PESSIMISTIC_FORCE_INCREMENT</code> are the following. |
| * |
| * <p> If transaction T1 calls for a lock of type |
| * <code>LockModeType.PESSIMISTIC_READ</code> or |
| * <code>LockModeType.PESSIMISTIC_WRITE</code> on an object, the entity |
| * manager must ensure that neither of the following phenomena can |
| * occur: |
| * <ul> |
| * <li> 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. |
| * |
| * <li> 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. |
| * </ul> |
| * |
| * <p> A lock with <code>LockModeType.PESSIMISTIC_WRITE</code> can be obtained on |
| * an entity instance to force serialization among transactions |
| * attempting to update the entity data. A lock with |
| * <code>LockModeType.PESSIMISTIC_READ</code> 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 |
| * <code>LockModeType.PESSIMISTIC_WRITE</code> can be used when querying data and |
| * there is a high likelihood of deadlock or update failure among |
| * concurrent updating transactions. |
| * |
| * <p> The persistence implementation must support use of locks of type |
| * <code>LockModeType.PESSIMISTIC_READ</code> |
| * <code>LockModeType.PESSIMISTIC_WRITE</code> on a non-versioned entity as well as |
| * on a versioned entity. |
| * |
| * <p> 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 <code>EntityTransaction</code> has been marked for rollback. |
| * |
| * <p> 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 <code>OPTIMISTIC</code>. |
| * <code>OPTIMISTIC</code> is to be preferred for new |
| * applications. |
| * |
| */ |
| READ, |
| |
| /** |
| * Synonymous with <code>OPTIMISTIC_FORCE_INCREMENT</code>. |
| * <code>OPTIMISTIC_FORCE_IMCREMENT</code> 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 |
| } |