HHH-15681 use enum instead of boolean of lock scopes

also a bunch of Javadoc improvement for LockOptions and friends

hibernate-core/src/main/java/org/hibernate/LockMode.java

@@ -24,14 +24,15 @@
  */
 public enum LockMode {
 	/**
-	 * No lock required. If an object is requested with this lock
+	 * No lock required. If an object is requested with this
-	 * mode, a {@link #READ} lock will be obtained if it is
+	 * lock mode, a {@link #READ} lock will be obtained if it
-	 * necessary to actually read the state from the database,
+	 * is necessary to actually read the state from the database,
 	 * rather than pull it from a cache.
 	 * <p>
 	 * This is the "default" lock mode.
 	 */
 	NONE( 0, "none" ),
+
 	/**
 	 * A shared lock. Objects in this lock mode were read from
 	 * the database in the current transaction, rather than being
@@ -40,31 +41,34 @@ public enum LockMode {
 	READ( 5, "read" ),
 
 	/**
-	 * Optimistically assume that transaction will not experience contention for
+	 * Optimistically assume that transaction will not experience
-	 * entities.  The entity version will be verified near the transaction end.
+	 * contention for an entity. The version will be verified near
+	 * the transaction end.
 	 */
 	OPTIMISTIC( 6, "optimistic" ),
 
 	/**
-	 * Optimistically assume that transaction will not experience contention for
+	 * Optimistically assume that transaction will not experience
-	 * entities.  The entity version will be verified and incremented near the transaction end.
+	 * contention for an entity. The version will be verified and
+	 * incremented near the transaction end.
 	 */
 	OPTIMISTIC_FORCE_INCREMENT( 7, "optimistic_force_increment" ),
 
 	/**
-	 * A {@code WRITE} lock is obtained when an object is updated or inserted.
+	 * A {@code WRITE} lock is obtained when an object is updated
-	 *
+	 * or inserted.
-	 * This lock mode is for internal use only and is not a valid mode for
+	 * <p>
-	 * {@code load()} or {@code lock()}, both of which throw exceptions if
+	 * This lock mode is for internal use only and is not a valid
-	 * {@code WRITE} is specified.
+	 * argument to {@code load()} or {@code lock()}. These method
+	 * throw an exception if {@code WRITE} given as an argument.
 	 */
 	@Internal
 	WRITE( 10, "write" ),
 
 	/**
 	 * Attempt to obtain an upgrade lock, using an Oracle-style
-	 * {@code select for update nowait}. The semantics of
+	 * {@code select for update nowait}. The semantics of this
-	 * this lock mode, once obtained, are the same as
+	 * lock mode, once obtained, are the same as
 	 * {@link #PESSIMISTIC_WRITE}.
 	 */
 	UPGRADE_NOWAIT( 10, "upgrade-nowait" ),
@@ -78,7 +82,7 @@ public enum LockMode {
 	UPGRADE_SKIPLOCKED( 10, "upgrade-skiplocked" ),
 
 	/**
-	 * Implemented as PESSIMISTIC_WRITE.
+	 * Implemented as {@link #PESSIMISTIC_WRITE}.
 	 */
 	PESSIMISTIC_READ( 12, "pessimistic_read" ),
 

hibernate-core/src/main/java/org/hibernate/LockOptions.java

@@ -12,98 +12,130 @@
 import java.util.Iterator;
 import java.util.LinkedHashMap;
 import java.util.Map;
+import java.util.Objects;
 
+import jakarta.persistence.PessimisticLockScope;
 import org.hibernate.query.Query;
+import org.hibernate.query.spi.QueryOptions;
+
+import static java.util.Collections.emptyList;
 
 /**
- * Contains locking details (LockMode, Timeout and Scope).
+ * Contains a set of options describing how a row of a database table
- * 
+ * mapped by an entity should be locked. For
+ * {@link Session#buildLockRequest(LockOptions)},
+ * {@link Session#get(Class, Object, LockOptions)}, or
+ * {@link Session#refresh(Object, LockOptions)}, the relevant options
+ * are:
+ * <ul>
+ * <li>the {@link #getLockMode() lock mode},
+ * <li>the {@link #getTimeOut() pessimistic lock timeout}, and
+ * <li>the {@link #getLockScope() lock scope}, that is, whether the
+ *     lock extends to rows of owned collections.
+ * </ul>
+ * In HQL and criteria queries, lock modes can be defined in an even
+ * more granular fashion, with the option to specify a lock mode that
+ * {@linkplain #setAliasSpecificLockMode(String, LockMode) applies
+ * only to a certain query alias}.
+ *
  * @author Scott Marlow
  */
 public class LockOptions implements Serializable {
 	/**
-	 * Represents LockMode.NONE (timeout + scope do not apply).
+	 * Represents {@link LockMode#NONE}, where timeout and scope are
+	 * not applicable.
 	 */
 	public static final LockOptions NONE = new LockOptions(LockMode.NONE);
 
 	/**
-	 * Represents LockMode.READ (timeout + scope do not apply).
+	 * Represents {@link LockMode#READ}, where timeout and scope are
+	 * not applicable.
 	 */
 	public static final LockOptions READ = new LockOptions(LockMode.READ);
 
 	/**
-	 * Represents LockMode.UPGRADE (will wait forever for lock and scope of false meaning only entity is locked).
+	 * Represents {@link LockMode#PESSIMISTIC_WRITE} with
+	 * {@linkplain #WAIT_FOREVER no timeout}, and
+	 * {@linkplain PessimisticLockScope#NORMAL no extension of the
+	 * lock to owned collections}.
 	 */
 	public static final LockOptions UPGRADE = new LockOptions(LockMode.PESSIMISTIC_WRITE);
 
 	/**
-	 * Indicates that the database should not wait at all to acquire the pessimistic lock.
+	 * Indicates that the database should not wait at all to acquire
+	 * a pessimistic lock which is not immediately available.
+	 *
 	 * @see #getTimeOut
 	 */
 	public static final int NO_WAIT = 0;
 
 	/**
-	 * Indicates that there is no timeout for the acquisition.
+	 * Indicates that there is no timeout for the lock acquisition.
+	 *
 	 * @see #getTimeOut
 	 */
 	public static final int WAIT_FOREVER = -1;
 
 	/**
-	 * Indicates that rows that are already locked should be skipped.
+	 * Indicates that rows which are already locked should be skipped.
+	 *
 	 * @see #getTimeOut()
 	 */
 	public static final int SKIP_LOCKED = -2;
 
 	private LockMode lockMode = LockMode.NONE;
 	private int timeout = WAIT_FOREVER;
+	private boolean scope;
 
 	private Map<String,LockMode> aliasSpecificLockModes;
 
 	private Boolean followOnLocking;
 
 	/**
-	 * Constructs a LockOptions with all default options.
+	 * Constructs an instance with all default options.
 	 */
 	public LockOptions() {
 	}
 
 	/**
-	 * Constructs a LockOptions with the given lock mode.
+	 * Constructs an instance with the given {@linkplain LockMode
+	 * lock mode}.
 	 *
 	 * @param lockMode The lock mode to use
 	 */
-	public LockOptions( LockMode lockMode) {
+	public LockOptions(LockMode lockMode) {
 		this.lockMode = lockMode;
 	}
 
 	/**
-	 * Returns whether the lock options are empty.
+	 * Determine of the lock options are empty.
 	 *
-	 * @return If the lock options is equivalent to {@link LockOptions#NONE}.
+	 * @return {@code true} if the lock options are equivalent to
+	 *         {@link LockOptions#NONE}.
 	 */
 	public boolean isEmpty() {
-		return lockMode == LockMode.NONE && timeout == WAIT_FOREVER && followOnLocking == null && !scope && !hasAliasSpecificLockModes();
+		return lockMode == LockMode.NONE
+			&& timeout == WAIT_FOREVER
+			&& followOnLocking == null
+			&& !scope
+			&& !hasAliasSpecificLockModes();
 	}
 
 	/**
 	 * Retrieve the overall lock mode in effect for this set of options.
-	 * <p/>
-	 * In certain contexts (hql and criteria), lock-modes can be defined in an
-	 * even more granular {@link #setAliasSpecificLockMode(String, LockMode) per-alias} fashion
 	 *
-	 * @return The overall lock mode.
+	 * @return the overall lock mode
 	 */
 	public LockMode getLockMode() {
 		return lockMode;
 	}
 
 	/**
-	 * Set the overall {@link LockMode} to be used.  The default is
+	 * Set the overall {@linkplain LockMode lock mode}. The default is
-	 * {@link LockMode#NONE}
+	 * {@link LockMode#NONE}, that is, no locking at all.
 	 *
-	 * @param lockMode The new overall lock mode to use.
+	 * @param lockMode the new overall lock mode
-	 *
+	 * @return {@code this} for method chaining
-	 * @return this (for method chaining).
 	 */
 	public LockOptions setLockMode(LockMode lockMode) {
 		this.lockMode = lockMode;
@@ -111,11 +143,11 @@ public LockOptions setLockMode(LockMode lockMode) {
 	}
 
 	/**
-	 * Specify the {@link LockMode} to be used for a specific query alias.
+	 * Specify the {@link LockMode} to be used for the given query alias.
 	 *
-	 * @param alias used to reference the LockMode.
+	 * @param alias the query alias to which the lock mode applies
-	 * @param lockMode The lock mode to apply to the given alias
+	 * @param lockMode the lock mode to apply to the given alias
-	 * @return this LockRequest instance for operation chaining.
+	 * @return {@code this} for method chaining
 	 *
 	 * @see Query#setLockMode(String, LockMode)
 	 */
@@ -133,34 +165,30 @@ public LockOptions setAliasSpecificLockMode(String alias, LockMode lockMode) {
 	}
 
 	/**
-	 * Get the {@link LockMode} explicitly specified for the given alias via
+	 * Get the {@link LockMode} explicitly specified for the given alias
-	 * {@link #setAliasSpecificLockMode}
+	 * via {@link #setAliasSpecificLockMode(String, LockMode)}.
-	 * <p/>
+	 * <p>
-	 * Differs from {@link #getEffectiveLockMode} in that here we only return
+	 * Differs from {@link #getEffectiveLockMode(String)} in that here we
-	 * explicitly specified alias-specific lock modes.
+	 * only return an explicitly specified alias-specific lock mode.
 	 *
 	 * @param alias The alias for which to locate the explicit lock mode.
-	 *
 	 * @return The explicit lock mode for that alias.
 	 */
 	public LockMode getAliasSpecificLockMode(String alias) {
-		if ( aliasSpecificLockModes == null ) {
+		return aliasSpecificLockModes == null ? null : aliasSpecificLockModes.get( alias );
-			return null;
-		}
-		return aliasSpecificLockModes.get( alias );
 	}
 
 	/**
-	 * Determine the {@link LockMode} to apply to the given alias.  If no
+	 * Determine the {@link LockMode} to apply to the given alias. If no
-	 * mode was explicitly {@linkplain #setAliasSpecificLockMode set}, the
+	 * mode was {@linkplain #setAliasSpecificLockMode(String, LockMode)}
-	 * {@linkplain #getLockMode overall mode} is returned.  If the overall
+	 * explicitly set}, the {@linkplain #getLockMode()}  overall mode} is
-	 * lock mode is {@code null} as well, {@link LockMode#NONE} is returned.
+	 * returned. If the overall lock mode is also {@code null},
-	 * <p/>
+	 * {@link LockMode#NONE} is returned.
-	 * Differs from {@link #getAliasSpecificLockMode} in that here we fallback to we only return
+	 * <p>
-	 * the overall lock mode.
+	 * Differs from {@link #getAliasSpecificLockMode(String)} in that here
+	 * we fall back to only returning the overall lock mode.
 	 *
 	 * @param alias The alias for which to locate the effective lock mode.
-	 *
 	 * @return The effective lock mode.
 	 */
 	public LockMode getEffectiveLockMode(String alias) {
@@ -172,31 +200,31 @@ public LockMode getEffectiveLockMode(String alias) {
 	}
 
 	/**
-	 * Does this {@code LockOptions} instance define alias-specific lock modes?
+	 * Does this {@code LockOptions} instance define alias-specific lock
+	 * modes?
 	 *
-	 * @return {@code true} if this object defines alias-specific lock modes; {@code false} otherwise.
+	 * @return {@code true} if this object defines alias-specific lock modes;
+	 *        {@code false} otherwise.
 	 */
 	public boolean hasAliasSpecificLockModes() {
 		return aliasSpecificLockModes != null
-				&& ! aliasSpecificLockModes.isEmpty();
+			&& ! aliasSpecificLockModes.isEmpty();
 	}
 
 	/**
-	 * Get the number of aliases that have specific lock modes defined.
+	 * The number of aliases that have alias-specific lock modes specified.
 	 *
 	 * @return the number of explicitly defined alias lock modes.
 	 */
 	public int getAliasLockCount() {
-		if ( aliasSpecificLockModes == null ) {
+		return aliasSpecificLockModes == null ? 0 : aliasSpecificLockModes.size();
-			return 0;
-		}
-		return aliasSpecificLockModes.size();
 	}
 
 	/**
-	 * Iterator for accessing Alias (key) and LockMode (value) as Map.Entry.
+	 * Iterator over {@link Map.Entry}s, each containing an alias and its
+	 * {@link LockMode}.
 	 *
-	 * @return Iterator for accessing the Map.Entry's
+	 * @return an iterator over the {@link Map.Entry}s
 	 * @deprecated use {@link #getAliasSpecificLocks()}
 	 */
 	@Deprecated
@@ -205,15 +233,13 @@ public Iterator<Map.Entry<String,LockMode>> getAliasLockIterator() {
 	}
 
 	/**
-	 * Iterable access to alias (key) and LockMode (value) as Map.Entry.
+	 * Iterable with {@link Map.Entry}s, each containing an alias and its
+	 * {@link LockMode}.
 	 *
-	 * @return Iterable for accessing the Map.Entry's
+	 * @return an iterable with the {@link Map.Entry}s
 	 */
 	public Iterable<Map.Entry<String,LockMode>> getAliasSpecificLocks() {
-		if ( aliasSpecificLockModes == null ) {
+		return aliasSpecificLockModes == null ? emptyList() : aliasSpecificLockModes.entrySet();
-			return Collections.emptyList();
-		}
-		return aliasSpecificLockModes.entrySet();
 	}
 
 	/**
@@ -241,27 +267,30 @@ public LockMode findGreatestLockMode() {
 	}
 
 	/**
-	 * Retrieve the current timeout setting.
+	 * The current timeout, a maximum amount of time in milliseconds
-	 * <p/>
+	 * that the database should wait to obtain a pessimistic lock before
-	 * The timeout is the amount of time, in milliseconds, we should instruct the database
+	 * returning an error to the client.
-	 * to wait for any requested pessimistic lock acquisition.
+	 * <p>
-	 * <p/>
+	 * {@link #NO_WAIT}, {@link #WAIT_FOREVER}, or {@link #SKIP_LOCKED}
-	 * {@link #NO_WAIT}, {@link #WAIT_FOREVER} or {@link #SKIP_LOCKED} represent 3 "magic" values.
+	 * represent 3 "magic" values.
 	 *
-	 * @return timeout in milliseconds, {@link #NO_WAIT}, {@link #WAIT_FOREVER} or {@link #SKIP_LOCKED}
+	 * @return a timeout in milliseconds, {@link #NO_WAIT},
+	 *         {@link #WAIT_FOREVER}, or {@link #SKIP_LOCKED}
 	 */
 	public int getTimeOut() {
 		return timeout;
 	}
 
 	/**
-	 * Set the timeout setting.
+	 * Set the timeout, that is, the maximum amount of time in milliseconds
-	 * <p/>
+	 * that the database should wait to obtain a pessimistic lock before
-	 * See {@link #getTimeOut} for a discussion of meaning.
+	 * returning an error to the client.
+	 * <p>
+	 * {@link #NO_WAIT}, {@link #WAIT_FOREVER}, or {@link #SKIP_LOCKED}
+	 * represent 3 "magic" values.
 	 *
-	 * @param timeout The new timeout setting, in milliseconds
+	 * @param timeout the new timeout setting, in milliseconds
-	 *
+	 * @return {@code this} for method chaining
-	 * @return this (for method chaining).
 	 *
 	 * @see #getTimeOut
 	 */
@@ -270,44 +299,93 @@ public LockOptions setTimeOut(int timeout) {
 		return this;
 	}
 
-	private boolean scope;
+	/**
+	 * The current lock scope:
+	 * <ul>
+	 * <li>{@link PessimisticLockScope#EXTENDED} means the lock
+	 *     extends to rows of owned collections, but
+	 * <li>{@link PessimisticLockScope#NORMAL} means only the entity
+	 *     table and secondary tables are locked.
+	 * </ul>
+	 *
+	 * @return the current {@link PessimisticLockScope}
+	 */
+	public PessimisticLockScope getLockScope() {
+		return scope ? PessimisticLockScope.EXTENDED : PessimisticLockScope.NORMAL;
+	}
 
 	/**
-	 * Retrieve the current lock scope setting.
+	 * Set the lock scope:
-	 * <p/>
+	 * <ul>
-	 * "scope" is a JPA defined term.  It is basically a cascading of the lock to associations.
+	 * <li>{@link PessimisticLockScope#EXTENDED} means the lock
+	 *     extends to rows of owned collections, but
+	 * <li>{@link PessimisticLockScope#NORMAL} means only the entity
+	 *     table and secondary tables are locked.
+	 * </ul>
 	 *
-	 * @return true if locking will be extended to owned associations
+	 * @param scope the new {@link PessimisticLockScope}
+	 * @return {@code this} for method chaining
 	 */
+	public LockOptions setLockScope(PessimisticLockScope scope) {
+		return setScope(scope==PessimisticLockScope.EXTENDED);
+	}
+
+	/**
+	 * The current lock scope setting:
+	 * <ul>
+	 * <li>{@code true} means the lock extends to rows of owned
+	 *     collections, but
+	 * <li>{@code false} means only the entity table and secondary
+	 *     tables are locked.
+	 * </ul>
+	 *
+	 * @return {@code true} if the lock extends to owned associations
+	 *
+	 * @deprecated use {@link #getLockScope()}
+	 */
+	@Deprecated(since = "6.2")
 	public boolean getScope() {
 		return scope;
 	}
 
 	/**
-	 * Set the scope.
+	 * Set the lock scope setting:
+	 * <ul>
+	 * <li>{@code true} means the lock extends to rows of owned
+	 *     collections, but
+	 * <li>{@code false} means only the entity table and secondary
+	 *     tables are locked.
+	 * </ul>
 	 *
-	 * @param scope The new scope setting
+	 * @param scope the new scope setting
+	 * @return {@code this} for method chaining
 	 *
-	 * @return this (for method chaining).
+	 * @deprecated use {@link #setLockScope(PessimisticLockScope)}
 	 */
+	@Deprecated(since = "6.2")
 	public LockOptions setScope(boolean scope) {
 		this.scope = scope;
 		return this;
 	}
 
 	/**
-	 * Retrieve the current follow-on-locking setting.
+	 * The current follow-on locking setting.
 	 *
-	 * @return true if follow-on-locking is enabled
+	 * @return {@code true} if follow-on locking is enabled
+	 *
+	 * @see org.hibernate.dialect.Dialect#useFollowOnLocking(String, QueryOptions)
 	 */
 	public Boolean getFollowOnLocking() {
 		return followOnLocking;
 	}
 
 	/**
-	 * Set the follow-on-locking setting.
+	 * Set the follow-on locking setting.
-	 * @param followOnLocking The new follow-on-locking setting
+	 *
-	 * @return this (for method chaining).
+	 * @param followOnLocking The new follow-on locking setting
+	 * @return {@code this} for method chaining
+	 *
+	 * @see org.hibernate.dialect.Dialect#useFollowOnLocking(String, QueryOptions)
 	 */
 	public LockOptions setFollowOnLocking(Boolean followOnLocking) {
 		this.followOnLocking = followOnLocking;
@@ -330,7 +408,8 @@ public void overlay(LockOptions lockOptions) {
 	}
 
 	/**
-	 * Perform a shallow copy.
+	 * Copy the options in the first given instance of
+	 * {@code LockOptions} to the second given instance.
 	 *
 	 * @param source Source for the copy (copied from)
 	 * @param destination Destination for the copy (copied to)
@@ -349,40 +428,25 @@ public static LockOptions copy(LockOptions source, LockOptions destination) {
 	}
 
 	@Override
-	public boolean equals(Object o) {
+	public boolean equals(Object object) {
-		if ( this == o ) {
+		if ( this == object ) {
 			return true;
 		}
-		if ( o == null || getClass() != o.getClass() ) {
+		else if ( !(object instanceof LockOptions) ) {
 			return false;
 		}
-
+		else {
-		LockOptions that = (LockOptions) o;
+			final LockOptions that = (LockOptions) object;
-
+			return timeout == that.timeout
-		if ( timeout != that.timeout ) {
+				&& scope == that.scope
-			return false;
+				&& lockMode == that.lockMode
+				&& Objects.equals( aliasSpecificLockModes, that.aliasSpecificLockModes )
+				&& Objects.equals( followOnLocking, that.followOnLocking );
 		}
-		if ( scope != that.scope ) {
-			return false;
-		}
-		if ( lockMode != that.lockMode ) {
-			return false;
-		}
-		if ( aliasSpecificLockModes != null ?
-				!aliasSpecificLockModes.equals( that.aliasSpecificLockModes ) :
-				that.aliasSpecificLockModes != null ) {
-			return false;
-		}
-		return followOnLocking != null ? followOnLocking.equals( that.followOnLocking ) : that.followOnLocking == null;
 	}
 
 	@Override
 	public int hashCode() {
-		int result = lockMode != null ? lockMode.hashCode() : 0;
+		return Objects.hash( lockMode, timeout, aliasSpecificLockModes, followOnLocking, scope );
-		result = 31 * result + timeout;
-		result = 31 * result + ( aliasSpecificLockModes != null ? aliasSpecificLockModes.hashCode() : 0 );
-		result = 31 * result + ( followOnLocking != null ? followOnLocking.hashCode() : 0 );
-		result = 31 * result + ( scope ? 1 : 0 );
-		return result;
 	}
 }

hibernate-core/src/main/java/org/hibernate/Session.java

@@ -8,6 +8,7 @@
 
 import java.util.List;
 
+import jakarta.persistence.PessimisticLockScope;
 import org.hibernate.graph.RootGraph;
 import org.hibernate.query.Query;
 import org.hibernate.stat.SessionStatistics;
@@ -1209,13 +1210,13 @@ public interface Session extends SharedSessionContract, EntityManager {
 	 */
 	interface LockRequest {
 		/**
-		 * Constant usable as a time out value that indicates no wait semantics should
+		 * Constant usable as a timeout value indicating that no wait semantics should
 		 * be used in attempting to acquire locks.
 		 */
 		int PESSIMISTIC_NO_WAIT = 0;
 		/**
-		 * Constant usable as a time out value that indicates that attempting to acquire
+		 * Constant usable as a timeout value indicating that attempting to acquire
-		 * locks should be allowed to wait forever (apply no timeout).
+		 * locks should be allowed to wait forever, that is, that there's no timeout.
 		 */
 		int PESSIMISTIC_WAIT_FOREVER = -1;
 
@@ -1243,9 +1244,10 @@ interface LockRequest {
 		int getTimeOut();
 
 		/**
-		 * Specify the pessimistic lock timeout. The default pessimistic lock behavior
+		 * Specify the pessimistic lock timeout. The default pessimistic lock
-		 * is to wait forever for the lock. Lock timeout support is not available in
+		 * behavior is to wait forever for the lock. Lock timeout support is
-		 * all {@link org.hibernate.dialect.Dialect SQL dialects}.
+		 * not available in every {@link org.hibernate.dialect.Dialect dialect}
+		 * of SQL.
 		 *
 		 * @param timeout is time in milliseconds to wait for lock.
 		 *                -1 means wait forever and 0 means no wait.
@@ -1255,24 +1257,43 @@ interface LockRequest {
 		LockRequest setTimeOut(int timeout);
 
 		/**
-		 * Check if locking is cascaded to owned collections and associated entities.
+		 * Check if locking extends to owned collections and associated entities.
 		 *
 		 * @return true if locking will be extended to owned collections and associated entities
+		 *
+		 * @deprecated use {@link #getLockScope()}
 		 */
+		@Deprecated(since = "6.2")
 		boolean getScope();
 
 		/**
-		 * Specify whether the {@link LockMode} should be cascaded to owned collections
+		 * Check if locking extends to owned collections and associated entities.
+		 *
+		 * @return true if locking will be extended to owned collections and associated entities
+		 */
+		default PessimisticLockScope getLockScope() {
+			return getScope() ? PessimisticLockScope.EXTENDED : PessimisticLockScope.NORMAL;
+		}
+
+		/**
+		 * Specify whether the {@link LockMode} should extend to owned collections
 		 * and associated entities. An association must be mapped with
-		 * {@link org.hibernate.annotations.CascadeType#LOCK} for this setting to have
+		 * {@link org.hibernate.annotations.CascadeType#LOCK} for this setting to
-		 * any effect.
+		 * have any effect.
 		 *
 		 * @param scope {@code true} to cascade locks; {@code false} to not.
 		 *
 		 * @return {@code this}, for method chaining
+		 *
+		 * @deprecated use {@link #setLockScope(PessimisticLockScope)}
 		 */
+		@Deprecated(since = "6.2")
 		LockRequest setScope(boolean scope);
 
+		default LockRequest setLockScope(PessimisticLockScope scope) {
+			return setScope( scope == PessimisticLockScope.EXTENDED );
+		}
+
 		/**
 		 * Perform the requested locking.
 		 *

hibernate-core/src/main/java/org/hibernate/dialect/Dialect.java

@@ -3258,7 +3258,7 @@ public boolean useFollowOnLocking(String sql, QueryOptions queryOptions) {
 	}
 
 	/**
-	 * Get the UniqueDelegate supported by this dialect
+	 * Get the {@link UniqueDelegate} supported by this dialect
 	 *
 	 * @return The UniqueDelegate
 	 */

hibernate-core/src/main/java/org/hibernate/dialect/lock/OptimisticForceIncrementLockingStrategy.java

@@ -15,10 +15,11 @@
 import org.hibernate.persister.entity.Lockable;
 
 /**
- * An optimistic locking strategy that forces an increment of the version (after verifying that version hasn't changed).
+ * An optimistic locking strategy that verifies that the version
- * This takes place just prior to transaction commit.
+ * has not changed and then forces an increment of the version,
- * <p/>
+ * just before committing the transaction.
- * This strategy is valid for LockMode.OPTIMISTIC_FORCE_INCREMENT
+ * <p>
+ * This strategy is valid for {@link LockMode#OPTIMISTIC_FORCE_INCREMENT}.
  *
  * @author Scott Marlow
  * @since 3.5

hibernate-core/src/main/java/org/hibernate/dialect/lock/OptimisticLockingStrategy.java

@@ -14,9 +14,10 @@
 import org.hibernate.persister.entity.Lockable;
 
 /**
- * An optimistic locking strategy that verifies that the version hasn't changed (prior to transaction commit).
+ * An optimistic locking strategy that simply verifies that the
+ * version has not changed, just before committing the transaction.
  * <p/>
- * This strategy is valid for LockMode.OPTIMISTIC
+ * This strategy is valid for {@link LockMode#OPTIMISTIC}.
  *
  * @author Scott Marlow
  * @since 3.5

hibernate-core/src/main/java/org/hibernate/dialect/lock/PessimisticForceIncrementLockingStrategy.java

@@ -14,9 +14,10 @@
 import org.hibernate.persister.entity.Lockable;
 
 /**
- * A pessimistic locking strategy that increments the version immediately (obtaining an exclusive write lock).
+ * A pessimistic locking strategy where a lock is obtained by incrementing
- * <p/>
+ * the version immediately, obtaining an exclusive write lock by side effect.
- * This strategy is valid for LockMode.PESSIMISTIC_FORCE_INCREMENT
+ * <p>
+ * This strategy is valid for {@link LockMode#PESSIMISTIC_FORCE_INCREMENT}.
  *
  * @author Scott Marlow
  * @since 3.5

hibernate-core/src/main/java/org/hibernate/dialect/lock/PessimisticReadSelectLockingStrategy.java

@@ -23,14 +23,15 @@
 import org.hibernate.stat.spi.StatisticsImplementor;
 
 /**
- * A pessimistic locking strategy where the locks are obtained through select statements.
+ * A pessimistic locking strategy where a lock is obtained via a
- * <p/>
+ * select statements.
- * For non-read locks, this is achieved through the Dialect's specific
+ * <p>
- * SELECT ... FOR UPDATE syntax.
+ * For non-read locks, this is achieved through the dialect's native
- *
+ * {@code SELECT ... FOR UPDATE} syntax.
- * This strategy is valid for LockMode.PESSIMISTIC_READ
+ * <p>
- *
+ * This strategy is valid for {@link LockMode#PESSIMISTIC_READ}.
- * This class is a clone of SelectLockingStrategy.
+ * <p>
+ * This class is a clone of {@link SelectLockingStrategy}.
  *
  * @author Steve Ebersole
  * @author Scott Marlow

hibernate-core/src/main/java/org/hibernate/dialect/lock/PessimisticReadUpdateLockingStrategy.java

@@ -25,11 +25,12 @@
 import org.jboss.logging.Logger;
 
 /**
- * A pessimistic locking strategy where the locks are obtained through update statements.
+ * A pessimistic locking strategy where a lock is obtained via
- * <p/>
+ * an update statement.
- * This strategy is valid for LockMode.PESSIMISTIC_READ
+ * <p>
- *
+ * This strategy is valid for {@link LockMode#PESSIMISTIC_READ}.
- * This class is a clone of UpdateLockingStrategy.
+ * <p>
+ * This class is a clone of {@link UpdateLockingStrategy}.
  *
  * @author Steve Ebersole
  * @author Scott Marlow

hibernate-core/src/main/java/org/hibernate/dialect/lock/PessimisticWriteSelectLockingStrategy.java

@@ -23,14 +23,15 @@
 import org.hibernate.stat.spi.StatisticsImplementor;
 
 /**
- * A pessimistic locking strategy where the locks are obtained through select statements.
+ * A pessimistic locking strategy where a lock is obtained via a
- * <p/>
+ * select statement.
- * For non-read locks, this is achieved through the Dialect's specific
+ * <p>
- * SELECT ... FOR UPDATE syntax.
+ * For non-read locks, this is achieved through the dialect's native
- *
+ * {@code SELECT ... FOR UPDATE} syntax.
- * This strategy is valid for LockMode.PESSIMISTIC_WRITE
+ * <p>
- *
+ * This strategy is valid for {@link LockMode#PESSIMISTIC_WRITE}.
- * This class is a clone of SelectLockingStrategy.
+ * <p>
+ * This class is a clone of {@link SelectLockingStrategy}.
  *
  * @see org.hibernate.dialect.Dialect#getForUpdateString(LockMode)
  * @see org.hibernate.dialect.Dialect#appendLockHint(LockOptions, String)

hibernate-core/src/main/java/org/hibernate/dialect/lock/PessimisticWriteUpdateLockingStrategy.java

@@ -25,11 +25,12 @@
 import org.jboss.logging.Logger;
 
 /**
- * A pessimistic locking strategy where the locks are obtained through update statements.
+ * A pessimistic locking strategy where a lock is obtained via
- * <p/>
+ * an update statement.
- * This strategy is valid for LockMode.PESSIMISTIC_WRITE
+ * <p>
- *
+ * This strategy is valid for {@link LockMode#PESSIMISTIC_WRITE}.
- * This class is a clone of UpdateLockingStrategy.
+ * <p>
+ * This class is a clone of {@link UpdateLockingStrategy}.
  *
  * @author Steve Ebersole
  * @author Scott Marlow

hibernate-core/src/main/java/org/hibernate/dialect/lock/SelectLockingStrategy.java

@@ -23,10 +23,10 @@
 import org.hibernate.stat.spi.StatisticsImplementor;
 
 /**
- * A locking strategy where the locks are obtained through select statements.
+ * A locking strategy where a lock is obtained via a select statement.
  * <p/>
- * For non-read locks, this is achieved through the Dialect's specific
+ * For non-read locks, this is achieved through the dialect's native
- * SELECT ... FOR UPDATE syntax.
+ * {@code SELECT ... FOR UPDATE} syntax.
  *
  * @see org.hibernate.dialect.Dialect#getForUpdateString(LockMode)
  * @see org.hibernate.dialect.Dialect#appendLockHint(LockOptions, String)

hibernate-core/src/main/java/org/hibernate/dialect/lock/UpdateLockingStrategy.java

@@ -27,8 +27,8 @@
 import org.jboss.logging.Logger;
 
 /**
- * A locking strategy where the locks are obtained through update statements.
+ * A locking strategy where a lock is obtained via an update statement.
- * <p/>
+ * <p>
  * This strategy is not valid for read style locks.
  *
  * @author Steve Ebersole