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>

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,37 +102,135 @@ 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,
 
  /**
  * 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,
 
  /**
  * 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,