Class LockOptions

java.lang.Object

org.hibernate.LockOptions

All Implemented Interfaces:

Serializable

@Deprecated(since="7",
            forRemoval=true)
public class LockOptions
extends Object
implements Serializable

Deprecated, for removal: This API element is subject to removal in a future version.

Since JPA 3.2 and Hibernate 7, a LockMode, 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.

For HQL/JPQL queries, locking should be controlled via operations of the SelectionQuery interface:

• A timeout may be set via CommonQueryContract.setTimeout(Timeout)
• The PessimisticLockScope may be set using SelectionQuery.setLockScope(PessimisticLockScope)
• Use of follow-on locking may be enabled via SelectionQuery.setFollowOnStrategy(Locking.FollowOn)

The interface Timeouts provides several operations to simplify migration.

Contains a set of options describing how a row of a database table mapped by an entity should be locked. For Session.lock(Object, LockOptions), Session.get(Class, Object, LockOptions), or Session.refresh(Object, LockOptions), the relevant options are:

• the lock mode,
• the pessimistic lock timeout, and
• the lock scope, that is, whether the lock extends to rows of owned collections.

Timeout and lock scope are ignored if the specified LockMode represents a flavor of optimistic locking.

In HQL and criteria queries, lock modes can be defined in an even more granular fashion, with the option to specify a lock mode that applies only to a certain query alias.

Finally, the use of follow-on locking may be force enabled or disabled, overriding the default behavior of the SQL dialect's follow-on locking policy by passing a non-null argument to setFollowOnLocking(Boolean).

See Also:

• Timeout
• Timeouts
• LockMode
• LockModeType
• PessimisticLockScope
• Serialized Form

Field Summary

Fields

Modifier and Type	Field	Description
static final int	NO_WAIT	Deprecated, for removal: This API element is subject to removal in a future version. This, and the other constants on this class, will be removed.
static final LockOptions	NONE	Deprecated, for removal: This API element is subject to removal in a future version. This, and the other constants on this class, will be removed.
static final LockOptions	READ	Deprecated, for removal: This API element is subject to removal in a future version. This, and the other constants on this class, will be removed.
static final int	SKIP_LOCKED	Deprecated, for removal: This API element is subject to removal in a future version. This, and the other constants on this class, will be removed.
static final LockOptions	UPGRADE	Deprecated, for removal: This API element is subject to removal in a future version. This, and the other constants on this class, will be removed.
static final int	WAIT_FOREVER	Deprecated, for removal: This API element is subject to removal in a future version. This, and the other constants on this class, will be removed.

Constructor Summary

Constructors

Modifier	Constructor	Description
	LockOptions()	Deprecated, for removal: This API element is subject to removal in a future version. Construct an instance with mode LockMode.NONE and no timeout.
protected	LockOptions(boolean immutable, LockMode lockMode)	Deprecated, for removal: This API element is subject to removal in a future version. Internal operation used to create immutable global instances.
	LockOptions(LockMode lockMode)	Deprecated, for removal: This API element is subject to removal in a future version. Construct an instance with the given mode and no timeout.
	LockOptions(LockMode lockMode, int timeout)	Deprecated. Use LockOptions(LockMode, Timeout) instead
	LockOptions(LockMode lockMode, int timeout, PessimisticLockScope scope)	Deprecated. Use LockOptions(LockMode, Timeout, PessimisticLockScope) instead
	LockOptions(LockMode lockMode, int timeout, PessimisticLockScope scope, Locking.FollowOn followOnStrategy)	Deprecated, for removal: This API element is subject to removal in a future version.
	LockOptions(LockMode lockMode, Timeout timeout)	Deprecated, for removal: This API element is subject to removal in a future version. Construct an instance with the given mode and timeout.
	LockOptions(LockMode lockMode, Timeout timeout, PessimisticLockScope jpaScope)	Deprecated, for removal: This API element is subject to removal in a future version. Construct an instance with the given mode, timeout, and scope.

