Skip to content

HHH-19440 completely deprecate LockOptions #10145

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
May 13, 2025
Merged

HHH-19440 completely deprecate LockOptions #10145

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 36 additions & 10 deletions hibernate-core/src/main/java/org/hibernate/LockOptions.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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>
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -228,6 +252,7 @@ private LockOptions(boolean immutable, LockMode lockMode) {
timeout = Timeouts.WAIT_FOREVER;
pessimisticLockScope = NORMAL;
}

/**
* Determine of the lock options are empty.
*
Expand Down Expand Up @@ -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 ) {
Expand Down Expand Up @@ -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>
Expand Down Expand Up @@ -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.
Expand Down
10 changes: 5 additions & 5 deletions hibernate-core/src/main/java/org/hibernate/Timeouts.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
*
Expand Down
2 changes: 1 addition & 1 deletion hibernate-core/src/main/java/org/hibernate/procedure/internal/ProcedureCallImpl.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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" );
}
Expand Down
4 changes: 2 additions & 2 deletions hibernate-core/src/main/java/org/hibernate/query/NativeQuery.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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();

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

/**
Expand Down
5 changes: 3 additions & 2 deletions hibernate-core/src/main/java/org/hibernate/query/Query.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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();

/**
Expand Down
4 changes: 4 additions & 0 deletions hibernate-core/src/main/java/org/hibernate/query/SelectionQuery.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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();

/**
Expand Down
2 changes: 1 addition & 1 deletion hibernate-core/src/main/java/org/hibernate/query/hql/spi/SqmQueryImplementor.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 2 additions & 2 deletions hibernate-core/src/main/java/org/hibernate/query/spi/AbstractQuery.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down
2 changes: 1 addition & 1 deletion hibernate-core/src/main/java/org/hibernate/query/spi/AbstractSelectionQuery.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -398,7 +398,7 @@ public SelectionQuery<R> disableFetchProfile(String profileName) {
return this;
}

@Override
@Override @Deprecated
public LockOptions getLockOptions() {
return getQueryOptions().getLockOptions();
}
Expand Down
2 changes: 1 addition & 1 deletion hibernate-core/src/main/java/org/hibernate/query/sql/internal/NativeQueryImpl.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down
2 changes: 1 addition & 1 deletion hibernate-core/src/main/java/org/hibernate/query/sql/spi/NativeQueryImplementor.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -174,7 +174,7 @@ NativeQueryImplementor<R> addJoin(
@Override
NativeQueryImplementor<R> setReadOnly(boolean readOnly);

@Override
@Override @Deprecated
NativeQueryImplementor<R> setLockOptions(LockOptions lockOptions);

@Override
Expand Down
2 changes: 1 addition & 1 deletion hibernate-core/src/main/java/org/hibernate/query/sqm/internal/QuerySqmImpl.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 );
Expand Down
2 changes: 1 addition & 1 deletion ...ore/src/main/java/org/hibernate/query/sqm/spi/DelegatingSqmSelectionQueryImplementor.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -263,7 +263,7 @@ public String getCacheRegion() {
return getDelegate().getCacheRegion();
}

@Override
@Override @Deprecated
public LockOptions getLockOptions() {
return getDelegate().getLockOptions();
}
Expand Down
4 changes: 3 additions & 1 deletion migration-guide.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
Loading