From d1b2f70fb9d26288e5871655b5af2688371f9492 Mon Sep 17 00:00:00 2001
From: Gavin King <gavin@hibernate.org>
Date: Sun, 12 May 2024 12:11:04 +0200
Subject: [PATCH] reorganize the javadoc for LockModeType

there are no semantic changes here, but this is much more readable, I believe

Signed-off-by: Gavin King <gavin@hibernate.org>
---
 .../jakarta/persistence/LockModeType.java     | 241 +++++++++++-------
 1 file changed, 146 insertions(+), 95 deletions(-)

diff --git a/api/src/main/java/jakarta/persistence/LockModeType.java b/api/src/main/java/jakarta/persistence/LockModeType.java
index bb58b6e8..f262408e 100644
--- a/api/src/main/java/jakarta/persistence/LockModeType.java
+++ b/api/src/main/java/jakarta/persistence/LockModeType.java
@@ -17,10 +17,10 @@
 package jakarta.persistence;
 
 /**
- * Enumerates the kinds of optimistic or pessimistic lock which
- * may be obtained on an entity instance.
+ * Enumerates the kinds of optimistic or pessimistic lock which may
+ * be obtained on an entity instance.
  *
- * <p> A specific lock mode may be requested by passing an explicit
+ * <p>A specific lock mode may be requested by passing an explicit
  * {@code LockModeType} as an argument to:
  * <ul>
  * <li>one of the methods of {@link EntityManager} which obtains
@@ -30,102 +30,55 @@
  * <li>to {@link Query#setLockMode(LockModeType)} or
  *     {@link TypedQuery#setLockMode(LockModeType)}.
  * </ul>
+ * <p>Lock modes other than {@link #NONE} prevent dirty reads and
+ * non-repeatable reads of locked entity data within the current
+ * transaction.
  * 
- * <p> Optimistic locks are specified using
- * {@link LockModeType#OPTIMISTIC LockModeType.OPTIMISTIC} and
- * {@link LockModeType#OPTIMISTIC_FORCE_INCREMENT}. The lock mode
- * types {@link LockModeType#READ} and {@link LockModeType#WRITE} are
- * synonyms for {@code OPTIMISTIC} and {@code OPTIMISTIC_FORCE_INCREMENT}
+ * <p>An optimistic lock is requested by specifying the lock mode
+ * type {@link #OPTIMISTIC} or {@link #OPTIMISTIC_FORCE_INCREMENT}.
+ * The lock mode types {@link #READ} and {@link #WRITE} are synonyms
+ * for {@code OPTIMISTIC} and {@code OPTIMISTIC_FORCE_INCREMENT}
  * respectively. The latter are preferred for new applications.
  *
- * <p> The semantics of requesting locks of type
- * {@code LockModeType.OPTIMISTIC} and
- * {@code LockModeType.OPTIMISTIC_FORCE_INCREMENT} are the
- * following.
+ * <p>The persistence implementation is not required to accept
+ * requests for optimistic locks on non-versioned entities. When
+ * a provider does not support such a lock request, it must throw
+ * {@link PersistenceException}.
  *
- * <p> If transaction T1 calls for a lock of type 
- * {@code LockModeType.OPTIMISTIC} on a versioned object, 
- * the entity manager must ensure that neither of the following 
- * phenomena can occur:
+ * <p>An immediate pessimistic database-level lock is requested by
+ * specifying one of the lock mode types {@link #PESSIMISTIC_READ},
+ * {@link #PESSIMISTIC_WRITE}, or {@link #PESSIMISTIC_FORCE_INCREMENT}.
  * <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>
+ * <li>A lock with type {@code PESSIMISTIC_WRITE} can be obtained on
+ *     an entity instance to force serialization among transactions
+ *     attempting to update the entity data.
+ * <li>A lock with type {@code 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.
+ * <li>A lock with type {@code PESSIMISTIC_WRITE} can be used when
+ *     querying data and there is a high likelihood of deadlock or
+ *     update failure among concurrent updating transactions.
  * </ul>
- *
- * <p> Lock modes must always prevent the phenomena P1 and P2.
- *
- * <p> In addition, obtaining a lock of type
- * {@code LockModeType.OPTIMISTIC_FORCE_INCREMENT} 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 such a lock request, it must throw the {@link
- * PersistenceException}.
- *
- * <p>The lock modes {@link LockModeType#PESSIMISTIC_READ},
- * {@link LockModeType#PESSIMISTIC_WRITE}, and
- * {@link 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 LockModeType.PESSIMISTIC_WRITE}, and
- * {@code LockModeType.PESSIMISTIC_FORCE_INCREMENT} are the
- * following.
- *
- * <p> If transaction T1 calls for a lock of type
- * {@code LockModeType.PESSIMISTIC_READ} or
- * {@code LockModeType.PESSIMISTIC_WRITE} 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} 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} 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} 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 the use of locks
- * of type {@code LockModeType.PESSIMISTIC_READ} and
- * {@code LockModeType.PESSIMISTIC_WRITE} with non-versioned entities
- * as well as with versioned entities.
- *
- * <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} 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).
+ * <p>The persistence implementation must accept requests for locks
+ * of type {@code PESSIMISTIC_READ} and {@code PESSIMISTIC_WRITE} on
+ * both versioned and non-versioned entities.
+ * <ul>
+ * <li>When the lock cannot be obtained, and the database locking
+ *     failure results in transaction-level rollback, the provider
+ *     must throw {@link PessimisticLockException} and ensure that
+ *     the JTA transaction or {@code EntityTransaction} has been
+ *     marked for rollback.
+ * <li>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).</li>
+ * </ul>
+ * <p>The persistence implementation is not required to accept
+ * requests for locks of type {@code PESSIMISTIC_FORCE_INCREMENT} on
+ * non-versioned entities. When a provider does not support such a
+ * lock request, it must throw {@link PersistenceException}.
  *
  * @since 1.0
  *
@@ -149,23 +102,85 @@ public enum LockModeType implements FindOption, RefreshOption {
     WRITE,
 
     /**
-     * Optimistic lock.
+     * An optimistic lock.
+     *
+     * <p>If transaction T1 calls for a lock of type
+     * {@code OPTIMISTIC} on a versioned object, the entity manager
+     * must ensure that neither of the following phenomena can occur:
+     * <ul>
+     * <li>P1 <b>Dirty read</b>: 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 <b>Non-repeatable read</b>: 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>The persistence implementation is not required to accept
+     * requests for {@code OPTIMISTIC} locks on non-versioned entities.
      *
      * @since 2.0
      */
     OPTIMISTIC,
 
     /**
-     * Optimistic lock, with version update.
+     * Optimistic lock, with version update, which prevents the
+     * following phenomena:
+     *
+     * <p>If transaction T1 calls for a lock of type
+     * {@code OPTIMISTIC_FORCE_INCREMENT} on a versioned object,
+     * the entity manager must ensure that neither of the following
+     * phenomena can occur:
+     * <ul>
+     * <li>P1 <b>Dirty read</b>: 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 <b>Non-repeatable read</b>: 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>In addition, obtaining a lock of type
+     * {@code OPTIMISTIC_FORCE_INCREMENT} on a versioned entity will
+     * also force an update (increment) to the {@linkplain Version
+     * version column}.
+     *
+     * <p>The persistence implementation is not required to accept
+     * requests for {@code OPTIMISTIC_FORCE_INCREMENT} locks on
+     * non-versioned entities.
      *
      * @since 2.0
      */
     OPTIMISTIC_FORCE_INCREMENT,
 
     /**
-     *
      * Pessimistic read lock.
      *
+     * <p>If transaction T1 calls for a lock of type
+     * {@code PESSIMISTIC_READ} on an object, the entity manager must
+     * ensure that neither of the following phenomena can occur:
+     * <ul>
+     * <li>P1 <b>Dirty read</b>: 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>
+     * <li>P2 <b>Non-repeatable read</b>: Transaction T1 reads a row.
+     *     Another transaction T2 then modifies or deletes that row,
+     *     before T1 has committed or rolled back.
+     * </ul>
+     *
      * @since 2.0
      */
     PESSIMISTIC_READ,