Method Summary

Modifier and Type	Method	Description
static LockOptions	copy(LockOptions source, LockOptions destination)	Deprecated, for removal: This API element is subject to removal in a future version. LockOptions will be made into a record.
boolean	equals(Object object)	Deprecated, for removal: This API element is subject to removal in a future version.
LockMode	findGreatestLockMode()	Deprecated, for removal: This API element is subject to removal in a future version. Alias-specific locks are no longer supported, roughly replaced with locking scope.
int	getAliasLockCount()	Deprecated, for removal: This API element is subject to removal in a future version. Alias-specific locks are no longer supported, roughly replaced with locking scope.
Iterator<Map.Entry<String,LockMode>>	getAliasLockIterator()	Deprecated, for removal: This API element is subject to removal in a future version. Alias-specific locks are no longer supported, roughly replaced with locking scope.
LockMode	getAliasSpecificLockMode(String alias)	Deprecated, for removal: This API element is subject to removal in a future version. Alias-specific locks are no longer supported, roughly replaced with locking scope.
Set<Map.Entry<String,LockMode>>	getAliasSpecificLocks()	Deprecated, for removal: This API element is subject to removal in a future version. Alias-specific locks are no longer supported, roughly replaced with locking scope.
LockMode	getEffectiveLockMode(String alias)	Deprecated, for removal: This API element is subject to removal in a future version. Alias-specific locks are no longer supported, roughly replaced with locking scope.
Boolean	getFollowOnLocking()	Deprecated. Use getFollowOnStrategy() instead.
Locking.FollowOn	getFollowOnStrategy()	Deprecated, for removal: This API element is subject to removal in a future version. Whether follow-on locking is allowed or, if not, how to handle cases where Hibernate determines it would need to use follow-on locking.
LockMode	getLockMode()	Deprecated, for removal: This API element is subject to removal in a future version. Retrieve the overall lock mode in effect for this set of options.
PessimisticLockScope	getLockScope()	Deprecated, for removal: This API element is subject to removal in a future version. Use getScope() instead
PessimisticLockScope	getScope()	Deprecated, for removal: This API element is subject to removal in a future version. Associated lock scope
Timeout	getTimeout()	Deprecated, for removal: This API element is subject to removal in a future version. The timeout associated with this options, defining a maximum amount of time that the database should wait to obtain a pessimistic lock before returning an error to the client.
int	getTimeOut()	Deprecated, for removal: This API element is subject to removal in a future version. The timeout, in milliseconds, associated with this options.
boolean	hasAliasSpecificLockModes()	Deprecated, for removal: This API element is subject to removal in a future version. Alias-specific locks are no longer supported, roughly replaced with locking scope.
int	hashCode()	Deprecated, for removal: This API element is subject to removal in a future version.
boolean	hasNonDefaultOptions()	Deprecated, for removal: This API element is subject to removal in a future version.
boolean	isEmpty()	Deprecated, for removal: This API element is subject to removal in a future version. Whether this LockOptions instance is "empty".
LockOptions	makeCopy()	Deprecated, for removal: This API element is subject to removal in a future version. LockOptions will be made into a record.
LockOptions	makeDefensiveCopy()	Deprecated, for removal: This API element is subject to removal in a future version. LockOptions will be made into a record.
void	overlay(LockOptions lockOptions)	Deprecated, for removal: This API element is subject to removal in a future version. LockOptions will be made into a record.
LockOptions	setAliasSpecificLockMode(String alias, LockMode lockMode)	Deprecated, for removal: This API element is subject to removal in a future version. Alias-specific locks are no longer supported, roughly replaced with locking scope.
LockOptions	setFollowOnLocking(Boolean followOnLocking)	Deprecated. Use setFollowOnStrategy(Locking.FollowOn) instead.
LockOptions	setFollowOnStrategy(Locking.FollowOn followOnStrategy)	Deprecated, for removal: This API element is subject to removal in a future version. How to handle cases where Hibernate has determined it would need to use follow-on locking.
LockOptions	setLockMode(LockMode lockMode)	Deprecated, for removal: This API element is subject to removal in a future version. Set the overall lock mode.
LockOptions	setLockScope(PessimisticLockScope jpaScope)	Deprecated, for removal: This API element is subject to removal in a future version. Use setScope(PessimisticLockScope) instead
LockOptions	setScope(PessimisticLockScope scope)	Deprecated, for removal: This API element is subject to removal in a future version. Set the associated lock scope
LockOptions	setTimeout(Timeout timeout)	Deprecated, for removal: This API element is subject to removal in a future version. Set the timeout associated with this options.
LockOptions	setTimeOut(int timeout)	Deprecated, for removal: This API element is subject to removal in a future version. Set the timeout, in milliseconds, associated with this options.

