diff --git a/hibernate-core/src/main/java/org/hibernate/LockOptions.java b/hibernate-core/src/main/java/org/hibernate/LockOptions.java index fcc02a47b186..54db73b98de2 100644 --- 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: * *

@@ -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. + *

+ * For HQL/JPQL queries, locking should be controlled via operations of + * the {@link org.hibernate.query.SelectionQuery} interface: + *

+ * 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. *

@@ -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. *

* {@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 index a8850ca43633..fc3fe1dd81d3 100644 --- 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 index d2886c58256f..697c3df327d2 100644 --- 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 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 index 0f9d7f05208a..315f7cfde4c7 100644 --- 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 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 index e46a1af45444..97e43e224d98 100644 --- 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 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 index 82684abd7f3d..1315993df830 100644 --- 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 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 index 30865b9f02ba..0f5385b0c769 100644 --- 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 applyLoadGraph(@SuppressWarnings("rawtypes") Root @Override SqmQueryImplementor addQueryHint(String hint); - @Override + @Override @Deprecated SqmQueryImplementor 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 index 33c152366f65..ef7e187e70c2 100644 --- 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 setReadOnly(boolean readOnly) { return this; } - @Override + @Override @Deprecated public LockOptions getLockOptions() { return getQueryOptions().getLockOptions(); } - @Override + @Override @Deprecated public QueryImplementor 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 index e4bf1ab1f886..b95781511523 100644 --- 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 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 index 609e200905f7..4e5b7e8418bc 100644 --- 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 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 index dbd2b61542e6..eeef6091a027 100644 --- 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 addJoin( @Override NativeQueryImplementor setReadOnly(boolean readOnly); - @Override + @Override @Deprecated NativeQueryImplementor 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 index 4f0878734bc6..6aa7b3c313b8 100644 --- 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 addQueryHint(String hint) { return this; } - @Override + @Override @Deprecated public SqmQueryImplementor 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 index 372e32d29297..d20e399f7e2d 100644 --- 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 index 7eba87c8c3b4..06a4b27004f8 100644 --- 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