001/*
002 * Copyright (c) 2008, 2009, 2011 Oracle, Inc. All rights reserved.
003 *
004 * This program and the accompanying materials are made available under the
005 * terms of the Eclipse Public License v1.0 and Eclipse Distribution License v. 1.0
006 * which accompanies this distribution.  The Eclipse Public License is available
007 * at http://www.eclipse.org/legal/epl-v10.html and the Eclipse Distribution License
008 * is available at http://www.eclipse.org/org/documents/edl-v10.php.
009 */
010package javax.persistence;
011
012/**
013 * Lock modes can be specified by means of passing a <code>LockModeType</code> argument to one of the
014 * {@link javax.persistence.EntityManager} methods that take locks (<code>lock</code>, <code>find</code>, or
015 * <code>refresh</code>) or to the {@link Query#setLockMode Query.setLockMode()} or
016 * {@link TypedQuery#setLockMode TypedQuery.setLockMode()} method.
017 * <p>
018 * Lock modes can be used to specify either optimistic or pessimistic locks.
019 * <p>
020 * Optimistic locks are specified using {@link LockModeType#OPTIMISTIC LockModeType.OPTIMISTIC} and
021 * {@link LockModeType#OPTIMISTIC_FORCE_INCREMENT LockModeType.OPTIMISTIC_FORCE_INCREMENT}. The lock mode type
022 * values {@link LockModeType#READ LockModeType.READ} and {@link LockModeType#WRITE LockModeType.WRITE} are
023 * synonyms of <code>OPTIMISTIC</code> and <code>OPTIMISTIC_FORCE_INCREMENT</code> respectively. The latter
024 * are to be preferred for new applications.
025 * <p>
026 * The semantics of requesting locks of type <code>LockModeType.OPTIMISTIC</code> and
027 * <code>LockModeType.OPTIMISTIC_FORCE_INCREMENT</code> are the following.
028 * <p>
029 * <p>
030 * If transaction T1 calls for a lock of type <code>LockModeType.OPTIMISTIC</code> on a versioned object, the
031 * entity manager must ensure that neither of the following phenomena can occur:
032 * <ul>
033 * <li>P1 (Dirty read): Transaction T1 modifies a row. Another transaction T2 then reads that row and obtains
034 * the modified value, before T1 has committed or rolled back. Transaction T2 eventually commits successfully;
035 * it does not matter whether T1 commits or rolls back and whether it does so before or after T2 commits.</li>
036 * <li>P2 (Non-repeatable read): Transaction T1 reads a row. Another transaction T2 then modifies or
037 * deletes that row, before T1 has committed. Both transactions eventually commit successfully. </li>
038 * </ul>
039 * <p>
040 * Lock modes must always prevent the phenomena P1 and P2.
041 * <p>
042 * In addition, calling a lock of type <code>LockModeType.OPTIMISTIC_FORCE_INCREMENT</code> on a versioned
043 * object, will also force an update (increment) to the entity's version column.
044 * <p>
045 * The persistence implementation is not required to support the use of optimistic lock modes on non-versioned
046 * objects. When it cannot support a such lock call, it must throw the {@link PersistenceException}.
047 * <p>
048 * The lock modes {@link LockModeType#PESSIMISTIC_READ LockModeType.PESSIMISTIC_READ},
049 * {@link LockModeType#PESSIMISTIC_WRITE LockModeType.PESSIMISTIC_WRITE}, and
050 * {@link LockModeType#PESSIMISTIC_FORCE_INCREMENT LockModeType.PESSIMISTIC_FORCE_INCREMENT} are used to
051 * immediately obtain long-term database locks.
052 * <p>
053 * The semantics of requesting locks of type <code>LockModeType.PESSIMISTIC_READ</code>,
054 * <code>LockModeType.PESSIMISTIC_WRITE</code>, and <code>LockModeType.PESSIMISTIC_FORCE_INCREMENT</code> are
055 * the following.
056 * <p>
057 * If transaction T1 calls for a lock of type <code>LockModeType.PESSIMISTIC_READ</code> or
058 * <code>LockModeType.PESSIMISTIC_WRITE</code> on an object, the entity manager must ensure that neither of
059 * the following phenomena can occur:
060 * <ul>
061 * <li>P1 (Dirty read): Transaction T1 modifies a row. Another transaction T2 then reads that row and obtains
062 * the modified value, before T1 has committed or rolled back.</li>
063 * <li>P2 (Non-repeatable read): Transaction T1 reads a row. Another transaction T2 then modifies or deletes
064 * that row, before T1 has committed or rolled back.</li>
065 * </ul>
066 * <p>
067 * A lock with <code>LockModeType.PESSIMISTIC_WRITE</code> can be obtained on an entity instance to force
068 * serialization among transactions attempting to update the entity data. A lock with
069 * <code>LockModeType.PESSIMISTIC_READ</code> can be used to query data using repeatable-read semantics
070 * without the need to reread the data at the end of the transaction to obtain a lock, and without blocking
071 * other transactions reading the data. A lock with <code>LockModeType.PESSIMISTIC_WRITE</code> can be used
072 * when querying data and there is a high likelihood of deadlock or update failure among concurrent updating
073 * transactions.
074 * <p>
075 * The persistence implementation must support use of locks of type <code>LockModeType.PESSIMISTIC_READ</code>
076 * <code>LockModeType.PESSIMISTIC_WRITE</code> on a non-versioned entity as well as on a versioned entity.
077 * <p>
078 * When the lock cannot be obtained, and the database locking failure results in transaction-level rollback,
079 * the provider must throw the {@link PessimisticLockException} and ensure that the JTA transaction or
080 * <code>EntityTransaction</code> has been marked for rollback.
081 * <p>
082 * When the lock cannot be obtained, and the database locking failure results in only statement-level
083 * rollback, the provider must throw the {@link LockTimeoutException} (and must not mark the transaction for
084 * rollback).
085 *
086 * @since Java Persistence 1.0
087 */
088public enum LockModeType {
089  /**
090   * Synonymous with <code>OPTIMISTIC</code>. <code>OPTIMISTIC</code> is to be preferred for new
091   * applications.
092   */
093  READ,
094
095  /**
096   * Synonymous with <code>OPTIMISTIC_FORCE_INCREMENT</code>. <code>OPTIMISTIC_FORCE_IMCREMENT</code> is to
097   * be preferred for new applications.
098   */
099  WRITE,
100
101  /**
102   * Optimistic lock.
103   *
104   * @since Java Persistence 2.0
105   */
106  OPTIMISTIC,
107
108  /**
109   * Optimistic lock, with version update.
110   *
111   * @since Java Persistence 2.0
112   */
113  OPTIMISTIC_FORCE_INCREMENT,
114
115  /**
116   * Pessimistic read lock.
117   *
118   * @since Java Persistence 2.0
119   */
120  PESSIMISTIC_READ,
121
122  /**
123   * Pessimistic write lock.
124   *
125   * @since Java Persistence 2.0
126   */
127  PESSIMISTIC_WRITE,
128
129  /**
130   * Pessimistic write lock, with version update.
131   *
132   * @since Java Persistence 2.0
133   */
134  PESSIMISTIC_FORCE_INCREMENT,
135
136  /**
137   * No lock.
138   *
139   * @since Java Persistence 2.0
140   */
141  NONE
142}