Methods inherited from class Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Field Details

NONE

@Deprecated(since="7",
            forRemoval=true)
public static final LockOptions NONE

Deprecated, for removal: This API element is subject to removal in a future version.

This, and the other constants on this class, will be removed.

Represents LockMode.NONE, to which timeout and scope are not applicable.

READ

@Deprecated(since="7",
            forRemoval=true)
public static final LockOptions READ

Deprecated, for removal: This API element is subject to removal in a future version.

This, and the other constants on this class, will be removed.

Represents LockMode.READ, to which timeout and scope are not applicable.

UPGRADE

@Deprecated(since="7",
            forRemoval=true)
public static final LockOptions UPGRADE

Deprecated, for removal: This API element is subject to removal in a future version.

This, and the other constants on this class, will be removed.

Represents LockMode.PESSIMISTIC_WRITE with no timeout, and no extension of the lock to owned collections.

NO_WAIT

@Deprecated(since="7",
            forRemoval=true)
public static final int NO_WAIT

Deprecated, for removal: This API element is subject to removal in a future version.

This, and the other constants on this class, will be removed.

See Also:

• Timeouts.NO_WAIT_MILLI
• Timeouts.NO_WAIT
• getTimeOut()
• Constant Field Values

WAIT_FOREVER

@Deprecated(since="7",
            forRemoval=true)
public static final int WAIT_FOREVER

Deprecated, for removal: This API element is subject to removal in a future version.

This, and the other constants on this class, will be removed.

See Also:

• Timeouts.WAIT_FOREVER_MILLI
• Timeouts.WAIT_FOREVER
• getTimeOut()
• Constant Field Values

SKIP_LOCKED

@Deprecated(since="6.2",
            forRemoval=true)
public static final int SKIP_LOCKED

Deprecated, for removal: This API element is subject to removal in a future version.

This, and the other constants on this class, will be removed.

See Also:

• Timeouts.SKIP_LOCKED_MILLI
• Timeouts.SKIP_LOCKED
• getTimeOut()
• Constant Field Values

Constructor Details

LockOptions

public LockOptions()

Deprecated, for removal: This API element is subject to removal in a future version.

Construct an instance with mode LockMode.NONE and no timeout.

See Also:

• LockMode.NONE
• Timeouts.WAIT_FOREVER
• PessimisticLockScope.NORMAL
• Locking.FollowOn.ALLOW

LockOptions

public LockOptions(LockMode lockMode)

Deprecated, for removal: This API element is subject to removal in a future version.

Construct an instance with the given mode and no timeout.

Parameters:

lockMode - The initial lock mode

See Also:

• Timeouts.WAIT_FOREVER
• PessimisticLockScope.NORMAL
• Locking.FollowOn.ALLOW

LockOptions

public LockOptions(LockMode lockMode,
 Timeout timeout)

Deprecated, for removal: This API element is subject to removal in a future version.

Construct an instance with the given mode and timeout.

Parameters:

lockMode - The initial lock mode

timeout - The initial timeout, in milliseconds

See Also:

• PessimisticLockScope.NORMAL
• Locking.FollowOn.ALLOW

LockOptions

