From b0b73db69010aac70a39cfe6514edda1c3513f43 Mon Sep 17 00:00:00 2001
From: Gavin King <gavin@hibernate.org>
Date: Mon, 17 Nov 2025 20:35:49 +0100
Subject: [PATCH 1/2] explain effect of LockModes on lost updates and
 non-repeatable reads

---
 .../src/main/java/org/hibernate/LockMode.java   | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/hibernate-core/src/main/java/org/hibernate/LockMode.java b/hibernate-core/src/main/java/org/hibernate/LockMode.java
index 6225d7e8254d..d7a6b1c81f27 100644
--- a/hibernate-core/src/main/java/org/hibernate/LockMode.java
+++ b/hibernate-core/src/main/java/org/hibernate/LockMode.java
@@ -34,6 +34,23 @@
  * which any pessimistic lock is already held has no effect,
  * and does not force a version increment.
  * <p>
+ * When an entity is read from the database, its lock mode
+ * determines whether lost updates and non-repeatable reads
+ * are possible.
+ * <ul>
+ * <li>{@link #NONE} and {@link #READ} prevent lost updates
+ *     only for versioned entities, but do not prevent
+ *     non-repeatable reads, and do not prevent lost updates
+ *     for entities with no version attribute.
+ * <li>{@link #OPTIMISTIC} and {@link #OPTIMISTIC_FORCE_INCREMENT}
+ *     prevent lost updates and non-repeatable reads only for
+ *     versioned entities.
+ * <li>{@link #PESSIMISTIC_READ}, {@link #PESSIMISTIC_WRITE},
+ *     and {@link #PESSIMISTIC_FORCE_INCREMENT} prevent lost
+ *     updates and non-repeatable reads for all entities,
+ *     including entities with no version attribute.
+ * </ul>
+ * <p>
  * This enumeration of lock modes competes with the JPA-defined
  * {@link LockModeType}, but offers additional options, including
  * {@link #UPGRADE_NOWAIT} and {@link #UPGRADE_SKIPLOCKED}.

From f0b17871b47d37116db3e01596105425d561b6f7 Mon Sep 17 00:00:00 2001
From: Gavin King <gavin@hibernate.org>
Date: Tue, 18 Nov 2025 06:28:54 +0100
Subject: [PATCH 2/2] add clarifications as recommended by @sebersole

---
 .../src/main/java/org/hibernate/LockMode.java | 19 +++++++++++++++----
 1 file changed, 15 insertions(+), 4 deletions(-)

diff --git a/hibernate-core/src/main/java/org/hibernate/LockMode.java b/hibernate-core/src/main/java/org/hibernate/LockMode.java
index d7a6b1c81f27..6461b926bf63 100644
--- a/hibernate-core/src/main/java/org/hibernate/LockMode.java
+++ b/hibernate-core/src/main/java/org/hibernate/LockMode.java
@@ -35,22 +35,33 @@
  * and does not force a version increment.
  * <p>
  * When an entity is read from the database, its lock mode
- * determines whether lost updates and non-repeatable reads
- * are possible.
+ * determines whether lost updates and non-repeatable reads are
+ * possible. Assuming the underlying transaction isolation
+ * {@linkplain java.sql.Connection#getTransactionIsolation level}
+ * of the current JDBC database connection is at least
+ * {@linkplain java.sql.Connection#TRANSACTION_READ_COMMITTED
+ * read committed}, then:
  * <ul>
  * <li>{@link #NONE} and {@link #READ} prevent lost updates
  *     only for versioned entities, but do not prevent
  *     non-repeatable reads, and do not prevent lost updates
- *     for entities with no version attribute.
+ *     for entities with no version attribute;
  * <li>{@link #OPTIMISTIC} and {@link #OPTIMISTIC_FORCE_INCREMENT}
  *     prevent lost updates and non-repeatable reads only for
- *     versioned entities.
+ *     versioned entities;
  * <li>{@link #PESSIMISTIC_READ}, {@link #PESSIMISTIC_WRITE},
  *     and {@link #PESSIMISTIC_FORCE_INCREMENT} prevent lost
  *     updates and non-repeatable reads for all entities,
  *     including entities with no version attribute.
  * </ul>
  * <p>
+ * Regardless of the lock mode of a given entity, a non-repeatable
+ * read is always possible when {@link Session#refresh(Object)}
+ * is called for that entity, except when the underlying transaction
+ * isolation level of the current JDBC database connection is at
+ * least {@linkplain java.sql.Connection#TRANSACTION_REPEATABLE_READ
+ * repeatable read}.
+ * <p>
  * This enumeration of lock modes competes with the JPA-defined
  * {@link LockModeType}, but offers additional options, including
  * {@link #UPGRADE_NOWAIT} and {@link #UPGRADE_SKIPLOCKED}.