1 /*
2 * Copyright (c) 2008, 2019 Oracle and/or its affiliates. All rights reserved.
3 *
4 * This program and the accompanying materials are made available under the
5 * terms of the Eclipse Public License v. 2.0 which is available at
6 * http://www.eclipse.org/legal/epl-2.0,
7 * or the Eclipse Distribution License v. 1.0 which is available at
8 * http://www.eclipse.org/org/documents/edl-v10.php.
9 *
10 * SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
11 */
12
13 // Contributors:
14 // Linda DeMichiel - 2.1
15 // Linda DeMichiel - 2.0
16
17 package javax.persistence;
18
19 /**
20 * Lock modes can be specified by means of passing a <code>LockModeType</code>
21 * argument to one of the {@link javax.persistence.EntityManager} methods that take locks
22 * (<code>lock</code>, <code>find</code>, or <code>refresh</code>) or
23 * to the {@link Query#setLockMode Query.setLockMode()} or
24 * {@link TypedQuery#setLockMode TypedQuery.setLockMode()} method.
25 *
26 * <p> Lock modes can be used to specify either optimistic or pessimistic locks.
27 *
28 * <p> Optimistic locks are specified using {@link
29 * LockModeType#OPTIMISTIC LockModeType.OPTIMISTIC} and {@link
30 * LockModeType#OPTIMISTIC_FORCE_INCREMENT
31 * LockModeType.OPTIMISTIC_FORCE_INCREMENT}. The lock mode type
32 * values {@link LockModeType#READ LockModeType.READ} and
33 * {@link LockModeType#WRITE LockModeType.WRITE} are
34 * synonyms of <code>OPTIMISTIC</code> and
35 * <code>OPTIMISTIC_FORCE_INCREMENT</code> respectively. The latter
36 * are to be preferred for new applications.
37 *
38 * <p> The semantics of requesting locks of type
39 * <code>LockModeType.OPTIMISTIC</code> and
40 * <code>LockModeType.OPTIMISTIC_FORCE_INCREMENT</code> are the
41 * following.
42 *
43 * <p> If transaction T1 calls for a lock of type
44 * <code>LockModeType.OPTIMISTIC</code> on a versioned object,
45 * the entity manager must ensure that neither of the following
46 * phenomena can occur:
47 * <ul>
48 * <li> P1 (Dirty read): Transaction T1 modifies a row.
49 * Another transaction T2 then reads that row and obtains
50 * the modified value, before T1 has committed or rolled back.
51 * Transaction T2 eventually commits successfully; it does not
52 * matter whether T1 commits or rolls back and whether it does
53 * so before or after T2 commits.
54 * </li>
55 * <li> P2 (Non-repeatable read): Transaction T1 reads a row.
56 * Another transaction T2 then modifies or deletes that row,
57 * before T1 has committed. Both transactions eventually commit
58 * successfully.
59 * </li>
60 * </ul>
61 *
62 * <p> Lock modes must always prevent the phenomena P1 and P2.
63 *
64 * <p> In addition, calling a lock of type
65 * <code>LockModeType.OPTIMISTIC_FORCE_INCREMENT</code> on a versioned object,
66 * will also force an update (increment) to the entity's version
67 * column.
68 *
69 * <p> The persistence implementation is not required to support
70 * the use of optimistic lock modes on non-versioned objects. When it
71 * cannot support a such lock call, it must throw the {@link
72 * PersistenceException}.
73 *
74 * <p>The lock modes {@link LockModeType#PESSIMISTIC_READ
75 * LockModeType.PESSIMISTIC_READ}, {@link
76 * LockModeType#PESSIMISTIC_WRITE LockModeType.PESSIMISTIC_WRITE}, and
77 * {@link LockModeType#PESSIMISTIC_FORCE_INCREMENT
78 * LockModeType.PESSIMISTIC_FORCE_INCREMENT} are used to immediately
79 * obtain long-term database locks.
80 *
81 * <p> The semantics of requesting locks of type
82 * <code>LockModeType.PESSIMISTIC_READ</code>, <code>LockModeType.PESSIMISTIC_WRITE</code>, and
83 * <code>LockModeType.PESSIMISTIC_FORCE_INCREMENT</code> are the following.
84 *
85 * <p> If transaction T1 calls for a lock of type
86 * <code>LockModeType.PESSIMISTIC_READ</code> or
87 * <code>LockModeType.PESSIMISTIC_WRITE</code> on an object, the entity
88 * manager must ensure that neither of the following phenomena can
89 * occur:
90 * <ul>
91 * <li> P1 (Dirty read): Transaction T1 modifies a
92 * row. Another transaction T2 then reads that row and obtains the
93 * modified value, before T1 has committed or rolled back.
94 *
95 * <li> P2 (Non-repeatable read): Transaction T1 reads a row. Another
96 * transaction T2 then modifies or deletes that row, before T1 has
97 * committed or rolled back.
98 * </ul>
99 *
100 * <p> A lock with <code>LockModeType.PESSIMISTIC_WRITE</code> can be obtained on
101 * an entity instance to force serialization among transactions
102 * attempting to update the entity data. A lock with
103 * <code>LockModeType.PESSIMISTIC_READ</code> can be used to query data using
104 * repeatable-read semantics without the need to reread the data at
105 * the end of the transaction to obtain a lock, and without blocking
106 * other transactions reading the data. A lock with
107 * <code>LockModeType.PESSIMISTIC_WRITE</code> can be used when querying data and
108 * there is a high likelihood of deadlock or update failure among
109 * concurrent updating transactions.
110 *
111 * <p> The persistence implementation must support use of locks of type
112 * <code>LockModeType.PESSIMISTIC_READ</code>
113 * <code>LockModeType.PESSIMISTIC_WRITE</code> on a non-versioned entity as well as
114 * on a versioned entity.
115 *
116 * <p> When the lock cannot be obtained, and the database locking
117 * failure results in transaction-level rollback, the provider must
118 * throw the {@link PessimisticLockException} and ensure that the JTA
119 * transaction or <code>EntityTransaction</code> has been marked for rollback.
120 *
121 * <p> When the lock cannot be obtained, and the database locking
122 * failure results in only statement-level rollback, the provider must
123 * throw the {@link LockTimeoutException} (and must not mark the transaction
124 * for rollback).
125 *
126 * @since 1.0
127 *
128 */
129 public enum LockModeType
130 {
131 /**
132 * Synonymous with <code>OPTIMISTIC</code>.
133 * <code>OPTIMISTIC</code> is to be preferred for new
134 * applications.
135 *
136 */
137 READ,
138
139 /**
140 * Synonymous with <code>OPTIMISTIC_FORCE_INCREMENT</code>.
141 * <code>OPTIMISTIC_FORCE_IMCREMENT</code> is to be preferred for new
142 * applications.
143 *
144 */
145 WRITE,
146
147 /**
148 * Optimistic lock.
149 *
150 * @since 2.0
151 */
152 OPTIMISTIC,
153
154 /**
155 * Optimistic lock, with version update.
156 *
157 * @since 2.0
158 */
159 OPTIMISTIC_FORCE_INCREMENT,
160
161 /**
162 *
163 * Pessimistic read lock.
164 *
165 * @since 2.0
166 */
167 PESSIMISTIC_READ,
168
169 /**
170 * Pessimistic write lock.
171 *
172 * @since 2.0
173 */
174 PESSIMISTIC_WRITE,
175
176 /**
177 * Pessimistic write lock, with version update.
178 *
179 * @since 2.0
180 */
181 PESSIMISTIC_FORCE_INCREMENT,
182
183 /**
184 * No lock.
185 *
186 * @since 2.0
187 */
188 NONE
189 }
190