public LockOptions(LockMode lockMode,
 Timeout timeout,
 PessimisticLockScope jpaScope)

Deprecated, for removal: This API element is subject to removal in a future version.

Construct an instance with the given mode, timeout, and scope.

Parameters:

lockMode - The initial lock mode

timeout - The initial timeout

jpaScope - The initial lock scope

See Also:

• Locking.FollowOn.ALLOW

LockOptions

protected LockOptions(boolean immutable,
 LockMode lockMode)

Deprecated, for removal: This API element is subject to removal in a future version.

Internal operation used to create immutable global instances.

See Also:

• Timeouts.WAIT_FOREVER
• PessimisticLockScope.NORMAL
• Locking.FollowOn.ALLOW

LockOptions

public LockOptions(LockMode lockMode,
 int timeout,
 PessimisticLockScope scope,
 Locking.FollowOn followOnStrategy)

Deprecated, for removal: This API element is subject to removal in a future version.

LockOptions

@Deprecated(since="7.0")
public LockOptions(LockMode lockMode,
 int timeout)

Deprecated.

Use LockOptions(LockMode, Timeout) instead

Construct an instance with the given mode and timeout.

Parameters:

lockMode - The initial lock mode

timeout - The initial timeout, in milliseconds

LockOptions

@Deprecated(since="7.0")
public LockOptions(LockMode lockMode,
 int timeout,
 PessimisticLockScope scope)

Deprecated.

Use LockOptions(LockMode, Timeout, PessimisticLockScope) instead

Construct an instance with the given mode, timeout, and scope.

Parameters:

lockMode - The initial lock mode

timeout - The initial timeout, in milliseconds

scope - The initial lock scope

Method Details

isEmpty

public boolean isEmpty()

Deprecated, for removal: This API element is subject to removal in a future version.

Whether this LockOptions instance is "empty". Effectively, this means a LockMode of NONE

getLockMode

public LockMode getLockMode()

Deprecated, for removal: This API element is subject to removal in a future version.

Retrieve the overall lock mode in effect for this set of options.

Returns:

the overall lock mode

setLockMode

public LockOptions setLockMode(LockMode lockMode)

Deprecated, for removal: This API element is subject to removal in a future version.

Set the overall lock mode. The default is LockMode.NONE, that is, no locking at all.

Parameters:

lockMode - the new overall lock mode

Returns:

this for method chaining

getTimeout

public Timeout getTimeout()

Deprecated, for removal: This API element is subject to removal in a future version.

The timeout associated with this options, defining a maximum amount of time that the database should wait to obtain a pessimistic lock before returning an error to the client.

setTimeout

public LockOptions setTimeout(Timeout timeout)

Deprecated, for removal: This API element is subject to removal in a future version.

Set the timeout associated with this options.

Returns:

this for method chaining

See Also:

• getTimeout()

getTimeOut

public int getTimeOut()

Deprecated, for removal: This API element is subject to removal in a future version.

The timeout, in milliseconds, associated with this options.

NO_WAIT, WAIT_FOREVER, or SKIP_LOCKED represent 3 "magic" values.

Returns:

a timeout in milliseconds, NO_WAIT, WAIT_FOREVER, or SKIP_LOCKED

setTimeOut

public LockOptions setTimeOut(int timeout)

Deprecated, for removal: This API element is subject to removal in a future version.

Set the timeout, in milliseconds, associated with this options.

NO_WAIT, WAIT_FOREVER, or SKIP_LOCKED represent 3 "magic" values.

Returns:

this for method chaining

See Also:

• getTimeOut()

getScope

public PessimisticLockScope getScope()

Deprecated, for removal: This API element is subject to removal in a future version.

Associated lock scope

setScope

public LockOptions setScope(PessimisticLockScope scope)

Deprecated, for removal: This API element is subject to removal in a future version.

Set the associated lock scope

getFollowOnStrategy

public Locking.FollowOn getFollowOnStrategy()

Deprecated, for removal: This API element is subject to removal in a future version.

