HHH-19440 - Deprecate exposing of LockOptions

Author: sebersole

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

@@ -4,9 +4,7 @@
  */
 package org.hibernate;
 
-import jakarta.persistence.FindOption;
 import jakarta.persistence.PessimisticLockScope;
-import jakarta.persistence.RefreshOption;
 import jakarta.persistence.Timeout;
 import org.hibernate.query.Query;
 
@@ -52,7 +50,7 @@
  *
  * @author Scott Marlow
  */
-public class LockOptions implements FindOption, RefreshOption, Serializable {
+public class LockOptions implements Serializable {
 	/**
 	 * Represents {@link LockMode#NONE}, to which timeout and scope are
 	 * not applicable.

hibernate-core/src/test/java/org/hibernate/orm/test/jpa/lock/LockExceptionTests.java

@@ -4,28 +4,27 @@
  */
 package org.hibernate.orm.test.jpa.lock;
 
+import jakarta.persistence.LockModeType;
+import jakarta.persistence.LockTimeoutException;
+import jakarta.persistence.PessimisticLockException;
 import org.hibernate.Timeouts;
 import org.hibernate.boot.registry.StandardServiceRegistryBuilder;
 import org.hibernate.cfg.AvailableSettings;
 import org.hibernate.dialect.CockroachDialect;
 import org.hibernate.dialect.SQLServerDialect;
 import org.hibernate.engine.jdbc.connections.spi.ConnectionProvider;
+import org.hibernate.exception.LockAcquisitionException;
 import org.hibernate.orm.test.jpa.model.AbstractJPATest;
 import org.hibernate.orm.test.jpa.model.Item;
-
-import org.hibernate.testing.orm.junit.JiraKey;
 import org.hibernate.testing.jdbc.SQLServerSnapshotIsolationConnectionProvider;
 import org.hibernate.testing.orm.junit.DialectFeatureChecks;
+import org.hibernate.testing.orm.junit.JiraKey;
 import org.hibernate.testing.orm.junit.RequiresDialectFeature;
 import org.hibernate.testing.orm.junit.SkipForDialect;
 import org.hibernate.testing.transaction.TransactionUtil2;
 import org.junit.jupiter.api.AfterAll;
 import org.junit.jupiter.api.Test;
 
-import jakarta.persistence.LockModeType;
-import jakarta.persistence.LockTimeoutException;
-import jakarta.persistence.PessimisticLockException;
-
 import static org.junit.jupiter.api.Assertions.fail;
 
 /**
@@ -78,7 +77,7 @@ public void testLockTimeoutFind() {
 										);
 										fail( "Expecting a failure" );
 									}
-									catch (LockTimeoutException | PessimisticLockException | org.hibernate.exception.LockTimeoutException expected ) {
+									catch (LockTimeoutException | PessimisticLockException | LockAcquisitionException expected ) {
 										// expected outcome
 									}
 								}

migration-guide.adoc

@@ -729,11 +729,47 @@ Now, `varchar(1)` is used by default.
 
 
 [[settings]]
-=== Changes Related to Settings
+== Changes Related to Settings
 
 * Removed `hibernate.mapping.precedence` and friends
 * Removed `hibernate.allow_refresh_detached_entity`
 
+[[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`.
+
+Use this
+
+====
+[source, java, indent=0]
+----
+Book loaded = session.find(
+    Book.class,
+    1,
+    LockMode.PESSIMISTIC_WRITE,
+    Timeouts.NO_WAIT
+);
+----
+====
+
+instead of this
+
+====
+[source, java, indent=0]
+----
+Book loaded = session.find(
+    Book.class,
+    1,
+    new LockOptions(
+        LockMode.PESSIMISTIC_WRITE,
+        0
+    )
+);
+----
+====
+
+See the link:{whatsNewBase}#operation-options[What's New] guide for more details.
 
 
 [[pools]]

whats-new.adoc

@@ -126,6 +126,53 @@ The new operations `Session.findMultiple()` and `StatelessSession.getMultiple()`
 Combined with the `BatchSize` option, allows breaking up the JDBC calls into "batches".
 
 
+[[operation-options]]
+== FindOption, LockOption, RefreshOption
+
+As a more typesafe replacement for hints, Jakarta Persistence now allows for "option objects" which indicate these hints.  Not only is it more typesafe, but also more concise - a double win!
+
+These "option objects" come in 3 flavors depending on what operation is being performed -
+
+FindOption:: Used to indicate options for find operations :
+    * `Session.find`
+    * `Session.findMultiple`
+    * etc
+LockOption:: Used to indicate options for `Session.lock`
+RefreshOption:: Used to indicate options for `Session.refresh`
+
+Each of these are interfaces.  Jakarta Persistence does provide some built-in options:
+
+CacheRetrieveMode:: Is now a `FindOption`.
+CacheStoreMode:: Is now a `FindOption` and a `RefreshOption`.
+LockModeType:: Is now a `FindOption` and a `RefreshOption`.
+Timeout (new):: Is a `FindOption`, a `RefreshOption` and a `LockOption`.  See also `org.hibernate.Timeouts` for some magic values.
+PessimisticLockScope:: Is now a `FindOption`, a `RefreshOption` and a `LockOption`
+
+Hibernate provides a few additional options:
+
+ReadOnlyMode (new):: Is a `FindOption` which indicates whether the entities and collections being loaded should be considered read-only.
+EnabledFetchProfile (new):: Is a `FindOption` indicating a fetch-profile to be enabled for the find operation.
+LockMode:: Is now a `FindOption` and a `RefreshOption` (expanded version of JPA's `LockModeType`).
+CacheMode:: Is now a `FindOption`.
+BatchSize (new):: Is now a `FindOption`.
+
+
+All operations which accept options (which previously accepted hints) accept a varargs grouping of them.  E.g.
+
+====
+[source, java, indent=0]
+----
+Book loaded = session.find(
+    Book.class,
+    1,
+    LockMode.PESSIMISTIC_WRITE,
+    Timeouts.NO_WAIT,
+    new EnabledFetchProfile("with-authors")
+);
+----
+====
+
+
 [[QuerySpecification]]
 == QuerySpecification, Restriction, and Range