Skip to content

Commit 72fa92b

Browse files
committed
HHH-19440 completely deprecate LockOptions
and explain what's going on with it in the javadoc
1 parent 42959cc commit 72fa92b

14 files changed

+62
-29
lines changed

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

+36-10
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,6 @@
66

77
import jakarta.persistence.PessimisticLockScope;
88
import jakarta.persistence.Timeout;
9-
import org.hibernate.query.Query;
109

1110
import java.io.Serializable;
1211
import java.util.HashMap;
@@ -28,9 +27,9 @@
2827
* {@link Session#refresh(Object, LockOptions)}, the relevant options
2928
* are:
3029
* <ul>
31-
* <li>the {@linkplain #getLockMode() lock mode},
32-
* <li>the {@linkplain #getTimeOut() pessimistic lock timeout}, and
33-
* <li>the {@linkplain #getLockScope() lock scope}, that is, whether
30+
* <li>the {@linkplain #getLockMode lock mode},
31+
* <li>the {@linkplain #getTimeOut pessimistic lock timeout}, and
32+
* <li>the {@linkplain #getLockScope lock scope}, that is, whether
3433
* the lock extends to rows of owned collections.
3534
* </ul>
3635
* <p>
@@ -48,8 +47,33 @@
4847
* default behavior of the SQL dialect} by passing a non-null argument
4948
* to {@link #setFollowOnLocking(Boolean)}.
5049
*
50+
* @deprecated
51+
* Since JPA 3.2 and Hibernate 7, a {@link LockMode}, {@link Timeout},
52+
* or {@link PessimisticLockScope} may be passed directly as an option
53+
* to {@code find()}, {@code refresh()}, or {@code lock()}. Therefore,
54+
* this class is obsolete as an API and will be moved to an SPI package.
55+
* <p>
56+
* For HQL/JPQL queries, locking should be controlled via operations of
57+
* the {@link org.hibernate.query.SelectionQuery} interface:
58+
* <ul>
59+
* <li>A timeout may be set via
60+
* {@link org.hibernate.query.CommonQueryContract#setTimeout(Timeout)}
61+
* <li>The {@code PessimisticLockScope} may be set using
62+
* {@link org.hibernate.query.SelectionQuery#setLockScope(PessimisticLockScope)}
63+
* <li>Alias-specific lock modes may be specified using
64+
* {@link org.hibernate.query.SelectionQuery#setLockMode(String, LockMode)}
65+
* <li>Use of follow-on locking may be enabled via
66+
* {@link org.hibernate.query.SelectionQuery#setFollowOnLocking(boolean)}
67+
* </ul>
68+
* The interface {@link Timeouts} provides several operations to simplify
69+
* migration.
70+
*
71+
* @see LockMode
72+
* @see Timeouts
73+
*
5174
* @author Scott Marlow
5275
*/
76+
@Deprecated(since = "7.0", forRemoval = true) // moving to an SPI package
5377
public class LockOptions implements Serializable {
5478
/**
5579
* Represents {@link LockMode#NONE}, to which timeout and scope are
@@ -191,7 +215,7 @@ public LockOptions(LockMode lockMode, int timeout) {
191215

192216
/**
193217
* Construct an instance with the given {@linkplain LockMode mode},
194-
* timeout, and {@link PessimisticLockScope scope}.
218+
* timeout, and {@linkplain PessimisticLockScope scope}.
195219
*
196220
* @param lockMode The initial lock mode
197221
* @param timeout The initial timeout
@@ -206,7 +230,7 @@ public LockOptions(LockMode lockMode, Timeout timeout, PessimisticLockScope scop
206230

207231
/**
208232
* Construct an instance with the given {@linkplain LockMode mode},
209-
* timeout, and {@link PessimisticLockScope scope}.
233+
* timeout, and {@linkplain PessimisticLockScope scope}.
210234
*
211235
* @param lockMode The initial lock mode
212236
* @param timeout The initial timeout, in milliseconds
@@ -228,6 +252,7 @@ private LockOptions(boolean immutable, LockMode lockMode) {
228252
timeout = Timeouts.WAIT_FOREVER;
229253
pessimisticLockScope = NORMAL;
230254
}
255+
231256
/**
232257
* Determine of the lock options are empty.
233258
*
@@ -273,7 +298,7 @@ public LockOptions setLockMode(LockMode lockMode) {
273298
* @param lockMode the lock mode to apply to the given alias
274299
* @return {@code this} for method chaining
275300
*
276-
* @see Query#setLockMode(String, LockMode)
301+
* @see org.hibernate.query.Query#setLockMode(String, LockMode)
277302
*/
278303
public LockOptions setAliasSpecificLockMode(String alias, LockMode lockMode) {
279304
if ( immutable ) {
@@ -307,8 +332,8 @@ public LockMode getAliasSpecificLockMode(String alias) {
307332

308333
/**
309334
* Determine the {@link LockMode} to apply to the given alias. If no
310-
* mode was {@linkplain #setAliasSpecificLockMode(String, LockMode)}
311-
* explicitly set}, the {@linkplain #getLockMode()} overall mode} is
335+
* mode was {@linkplain #setAliasSpecificLockMode(String, LockMode)
336+
* explicitly set}, the {@linkplain #getLockMode() overall mode} is
312337
* returned. If the overall lock mode is also {@code null},
313338
* {@link LockMode#NONE} is returned.
314339
* <p>
@@ -432,7 +457,8 @@ public int getTimeOut() {
432457
}
433458

434459
/**
435-
* Set the {@linkplain #getTimeout() timeout}, in milliseconds, associated with {@code this} options.
460+
* Set the {@linkplain #getTimeout() timeout}, in milliseconds, associated
461+
* with {@code this} options.
436462
* <p/>
437463
* {@link #NO_WAIT}, {@link #WAIT_FOREVER}, or {@link #SKIP_LOCKED}
438464
* represent 3 "magic" values.

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

+5-5
Original file line numberDiff line numberDiff line change
@@ -7,12 +7,12 @@
77
import jakarta.persistence.Timeout;
88

99
/**
10-
* Helpers for dealing with {@linkplain jakarta.persistence.Timeout time out} values,
11-
* including some "magic values".
10+
* Helpers for dealing with {@linkplain jakarta.persistence.Timeout timeout}
11+
* values, including some "magic values".
1212
*
13-
* @apiNote The {@linkplain #NO_WAIT} and {@linkplain #SKIP_LOCKED} magic values have
14-
* special {@linkplain LockMode} values as well ({@linkplain LockMode#UPGRADE_NOWAIT}
15-
* and {@linkplain LockMode#UPGRADE_SKIPLOCKED}, respectively).
13+
* @apiNote The {@link #NO_WAIT} and {@link #SKIP_LOCKED} magic values each
14+
* have a corresponding {@link LockMode} ({@link LockMode#UPGRADE_NOWAIT}
15+
* and {@link LockMode#UPGRADE_SKIPLOCKED}, respectively).
1616
*
1717
* @author Steve Ebersole
1818
*

hibernate-core/src/main/java/org/hibernate/procedure/internal/ProcedureCallImpl.java

+1-1
Original file line numberDiff line numberDiff line change
@@ -1059,7 +1059,7 @@ public LockModeType getLockMode() {
10591059
throw new IllegalStateException( "Illegal attempt to get lock mode on a native-query" );
10601060
}
10611061

1062-
@Override
1062+
@Override @Deprecated
10631063
public QueryImplementor<R> setLockOptions(LockOptions lockOptions) {
10641064
throw new UnsupportedOperationException( "setLockOptions does not apply to procedure calls" );
10651065
}

hibernate-core/src/main/java/org/hibernate/query/NativeQuery.java

+2-2
Original file line numberDiff line numberDiff line change
@@ -626,7 +626,7 @@ interface FetchReturn extends ResultNode {
626626
* result in changes to the native SQL query that is
627627
* actually executed.
628628
*/
629-
@Override
629+
@Override @Deprecated(forRemoval = true)
630630
LockOptions getLockOptions();
631631

632632
/**
@@ -637,7 +637,7 @@ interface FetchReturn extends ResultNode {
637637
* result in changes to the native SQL query that is
638638
* actually executed.
639639
*/
640-
@Override
640+
@Override @Deprecated(forRemoval = true)
641641
NativeQuery<T> setLockOptions(LockOptions lockOptions);
642642

643643
/**

hibernate-core/src/main/java/org/hibernate/query/Query.java

+3-2
Original file line numberDiff line numberDiff line change
@@ -361,10 +361,11 @@ default Query<R> applyLoadGraph(@SuppressWarnings("rawtypes") RootGraph graph) {
361361
*
362362
* @see LockOptions
363363
*
364-
* @deprecated To be removed with no replacement - this is an SPI/internal concern.
364+
* @deprecated Since {@link LockOptions} is transitioning to
365+
* a new role as an SPI.
365366
*/
366-
@Deprecated(since = "7.0", forRemoval = true)
367367
@Override
368+
@Deprecated(since = "7.0", forRemoval = true)
368369
LockOptions getLockOptions();
369370

370371
/**

hibernate-core/src/main/java/org/hibernate/query/SelectionQuery.java

+4
Original file line numberDiff line numberDiff line change
@@ -558,7 +558,11 @@ default Stream<R> stream() {
558558

559559
/**
560560
* The {@link LockOptions} currently in effect for the query
561+
*
562+
* @deprecated Since {@link LockOptions} is transitioning to
563+
* a new role as an SPI.
561564
*/
565+
@Deprecated(since = "7.0", forRemoval = true)
562566
LockOptions getLockOptions();
563567

564568
/**

hibernate-core/src/main/java/org/hibernate/query/hql/spi/SqmQueryImplementor.java

+1-1
Original file line numberDiff line numberDiff line change
@@ -92,7 +92,7 @@ default SqmQueryImplementor<R> applyLoadGraph(@SuppressWarnings("rawtypes") Root
9292
@Override
9393
SqmQueryImplementor<R> addQueryHint(String hint);
9494

95-
@Override
95+
@Override @Deprecated
9696
SqmQueryImplementor<R> setLockOptions(LockOptions lockOptions);
9797

9898
@Override

hibernate-core/src/main/java/org/hibernate/query/spi/AbstractQuery.java

+2-2
Original file line numberDiff line numberDiff line change
@@ -258,12 +258,12 @@ public QueryImplementor<R> setReadOnly(boolean readOnly) {
258258
return this;
259259
}
260260

261-
@Override
261+
@Override @Deprecated
262262
public LockOptions getLockOptions() {
263263
return getQueryOptions().getLockOptions();
264264
}
265265

266-
@Override
266+
@Override @Deprecated
267267
public QueryImplementor<R> setLockOptions(LockOptions lockOptions) {
268268
getQueryOptions().getLockOptions().overlay( lockOptions );
269269
return this;

hibernate-core/src/main/java/org/hibernate/query/spi/AbstractSelectionQuery.java

+1-1
Original file line numberDiff line numberDiff line change
@@ -398,7 +398,7 @@ public SelectionQuery<R> disableFetchProfile(String profileName) {
398398
return this;
399399
}
400400

401-
@Override
401+
@Override @Deprecated
402402
public LockOptions getLockOptions() {
403403
return getQueryOptions().getLockOptions();
404404
}

hibernate-core/src/main/java/org/hibernate/query/sql/internal/NativeQueryImpl.java

+1-1
Original file line numberDiff line numberDiff line change
@@ -572,7 +572,7 @@ public LockModeType getLockMode() {
572572
throw new IllegalStateException( "Illegal attempt to get lock mode on a native-query" );
573573
}
574574

575-
@Override
575+
@Override @Deprecated
576576
public NativeQueryImplementor<R> setLockOptions(LockOptions lockOptions) {
577577
super.setLockOptions( lockOptions );
578578
return this;

hibernate-core/src/main/java/org/hibernate/query/sql/spi/NativeQueryImplementor.java

+1-1
Original file line numberDiff line numberDiff line change
@@ -174,7 +174,7 @@ NativeQueryImplementor<R> addJoin(
174174
@Override
175175
NativeQueryImplementor<R> setReadOnly(boolean readOnly);
176176

177-
@Override
177+
@Override @Deprecated
178178
NativeQueryImplementor<R> setLockOptions(LockOptions lockOptions);
179179

180180
@Override

hibernate-core/src/main/java/org/hibernate/query/sqm/internal/QuerySqmImpl.java

+1-1
Original file line numberDiff line numberDiff line change
@@ -707,7 +707,7 @@ public SqmQueryImplementor<R> addQueryHint(String hint) {
707707
return this;
708708
}
709709

710-
@Override
710+
@Override @Deprecated
711711
public SqmQueryImplementor<R> setLockOptions(LockOptions lockOptions) {
712712
// No verifySelect call, because in Hibernate we support locking in subqueries
713713
getQueryOptions().getLockOptions().overlay( lockOptions );

hibernate-core/src/main/java/org/hibernate/query/sqm/spi/DelegatingSqmSelectionQueryImplementor.java

+1-1
Original file line numberDiff line numberDiff line change
@@ -263,7 +263,7 @@ public String getCacheRegion() {
263263
return getDelegate().getCacheRegion();
264264
}
265265

266-
@Override
266+
@Override @Deprecated
267267
public LockOptions getLockOptions() {
268268
return getDelegate().getLockOptions();
269269
}

migration-guide.adoc

+3-1
Original file line numberDiff line numberDiff line change
@@ -736,7 +736,9 @@ Now, `varchar(1)` is used by default.
736736
[[lock-options]]
737737
== LockOptions
738738

739-
The exposure of `LockOptions` as an API has been deprecated. Applications should instead prefer the use of `LockMode` (or `LockModeType`), `Timeout` and `PessimisticLockScope`.
739+
`LockOptions` has been marked deprecated.
740+
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()`.
741+
Therefore, this class is obsolete as an API and will be moved to an SPI package.
740742

741743
Use this
742744

0 commit comments

Comments
 (0)