Whether follow-on locking is allowed or, if not, how to handle cases where Hibernate determines it would need to use follow-on locking.

See Also:

• HibernateHints.HINT_FOLLOW_ON_STRATEGY

setFollowOnStrategy

public LockOptions setFollowOnStrategy(Locking.FollowOn followOnStrategy)

Deprecated, for removal: This API element is subject to removal in a future version.

How to handle cases where Hibernate has determined it would need to use follow-on locking.

See Also:

• getFollowOnStrategy()

hasNonDefaultOptions

public boolean hasNonDefaultOptions()

Deprecated, for removal: This API element is subject to removal in a future version.

equals

public boolean equals(Object object)

Deprecated, for removal: This API element is subject to removal in a future version.

Overrides:

equals in class Object

hashCode

public int hashCode()

Deprecated, for removal: This API element is subject to removal in a future version.

Overrides:

hashCode in class Object

getLockScope

@Deprecated(since="7",
            forRemoval=true)
public PessimisticLockScope getLockScope()

Deprecated, for removal: This API element is subject to removal in a future version.

Use getScope() instead

The current lock scope:

• PessimisticLockScope.EXTENDED means the lock extends to rows of owned collections, but
• PessimisticLockScope.NORMAL means only the entity table and secondary tables are locked.

Returns:

the current PessimisticLockScope

setLockScope

@Deprecated(since="7",
            forRemoval=true)
public LockOptions setLockScope(PessimisticLockScope jpaScope)

Deprecated, for removal: This API element is subject to removal in a future version.

Use setScope(PessimisticLockScope) instead

Set the lock scope:

• PessimisticLockScope.EXTENDED means the lock extends to rows of owned collections, but
• PessimisticLockScope.NORMAL means only the entity table and secondary tables are locked.

Parameters:

jpaScope - the new PessimisticLockScope

Returns:

this for method chaining

getFollowOnLocking

@Deprecated(since="7.1")
public Boolean getFollowOnLocking()

Deprecated.

Use getFollowOnStrategy() instead.

Whether follow-on locking is allowed or, if not, how to handle cases where Hibernate determines it would need to use follow-on locking.

See Also:

• Locking.FollowOn.asLegacyValue()
• HibernateHints.HINT_FOLLOW_ON_LOCKING
• FollowOnLockingPolicy

setFollowOnLocking

@Deprecated(since="7.1")
public LockOptions setFollowOnLocking(Boolean followOnLocking)

Deprecated.

Use setFollowOnStrategy(Locking.FollowOn) instead.

Force enable or disable the use of follow-on locking, overriding the default behavior of the SQL dialect.

Parameters:

followOnLocking - The new follow-on locking setting

Returns:

this for method chaining

See Also:

• Locking.FollowOn.fromLegacyValue(Boolean)
• HibernateHints.HINT_FOLLOW_ON_LOCKING
• FollowOnLockingPolicy

getAliasSpecificLocks

@Deprecated(since="7",
            forRemoval=true)
public Set<Map.Entry<String,LockMode>> getAliasSpecificLocks()

Deprecated, for removal: This API element is subject to removal in a future version.

Alias-specific locks are no longer supported, roughly replaced with locking scope.

Set of Map.Entrys, each associating an alias with its specified alias-specific LockMode.

Returns:

an iterable with the Map.Entrys

setAliasSpecificLockMode

@Deprecated(since="7",
            forRemoval=true)
public LockOptions setAliasSpecificLockMode(String alias,
 LockMode lockMode)

Deprecated, for removal: This API element is subject to removal in a future version.

Alias-specific locks are no longer supported, roughly replaced with locking scope.

Specify the LockMode to be used for the given query alias.

Parameters:

alias - the query alias to which the lock mode applies

lockMode - the lock mode to apply to the given alias

Returns:

this for method chaining

getAliasLockCount

@Deprecated(since="7",
            forRemoval=true)
public int getAliasLockCount()

