HHH-19440 completely deprecate LockOptions

and explain what's going on with it in the javadoc

Author: gavinking

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.

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
  *

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" );
 	}

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);
 
 	/**

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();
 
 	/**

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();
 
 	/**

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

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;

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();
 	}

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;