HHH-19440 completely deprecate LockOptions

gavinking · gavinking · commit 72fa92b2ecf2 · 2025-05-13T09:18:38.000+02:00
and explain what's going on with it in the javadoc
diff --git a/hibernate-core/src/main/java/org/hibernate/LockOptions.java b/hibernate-core/src/main/java/org/hibernate/LockOptions.java
@@ -6,7 +6,6 @@
 
 import jakarta.persistence.PessimisticLockScope;
 import jakarta.persistence.Timeout;
-import org.hibernate.query.Query;
 
 import java.io.Serializable;
 import java.util.HashMap;
@@ -28,9 +27,9 @@
  * {@link Session#refresh(Object, LockOptions)}, the relevant options
  * are:
  * <ul>
- * <li>the {@linkplain #getLockMode() lock mode},
- * <li>the {@linkplain #getTimeOut() pessimistic lock timeout}, and
- * <li>the {@linkplain #getLockScope() lock scope}, that is, whether
+ * <li>the {@linkplain #getLockMode lock mode},
+ * <li>the {@linkplain #getTimeOut pessimistic lock timeout}, and
+ * <li>the {@linkplain #getLockScope lock scope}, that is, whether
  *     the lock extends to rows of owned collections.
  * </ul>
  * <p>
@@ -48,8 +47,33 @@
  * default behavior of the SQL dialect} by passing a non-null argument
  * to {@link #setFollowOnLocking(Boolean)}.
  *
+ * @deprecated
+ * Since JPA 3.2 and Hibernate 7, a {@link LockMode}, {@link Timeout},
+ * or {@link PessimisticLockScope} may be passed directly as an option
+ * to {@code find()}, {@code refresh()}, or {@code lock()}. Therefore,
+ * this class is obsolete as an API and will be moved to an SPI package.
+ * <p>
+ * For HQL/JPQL queries, locking should be controlled via operations of
+ * the {@link org.hibernate.query.SelectionQuery} interface:
+ * <ul>
+ * <li>A timeout may be set via
+ * {@link org.hibernate.query.CommonQueryContract#setTimeout(Timeout)}
+ * <li>The {@code PessimisticLockScope} may be set using
+ * {@link org.hibernate.query.SelectionQuery#setLockScope(PessimisticLockScope)}
+ * <li>Alias-specific lock modes may be specified using
+ * {@link org.hibernate.query.SelectionQuery#setLockMode(String, LockMode)}
+ * <li>Use of follow-on locking may be enabled via
+ * {@link org.hibernate.query.SelectionQuery#setFollowOnLocking(boolean)}
+ * </ul>
+ * The interface {@link Timeouts} provides several operations to simplify
+ * migration.
+ *
+ * @see LockMode
+ * @see Timeouts
+ *
  * @author Scott Marlow
  */
+@Deprecated(since = "7.0", forRemoval = true) // moving to an SPI package
 public class LockOptions implements Serializable {
 	/**
 	 * Represents {@link LockMode#NONE}, to which timeout and scope are
@@ -191,7 +215,7 @@ public LockOptions(LockMode lockMode, int timeout) {
 
 	/**
 	 * Construct an instance with the given {@linkplain LockMode mode},
-	 * timeout, and {@link PessimisticLockScope scope}.
+	 * timeout, and {@linkplain PessimisticLockScope scope}.
 	 *
 	 * @param lockMode The initial lock mode
 	 * @param timeout The initial timeout
@@ -206,7 +230,7 @@ public LockOptions(LockMode lockMode, Timeout timeout, PessimisticLockScope scop
 
 	/**
 	 * Construct an instance with the given {@linkplain LockMode mode},
-	 * timeout, and {@link PessimisticLockScope scope}.
+	 * timeout, and {@linkplain PessimisticLockScope scope}.
 	 *
 	 * @param lockMode The initial lock mode
 	 * @param timeout The initial timeout, in milliseconds
@@ -228,6 +252,7 @@ private LockOptions(boolean immutable, LockMode lockMode) {
 		timeout = Timeouts.WAIT_FOREVER;
 		pessimisticLockScope = NORMAL;
 	}
+
 	/**
 	 * Determine of the lock options are empty.
 	 *
@@ -273,7 +298,7 @@ public LockOptions setLockMode(LockMode lockMode) {
 	 * @param lockMode the lock mode to apply to the given alias
 	 * @return {@code this} for method chaining
 	 *
-	 * @see Query#setLockMode(String, LockMode)
+	 * @see org.hibernate.query.Query#setLockMode(String, LockMode)
 	 */
 	public LockOptions setAliasSpecificLockMode(String alias, LockMode lockMode) {
 		if ( immutable ) {
@@ -307,8 +332,8 @@ public LockMode getAliasSpecificLockMode(String alias) {
 
 	/**
 	 * Determine the {@link LockMode} to apply to the given alias. If no
-	 * mode was {@linkplain #setAliasSpecificLockMode(String, LockMode)}
-	 * explicitly set}, the {@linkplain #getLockMode()}  overall mode} is
+	 * mode was {@linkplain #setAliasSpecificLockMode(String, LockMode)
+	 * explicitly set}, the {@linkplain #getLockMode() overall mode} is
 	 * returned. If the overall lock mode is also {@code null},
 	 * {@link LockMode#NONE} is returned.
 	 * <p>
@@ -432,7 +457,8 @@ public int getTimeOut() {
 	}
 
 	/**
-	 * Set the {@linkplain #getTimeout() timeout}, in milliseconds, associated with {@code this} options.
+	 * Set the {@linkplain #getTimeout() timeout}, in milliseconds, associated
+	 * with {@code this} options.
 	 * <p/>
 	 * {@link #NO_WAIT}, {@link #WAIT_FOREVER}, or {@link #SKIP_LOCKED}
 	 * represent 3 "magic" values.
diff --git a/hibernate-core/src/main/java/org/hibernate/Timeouts.java b/hibernate-core/src/main/java/org/hibernate/Timeouts.java
@@ -7,12 +7,12 @@
 import jakarta.persistence.Timeout;
 
 /**
- * Helpers for dealing with {@linkplain jakarta.persistence.Timeout time out} values,
- * including some "magic values".
+ * Helpers for dealing with {@linkplain jakarta.persistence.Timeout timeout}
+ * values, including some "magic values".
  *
- * @apiNote The {@linkplain #NO_WAIT} and {@linkplain #SKIP_LOCKED} magic values have
- * special {@linkplain LockMode} values as well ({@linkplain LockMode#UPGRADE_NOWAIT}
- * and {@linkplain LockMode#UPGRADE_SKIPLOCKED}, respectively).
+ * @apiNote The {@link #NO_WAIT} and {@link #SKIP_LOCKED} magic values each
+ * have a corresponding {@link LockMode} ({@link LockMode#UPGRADE_NOWAIT}
+ * and {@link LockMode#UPGRADE_SKIPLOCKED}, respectively).
  *
  * @author Steve Ebersole
  *
diff --git a/hibernate-core/src/main/java/org/hibernate/procedure/internal/ProcedureCallImpl.java b/hibernate-core/src/main/java/org/hibernate/procedure/internal/ProcedureCallImpl.java
@@ -1059,7 +1059,7 @@ public LockModeType getLockMode() {
 		throw new IllegalStateException( "Illegal attempt to get lock mode on a native-query" );
 	}
 
-	@Override
+	@Override @Deprecated
 	public QueryImplementor<R> setLockOptions(LockOptions lockOptions) {
 		throw new UnsupportedOperationException( "setLockOptions does not apply to procedure calls" );
 	}
diff --git a/hibernate-core/src/main/java/org/hibernate/query/NativeQuery.java b/hibernate-core/src/main/java/org/hibernate/query/NativeQuery.java
@@ -626,7 +626,7 @@ interface FetchReturn extends ResultNode {
 	 * result in changes to the native SQL query that is
 	 * actually executed.
 	 */
-	@Override
+	@Override @Deprecated(forRemoval = true)
 	LockOptions getLockOptions();
 
 	/**
@@ -637,7 +637,7 @@ interface FetchReturn extends ResultNode {
 	 * result in changes to the native SQL query that is
 	 * actually executed.
 	 */
-	@Override
+	@Override @Deprecated(forRemoval = true)
 	NativeQuery<T> setLockOptions(LockOptions lockOptions);
 
 	/**
diff --git a/hibernate-core/src/main/java/org/hibernate/query/Query.java b/hibernate-core/src/main/java/org/hibernate/query/Query.java
@@ -361,10 +361,11 @@ default Query<R> applyLoadGraph(@SuppressWarnings("rawtypes") RootGraph graph) {
 	 *
 	 * @see LockOptions
 	 *
-	 * @deprecated To be removed with no replacement - this is an SPI/internal concern.
+	 * @deprecated Since {@link LockOptions} is transitioning to
+	 *             a new role as an SPI.
 	 */
-	@Deprecated(since = "7.0", forRemoval = true)
 	@Override
+	@Deprecated(since = "7.0", forRemoval = true)
 	LockOptions getLockOptions();
 
 	/**
diff --git a/hibernate-core/src/main/java/org/hibernate/query/SelectionQuery.java b/hibernate-core/src/main/java/org/hibernate/query/SelectionQuery.java
@@ -558,7 +558,11 @@ default Stream<R> stream() {
 
 	/**
 	 * The {@link LockOptions} currently in effect for the query
+	 *
+	 * @deprecated Since {@link LockOptions} is transitioning to
+	 *             a new role as an SPI.
 	 */
+	@Deprecated(since = "7.0", forRemoval = true)
 	LockOptions getLockOptions();
 
 	/**
diff --git a/hibernate-core/src/main/java/org/hibernate/query/hql/spi/SqmQueryImplementor.java b/hibernate-core/src/main/java/org/hibernate/query/hql/spi/SqmQueryImplementor.java
@@ -92,7 +92,7 @@ default SqmQueryImplementor<R> applyLoadGraph(@SuppressWarnings("rawtypes") Root
 	@Override
 	SqmQueryImplementor<R> addQueryHint(String hint);
 
-	@Override
+	@Override @Deprecated
 	SqmQueryImplementor<R> setLockOptions(LockOptions lockOptions);
 
 	@Override
diff --git a/hibernate-core/src/main/java/org/hibernate/query/spi/AbstractQuery.java b/hibernate-core/src/main/java/org/hibernate/query/spi/AbstractQuery.java
@@ -258,12 +258,12 @@ public QueryImplementor<R> setReadOnly(boolean readOnly) {
 		return this;
 	}
 
-	@Override
+	@Override @Deprecated
 	public LockOptions getLockOptions() {
 		return getQueryOptions().getLockOptions();
 	}
 
-	@Override
+	@Override @Deprecated
 	public QueryImplementor<R> setLockOptions(LockOptions lockOptions) {
 		getQueryOptions().getLockOptions().overlay( lockOptions );
 		return this;
diff --git a/hibernate-core/src/main/java/org/hibernate/query/spi/AbstractSelectionQuery.java b/hibernate-core/src/main/java/org/hibernate/query/spi/AbstractSelectionQuery.java
@@ -398,7 +398,7 @@ public SelectionQuery<R> disableFetchProfile(String profileName) {
 		return this;
 	}
 
-	@Override
+	@Override @Deprecated
 	public LockOptions getLockOptions() {
 		return getQueryOptions().getLockOptions();
 	}
diff --git a/hibernate-core/src/main/java/org/hibernate/query/sql/internal/NativeQueryImpl.java b/hibernate-core/src/main/java/org/hibernate/query/sql/internal/NativeQueryImpl.java
@@ -572,7 +572,7 @@ public LockModeType getLockMode() {
 		throw new IllegalStateException( "Illegal attempt to get lock mode on a native-query" );
 	}
 
-	@Override
+	@Override @Deprecated
 	public NativeQueryImplementor<R> setLockOptions(LockOptions lockOptions) {
 		super.setLockOptions( lockOptions );
 		return this;
diff --git a/hibernate-core/src/main/java/org/hibernate/query/sql/spi/NativeQueryImplementor.java b/hibernate-core/src/main/java/org/hibernate/query/sql/spi/NativeQueryImplementor.java
@@ -174,7 +174,7 @@ NativeQueryImplementor<R> addJoin(
 	@Override
 	NativeQueryImplementor<R> setReadOnly(boolean readOnly);
 
-	@Override
+	@Override @Deprecated
 	NativeQueryImplementor<R> setLockOptions(LockOptions lockOptions);
 
 	@Override
diff --git a/hibernate-core/src/main/java/org/hibernate/query/sqm/internal/QuerySqmImpl.java b/hibernate-core/src/main/java/org/hibernate/query/sqm/internal/QuerySqmImpl.java
@@ -707,7 +707,7 @@ public SqmQueryImplementor<R> addQueryHint(String hint) {
 		return this;
 	}
 
-	@Override
+	@Override @Deprecated
 	public SqmQueryImplementor<R> setLockOptions(LockOptions lockOptions) {
 		// No verifySelect call, because in Hibernate we support locking in subqueries
 		getQueryOptions().getLockOptions().overlay( lockOptions );
diff --git a/hibernate-core/src/main/java/org/hibernate/query/sqm/spi/DelegatingSqmSelectionQueryImplementor.java b/hibernate-core/src/main/java/org/hibernate/query/sqm/spi/DelegatingSqmSelectionQueryImplementor.java
@@ -263,7 +263,7 @@ public String getCacheRegion() {
 		return getDelegate().getCacheRegion();
 	}
 
-	@Override
+	@Override @Deprecated
 	public LockOptions getLockOptions() {
 		return getDelegate().getLockOptions();
 	}
diff --git a/migration-guide.adoc b/migration-guide.adoc
@@ -736,7 +736,9 @@ Now, `varchar(1)` is used by default.
 [[lock-options]]
 == LockOptions
 
-The exposure of `LockOptions` as an API has been deprecated.  Applications should instead prefer the use of `LockMode` (or `LockModeType`), `Timeout` and `PessimisticLockScope`.
+`LockOptions` has been marked deprecated.
+Since JPA 3.2 and Hibernate 7, a `LockMode` (or `LockModeType`), `Timeout`, or `PessimisticLockScope` may be passed directly as an option to `find()`, `refresh()`, or `lock()`.
+Therefore, this class is obsolete as an API and will be moved to an SPI package.
 
 Use this
 

Original file line number	Diff line number	Diff line change
`@@ -7,12 +7,12 @@`
`7`	`7`	`import jakarta.persistence.Timeout;`
`8`	`8`
`9`	`9`	`/**`
`10`		`- * Helpers for dealing with {@linkplain jakarta.persistence.Timeout time out} values,`
`11`		`- * including some "magic values".`
	`10`	`+ * Helpers for dealing with {@linkplain jakarta.persistence.Timeout timeout}`
	`11`	`+ * values, including some "magic values".`
`12`	`12`	`*`
`13`		`- * @apiNote The {@linkplain #NO_WAIT} and {@linkplain #SKIP_LOCKED} magic values have`
`14`		`- * special {@linkplain LockMode} values as well ({@linkplain LockMode#UPGRADE_NOWAIT}`
`15`		`- * and {@linkplain LockMode#UPGRADE_SKIPLOCKED}, respectively).`
	`13`	`+ * @apiNote The {@link #NO_WAIT} and {@link #SKIP_LOCKED} magic values each`
	`14`	`+ * have a corresponding {@link LockMode} ({@link LockMode#UPGRADE_NOWAIT}`
	`15`	`+ * and {@link LockMode#UPGRADE_SKIPLOCKED}, respectively).`
`16`	`16`	`*`
`17`	`17`	`* @author Steve Ebersole`
`18`	`18`	`*`
Original file line number	Diff line number	Diff line change
`@@ -1059,7 +1059,7 @@ public LockModeType getLockMode() {`
`1059`	`1059`	`throw new IllegalStateException( "Illegal attempt to get lock mode on a native-query" );`
`1060`	`1060`	`}`
`1061`	`1061`
`1062`		`- @Override`
	`1062`	`+ @Override @Deprecated`
`1063`	`1063`	`public QueryImplementor<R> setLockOptions(LockOptions lockOptions) {`
`1064`	`1064`	`throw new UnsupportedOperationException( "setLockOptions does not apply to procedure calls" );`
`1065`	`1065`	`}`
Original file line number	Diff line number	Diff line change
`@@ -361,10 +361,11 @@ default Query<R> applyLoadGraph(@SuppressWarnings("rawtypes") RootGraph graph) {`
`361`	`361`	`*`
`362`	`362`	`* @see LockOptions`
`363`	`363`	`*`
`364`		`- * @deprecated To be removed with no replacement - this is an SPI/internal concern.`
	`364`	`+ * @deprecated Since {@link LockOptions} is transitioning to`
	`365`	`+ * a new role as an SPI.`
`365`	`366`	`*/`
`366`		`- @Deprecated(since = "7.0", forRemoval = true)`
`367`	`367`	`@Override`
	`368`	`+ @Deprecated(since = "7.0", forRemoval = true)`
`368`	`369`	`LockOptions getLockOptions();`
`369`	`370`
`370`	`371`	`/**`
Original file line number	Diff line number	Diff line change
`@@ -258,12 +258,12 @@ public QueryImplementor<R> setReadOnly(boolean readOnly) {`
`258`	`258`	`return this;`
`259`	`259`	`}`
`260`	`260`
`261`		`- @Override`
	`261`	`+ @Override @Deprecated`
`262`	`262`	`public LockOptions getLockOptions() {`
`263`	`263`	`return getQueryOptions().getLockOptions();`
`264`	`264`	`}`
`265`	`265`
`266`		`- @Override`
	`266`	`+ @Override @Deprecated`
`267`	`267`	`public QueryImplementor<R> setLockOptions(LockOptions lockOptions) {`
`268`	`268`	`getQueryOptions().getLockOptions().overlay( lockOptions );`
`269`	`269`	`return this;`
Original file line number	Diff line number	Diff line change
`@@ -398,7 +398,7 @@ public SelectionQuery<R> disableFetchProfile(String profileName) {`
`398`	`398`	`return this;`
`399`	`399`	`}`
`400`	`400`
`401`		`- @Override`
	`401`	`+ @Override @Deprecated`
`402`	`402`	`public LockOptions getLockOptions() {`
`403`	`403`	`return getQueryOptions().getLockOptions();`
`404`	`404`	`}`
Original file line number	Diff line number	Diff line change
`@@ -572,7 +572,7 @@ public LockModeType getLockMode() {`
`572`	`572`	`throw new IllegalStateException( "Illegal attempt to get lock mode on a native-query" );`
`573`	`573`	`}`
`574`	`574`
`575`		`- @Override`
	`575`	`+ @Override @Deprecated`
`576`	`576`	`public NativeQueryImplementor<R> setLockOptions(LockOptions lockOptions) {`
`577`	`577`	`super.setLockOptions( lockOptions );`
`578`	`578`	`return this;`
Original file line number	Diff line number	Diff line change
`@@ -707,7 +707,7 @@ public SqmQueryImplementor<R> addQueryHint(String hint) {`
`707`	`707`	`return this;`
`708`	`708`	`}`
`709`	`709`
`710`		`- @Override`
	`710`	`+ @Override @Deprecated`
`711`	`711`	`public SqmQueryImplementor<R> setLockOptions(LockOptions lockOptions) {`
`712`	`712`	`// No verifySelect call, because in Hibernate we support locking in subqueries`
`713`	`713`	`getQueryOptions().getLockOptions().overlay( lockOptions );`
Original file line number	Diff line number	Diff line change
`@@ -263,7 +263,7 @@ public String getCacheRegion() {`
`263`	`263`	`return getDelegate().getCacheRegion();`
`264`	`264`	`}`
`265`	`265`
`266`		`- @Override`
	`266`	`+ @Override @Deprecated`
`267`	`267`	`public LockOptions getLockOptions() {`
`268`	`268`	`return getDelegate().getLockOptions();`
`269`	`269`	`}`