Deprecated, for removal: This API element is subject to removal in a future version.

Alias-specific locks are no longer supported, roughly replaced with locking scope.

The number of aliases that have alias-specific lock modes specified.

Returns:

the number of explicitly defined alias lock modes.

hasAliasSpecificLockModes

@Deprecated(since="7",
            forRemoval=true)
public boolean hasAliasSpecificLockModes()

Deprecated, for removal: This API element is subject to removal in a future version.

Alias-specific locks are no longer supported, roughly replaced with locking scope.

Whether this LockOptions instance defines alias-specific lock-modes

Returns:

true if this object defines alias-specific lock modes; false otherwise.

getAliasSpecificLockMode

@Deprecated(since="7",
            forRemoval=true)
public LockMode getAliasSpecificLockMode(String alias)

Deprecated, for removal: This API element is subject to removal in a future version.

Alias-specific locks are no longer supported, roughly replaced with locking scope.

Get the LockMode explicitly specified for the given alias via setAliasSpecificLockMode(String, LockMode).

Differs from getEffectiveLockMode(String) in that here we only return an explicitly specified alias-specific lock mode.

Parameters:

alias - The alias for which to locate the explicit lock mode.

Returns:

The explicit lock mode for that alias.

getAliasLockIterator

@Deprecated(since="7",
            forRemoval=true)
public Iterator<Map.Entry<String,LockMode>> getAliasLockIterator()

Deprecated, for removal: This API element is subject to removal in a future version.

Alias-specific locks are no longer supported, roughly replaced with locking scope.

Iterator over Map.Entrys, each containing an alias and its LockMode.

Returns:

an iterator over the Map.Entrys

getEffectiveLockMode

@Deprecated(since="7",
            forRemoval=true)
public LockMode getEffectiveLockMode(String alias)

Deprecated, for removal: This API element is subject to removal in a future version.

Alias-specific locks are no longer supported, roughly replaced with locking scope.

Determine the LockMode to apply to the given alias. If no mode was explicitly set, the overall mode is returned. If the overall lock mode is also null, LockMode.NONE is returned.

Differs from getAliasSpecificLockMode(String) in that here we fall back to only returning the overall lock mode.

Parameters:

alias - The alias for which to locate the effective lock mode.

Returns:

The effective lock mode.

See Also:

• getLockMode()

findGreatestLockMode

@Deprecated(since="7",
            forRemoval=true)
public LockMode findGreatestLockMode()

Deprecated, for removal: This API element is subject to removal in a future version.

Alias-specific locks are no longer supported, roughly replaced with locking scope.

Currently needed for follow-on locking.

Returns:

The greatest of all requested lock modes.

See Also:

• getLockMode()

makeCopy

@Deprecated(since="7",
            forRemoval=true)
public LockOptions makeCopy()

Deprecated, for removal: This API element is subject to removal in a future version.

LockOptions will be made into a record.

Make a copy. The new copy will be mutable even if the original wasn't.

Returns:

The copy

makeDefensiveCopy

@Deprecated(since="7",
            forRemoval=true)
public LockOptions makeDefensiveCopy()

Deprecated, for removal: This API element is subject to removal in a future version.

LockOptions will be made into a record.

Make a copy, unless this is an immutable instance.

Returns:

The copy, or this if it was immutable.

overlay

@Deprecated(since="7",
            forRemoval=true)
public void overlay(LockOptions lockOptions)

Deprecated, for removal: This API element is subject to removal in a future version.

LockOptions will be made into a record.

Copy the given lock options into this instance, merging the alias-specific lock modes.

copy

@Deprecated(since="7",
            forRemoval=true)
public static LockOptions copy(LockOptions source,
 LockOptions destination)

Deprecated, for removal: This API element is subject to removal in a future version.

LockOptions will be made into a record.

Copy the options in the first given instance of LockOptions to the second given instance.

Parameters:

source - Source for the copy (copied from)

destination - Destination for the copy (copied to)

Returns:

destination