@@ -173,6 +188,19 @@ public enum LockModeType implements FindOption, RefreshOption {
     /**
      * Pessimistic write lock.
      *
+     * <p>If transaction T1 calls for a lock of type
+     * {@code PESSIMISTIC_WRITE} on an object, the entity manager must
+     * ensure that neither of the following phenomena can occur:
+     * <ul>
+     * <li>P1 <b>Dirty read</b>: 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>
+     * <li>P2 <b>Non-repeatable read</b>: Transaction T1 reads a row.
+     *     Another transaction T2 then modifies or deletes that row,
+     *     before T1 has committed or rolled back.
+     * </ul>
+     *
      * @since 2.0
      */
     PESSIMISTIC_WRITE,
@@ -180,6 +208,29 @@ public enum LockModeType implements FindOption, RefreshOption {
     /**
      * Pessimistic write lock, with version update.
      *
+     * <p>If transaction T1 calls for a lock of type
+     * {@code PESSIMISTIC_FORCE_INCREMENT} on an object, the entity
+     * manager must ensure that neither of the following phenomena
+     * can occur:
+     * <ul>
+     * <li>P1 <b>Dirty read</b>: 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>
+     * <li>P2 <b>Non-repeatable read</b>: Transaction T1 reads a row.
+     *     Another transaction T2 then modifies or deletes that row,
+     *     before T1 has committed or rolled back.
+     * </ul>
+     *
+     * <p>In addition, obtaining a lock of type
+     * {@code PESSIMISTIC_FORCE_INCREMENT} on a versioned entity will
+     * also force an update (increment) to the {@linkplain Version
+     * version column}.
+     *
+     * <p>The persistence implementation is not required to accept
+     * requests for {@code PESSIMISTIC_FORCE_INCREMENT} locks on
+     * non-versioned entities.
+     *
      * @since 2.0
      */
     PESSIMISTIC_FORCE_INCREMENT,