HHH-19440 - Deprecate exposing of LockOptions

# Conflicts:
#	hibernate-core/src/main/java/org/hibernate/LockOptions.java

Author: sebersole

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

@@ -4,15 +4,17 @@
  */
 package org.hibernate;
 
+import jakarta.persistence.FindOption;
+import jakarta.persistence.LockOption;
 import jakarta.persistence.PessimisticLockScope;
+import jakarta.persistence.RefreshOption;
 import jakarta.persistence.Timeout;
 
 import java.io.Serializable;
 import java.util.HashMap;
 import java.util.Iterator;
 import java.util.LinkedHashMap;
 import java.util.Map;
-import java.util.Objects;
 import java.util.Set;
 
 import static jakarta.persistence.PessimisticLockScope.NORMAL;
@@ -72,6 +74,15 @@
  * @see Timeouts
  *
  * @author Scott Marlow
+ *
+ * @deprecated Use methods accepting {@linkplain FindOption}, {@linkplain LockOption} or {@linkplain RefreshOption}
+ * instead.
+ *
+ * @see Timeout
+ * @see Timeouts
+ * @see LockMode
+ * @see jakarta.persistence.LockModeType
+ * @see PessimisticLockScope
  */
 @Deprecated(since = "7.0", forRemoval = true) // moving to an SPI package
 public class LockOptions implements Serializable {
@@ -163,7 +174,10 @@ public class LockOptions implements Serializable {
 
 	/**
 	 * Construct an instance with mode {@link LockMode#NONE} and
-	 * timeout {@link #WAIT_FOREVER}.
+	 * no timeout.
+	 *
+	 * @see LockMode#NONE
+	 * @see Timeouts#WAIT_FOREVER
 	 */
 	public LockOptions() {
 		immutable = false;
@@ -174,9 +188,11 @@ public LockOptions() {
 
 	/**
 	 * Construct an instance with the given {@linkplain LockMode mode}
-	 * and {@link #WAIT_FOREVER}.
+	 * and no timeout.
 	 *
 	 * @param lockMode The initial lock mode
+	 *
+	 * @see Timeouts#WAIT_FOREVER
 	 */
 	public LockOptions(LockMode lockMode) {
 		immutable = false;
@@ -199,20 +215,6 @@ public LockOptions(LockMode lockMode, Timeout timeout) {
 		pessimisticLockScope = NORMAL;
 	}
 
-	/**
-	 * Construct an instance with the given {@linkplain LockMode mode}
-	 * and timeout.
-	 *
-	 * @param lockMode The initial lock mode
-	 * @param timeout  The initial timeout, in milliseconds
-	 *
-	 * @deprecated Use {@linkplain #LockOptions(LockMode, Timeout)} instead
-	 */
-	@Deprecated(since = "7.0")
-	public LockOptions(LockMode lockMode, int timeout) {
-		this( lockMode, Timeouts.interpretMilliSeconds( timeout ) );
-	}
-
 	/**
 	 * Construct an instance with the given {@linkplain LockMode mode},
 	 * timeout, and {@linkplain PessimisticLockScope scope}.
@@ -228,6 +230,32 @@ public LockOptions(LockMode lockMode, Timeout timeout, PessimisticLockScope scop
 		this.pessimisticLockScope = scope;
 	}
 
+	/**
+	 * Internal operation used to create immutable global instances.
+	 */
+	protected LockOptions(boolean immutable, LockMode lockMode) {
+		this.immutable = immutable;
+		this.lockMode = lockMode;
+		timeout = Timeouts.WAIT_FOREVER;
+		pessimisticLockScope = NORMAL;
+	}
+
+
+	/**
+	 * Construct an instance with the given {@linkplain LockMode mode}
+	 * and timeout.
+	 *
+	 * @param lockMode The initial lock mode
+	 * @param timeout  The initial timeout, in milliseconds
+	 *
+	 * @deprecated Use {@linkplain #LockOptions(LockMode, Timeout)} instead
+	 */
+	@Deprecated(since = "7.0")
+	public LockOptions(LockMode lockMode, int timeout) {
+		this( lockMode, Timeouts.interpretMilliSeconds( timeout ) );
+	}
+
+
 	/**
 	 * Construct an instance with the given {@linkplain LockMode mode},
 	 * timeout, and {@linkplain PessimisticLockScope scope}.
@@ -244,27 +272,18 @@ public LockOptions(LockMode lockMode, int timeout, PessimisticLockScope scope) {
 	}
 
 	/**
-	 * Internal operation used to create immutable global instances.
-	 */
-	private LockOptions(boolean immutable, LockMode lockMode) {
-		this.immutable = immutable;
-		this.lockMode = lockMode;
-		timeout = Timeouts.WAIT_FOREVER;
-		pessimisticLockScope = NORMAL;
-	}
-
-	/**
-	 * Determine of the lock options are empty.
+	 * Whether this {@code LockOptions} instance is "empty", meaning
+	 * it has any non-default values set (which is the same as
 	 *
 	 * @return {@code true} if the lock options are equivalent to
-	 *         {@link LockOptions#NONE}.
+	 *         {@link org.hibernate.LockOptions#NONE}.
 	 */
 	public boolean isEmpty() {
 		return lockMode == LockMode.NONE
-			&& timeout == Timeouts.WAIT_FOREVER
-			&& followOnLocking == null
-			&& pessimisticLockScope == NORMAL
-			&& !hasAliasSpecificLockModes();
+			   && timeout == Timeouts.WAIT_FOREVER
+			   && followOnLocking == null
+			   && pessimisticLockScope == NORMAL
+			   && !hasAliasSpecificLockModes();
 	}
 
 	/**
@@ -291,6 +310,17 @@ public LockOptions setLockMode(LockMode lockMode) {
 		return this;
 	}
 
+	/**
+	 * Set of {@link Map.Entry}s, each associating an alias with its
+	 * specified {@linkplain #setAliasSpecificLockMode alias-specific}
+	 * {@link LockMode}.
+	 *
+	 * @return an iterable with the {@link Map.Entry}s
+	 */
+	public Set<Map.Entry<String,LockMode>> getAliasSpecificLocks() {
+		return aliasSpecificLockModes == null ? emptySet() : unmodifiableSet( aliasSpecificLockModes.entrySet() );
+	}
+
 	/**
 	 * Specify the {@link LockMode} to be used for the given query alias.
 	 *
@@ -317,43 +347,16 @@ public LockOptions setAliasSpecificLockMode(String alias, LockMode lockMode) {
 	}
 
 	/**
-	 * Get the {@link LockMode} explicitly specified for the given alias
-	 * via {@link #setAliasSpecificLockMode(String, LockMode)}.
-	 * <p>
-	 * Differs from {@link #getEffectiveLockMode(String)} in that here we
-	 * 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) {
-		return aliasSpecificLockModes == null ? null : aliasSpecificLockModes.get( 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
-	 * returned. If the overall lock mode is also {@code null},
-	 * {@link LockMode#NONE} is returned.
-	 * <p>
-	 * Differs from {@link #getAliasSpecificLockMode(String)} in that here
-	 * we fall back to only returning the overall lock mode.
+	 * The number of aliases that have alias-specific lock modes specified.
 	 *
-	 * @param alias The alias for which to locate the effective lock mode.
-	 * @return The effective lock mode.
+	 * @return the number of explicitly defined alias lock modes.
 	 */
-	public LockMode getEffectiveLockMode(String alias) {
-		LockMode lockMode = getAliasSpecificLockMode( alias );
-		if ( lockMode == null ) {
-			lockMode = this.lockMode;
-		}
-		return lockMode == null ? LockMode.NONE : lockMode;
+	public int getAliasLockCount() {
+		return aliasSpecificLockModes == null ? 0 : aliasSpecificLockModes.size();
 	}
 
 	/**
-	 * Does this {@code LockOptions} instance define alias-specific lock
-	 * modes?
+	 * Whether this {@code LockOptions} instance defines alias-specific lock-modes
 	 *
 	 * @return {@code true} if this object defines alias-specific lock modes;
 	 *        {@code false} otherwise.
@@ -363,12 +366,17 @@ public boolean hasAliasSpecificLockModes() {
 	}
 
 	/**
-	 * The number of aliases that have alias-specific lock modes specified.
+	 * Get the {@link LockMode} explicitly specified for the given alias
+	 * via {@link #setAliasSpecificLockMode(String, LockMode)}.
+	 * <p>
+	 * Differs from {@link #getEffectiveLockMode(String)} in that here we
+	 * only return an explicitly specified alias-specific lock mode.
 	 *
-	 * @return the number of explicitly defined alias lock modes.
+	 * @param alias The alias for which to locate the explicit lock mode.
+	 * @return The explicit lock mode for that alias.
 	 */
-	public int getAliasLockCount() {
-		return aliasSpecificLockModes == null ? 0 : aliasSpecificLockModes.size();
+	public LockMode getAliasSpecificLockMode(String alias) {
+		return aliasSpecificLockModes == null ? null : aliasSpecificLockModes.get( alias );
 	}
 
 	/**
@@ -384,14 +392,24 @@ public Iterator<Map.Entry<String,LockMode>> getAliasLockIterator() {
 	}
 
 	/**
-	 * Set of {@link Map.Entry}s, each associating an alias with its
-	 * specified {@linkplain #setAliasSpecificLockMode alias-specific}
-	 * {@link LockMode}.
+	 * 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
+	 * returned. If the overall lock mode is also {@code null},
+	 * {@link LockMode#NONE} is returned.
+	 * <p>
+	 * Differs from {@link #getAliasSpecificLockMode(String)} in that here
+	 * we fall back to only returning the overall lock mode.
 	 *
-	 * @return an iterable with the {@link Map.Entry}s
+	 * @param alias The alias for which to locate the effective lock mode.
+	 * @return The effective lock mode.
 	 */
-	public Set<Map.Entry<String,LockMode>> getAliasSpecificLocks() {
-		return aliasSpecificLockModes == null ? emptySet() : unmodifiableSet( aliasSpecificLockModes.entrySet() );
+	public LockMode getEffectiveLockMode(String alias) {
+		LockMode lockMode = getAliasSpecificLockMode( alias );
+		if ( lockMode == null ) {
+			lockMode = this.lockMode;
+		}
+		return lockMode == null ? LockMode.NONE : lockMode;
 	}
 
 	/**
@@ -453,7 +471,7 @@ public LockOptions setTimeout(Timeout timeout) {
 	 *         {@link #WAIT_FOREVER}, or {@link #SKIP_LOCKED}
 	 */
 	public int getTimeOut() {
-		return timeout.milliseconds();
+		return getTimeout().milliseconds();
 	}
 
 	/**
@@ -468,12 +486,10 @@ public int getTimeOut() {
 	 * @see #getTimeOut
 	 */
 	public LockOptions setTimeOut(int timeout) {
-		if ( immutable ) {
-			throw new UnsupportedOperationException("immutable global instance of LockMode");
-		}
 		return setTimeout( Timeouts.interpretMilliSeconds( timeout ) );
 	}
 
+
 	/**
 	 * The current lock scope:
 	 * <ul>
@@ -604,26 +620,4 @@ public static LockOptions copy(LockOptions source, LockOptions destination) {
 		destination.setFollowOnLocking( source.getFollowOnLocking() );
 		return destination;
 	}
-
-	@Override
-	public boolean equals(Object object) {
-		if ( this == object ) {
-			return true;
-		}
-		else if ( !(object instanceof LockOptions that) ) {
-			return false;
-		}
-		else {
-			return timeout == that.timeout
-				&& pessimisticLockScope == that.pessimisticLockScope
-				&& lockMode == that.lockMode
-				&& Objects.equals( aliasSpecificLockModes, that.aliasSpecificLockModes )
-				&& Objects.equals( followOnLocking, that.followOnLocking );
-		}
-	}
-
-	@Override
-	public int hashCode() {
-		return Objects.hash( lockMode, timeout, aliasSpecificLockModes, followOnLocking, pessimisticLockScope );
-	}
 }