Package org.hibernate

Class LockOptions

java.lang.Object

org.hibernate.LockOptions

All Implemented Interfaces:

Serializable

public class LockOptions
extends Object
implements Serializable

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 by passing a non-null argument to setFollowOnLocking(Boolean).

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field	Description
static int	NO_WAIT	Indicates that the database should not wait at all to acquire a pessimistic lock which is not immediately available.
static LockOptions	NONE	Represents LockMode.NONE, to which timeout and scope are not applicable.
static LockOptions	READ	Represents LockMode.READ, to which timeout and scope are not applicable.
static int	SKIP_LOCKED	Deprecated. use LockMode.UPGRADE_SKIPLOCKED
static LockOptions	UPGRADE	Represents LockMode.PESSIMISTIC_WRITE with no timeout, and no extension of the lock to owned collections.
static int	WAIT_FOREVER	Indicates that there is no timeout for the lock acquisition, that is, that the database should in principle wait forever to obtain the lock.

Constructor Summary

Constructors

Constructor	Description
LockOptions()	Construct an instance with mode LockMode.NONE and timeout WAIT_FOREVER.
LockOptions(LockMode lockMode)	Construct an instance with the given mode and WAIT_FOREVER.
LockOptions(LockMode lockMode, int timeout)	Construct an instance with the given mode and timeout.
LockOptions(LockMode lockMode, int timeout, PessimisticLockScope scope)	Construct an instance with the given mode, timeout, and scope.

Method Summary

Modifier and Type	Method	Description
static LockOptions	copy(LockOptions source, LockOptions destination)	Copy the options in the first given instance of LockOptions to the second given instance.
boolean	equals(Object object)
LockMode	findGreatestLockMode()	Currently needed for follow-on locking.
int	getAliasLockCount()	The number of aliases that have alias-specific lock modes specified.
Iterator<Map.Entry<String,LockMode>>	getAliasLockIterator()	Deprecated. use getAliasSpecificLocks()
LockMode	getAliasSpecificLockMode(String alias)	Get the LockMode explicitly specified for the given alias via setAliasSpecificLockMode(String, LockMode).
Set<Map.Entry<String,LockMode>>	getAliasSpecificLocks()	Set of Map.Entrys, each associating an alias with its specified alias-specific LockMode.
LockMode	getEffectiveLockMode(String alias)	Determine the LockMode to apply to the given alias.
Boolean	getFollowOnLocking()	Returns a value indicating if follow-on locking was force enabled or disabled, overriding the default behavior of the SQL dialect.
LockMode	getLockMode()	Retrieve the overall lock mode in effect for this set of options.
PessimisticLockScope	getLockScope()	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.
boolean	getScope()	Deprecated. use getLockScope()
int	getTimeOut()	The current timeout, a maximum amount of time in milliseconds that the database should wait to obtain a pessimistic lock before returning an error to the client.
boolean	hasAliasSpecificLockModes()	Does this LockOptions instance define alias-specific lock modes?
int	hashCode()
boolean	isEmpty()	Determine of the lock options are empty.
LockOptions	makeCopy()	Make a copy.
LockOptions	makeDefensiveCopy()	Make a copy, unless this is an immutable instance.
void	overlay(LockOptions lockOptions)	Copy the given lock options into this instance, merging the alias-specific lock modes.
LockOptions	setAliasSpecificLockMode(String alias, LockMode lockMode)	Specify the LockMode to be used for the given query alias.
LockOptions	setFollowOnLocking(Boolean followOnLocking)	Force enable or disable the use of follow-on locking, overriding the default behavior of the SQL dialect.
LockOptions	setLockMode(LockMode lockMode)	Set the overall lock mode.
LockOptions	setLockScope(PessimisticLockScope scope)	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.
LockOptions	setScope(boolean scope)	Deprecated. use setLockScope(PessimisticLockScope)
LockOptions	setTimeOut(int timeout)	Set the timeout, that is, the maximum amount of time in milliseconds that the database should wait to obtain a pessimistic lock before returning an error to the client.

Methods inherited from class java.lang.Object

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

Field Detail

NONE

public static final LockOptions NONE

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

READ

public static final LockOptions READ

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

UPGRADE

public static final LockOptions UPGRADE

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

NO_WAIT

public static final int NO_WAIT

Indicates that the database should not wait at all to acquire a pessimistic lock which is not immediately available. This has the same effect as LockMode.UPGRADE_NOWAIT.

See Also:

getTimeOut(), Constant Field Values

WAIT_FOREVER

public static final int WAIT_FOREVER

Indicates that there is no timeout for the lock acquisition, that is, that the database should in principle wait forever to obtain the lock.

See Also:

getTimeOut(), Constant Field Values

SKIP_LOCKED

@Deprecated
public static final int SKIP_LOCKED

Deprecated.

use LockMode.UPGRADE_SKIPLOCKED

Indicates that rows which are already locked should be skipped.

See Also:

getTimeOut(), Constant Field Values

Constructor Detail

LockOptions

public LockOptions()

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

LockOptions

public LockOptions(LockMode lockMode)

Construct an instance with the given mode and WAIT_FOREVER.

Parameters:

lockMode - The initial lock mode

LockOptions

public LockOptions(LockMode lockMode,
                   int timeout)

Construct an instance with the given mode and timeout.

Parameters:

lockMode - The initial lock mode

timeout - The initial timeout

LockOptions

public LockOptions(LockMode lockMode,
                   int timeout,
                   PessimisticLockScope scope)

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

Parameters:

lockMode - The initial lock mode

timeout - The initial timeout

scope - The initial lock scope

Method Detail

isEmpty

public boolean isEmpty()

Determine of the lock options are empty.

Returns:

true if the lock options are equivalent to NONE.

getLockMode

public LockMode getLockMode()

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

Returns:

the overall lock mode

setLockMode

public LockOptions setLockMode(LockMode lockMode)

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

setAliasSpecificLockMode

public LockOptions setAliasSpecificLockMode(String alias,
                                            LockMode lockMode)

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

See Also:

Query.setLockMode(String, LockMode)

getAliasSpecificLockMode

public LockMode getAliasSpecificLockMode(String alias)

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.

getEffectiveLockMode

public LockMode getEffectiveLockMode(String alias)

Determine the LockMode to apply to the given alias. If no mode was setAliasSpecificLockMode(String, LockMode) explicitly set}, the getLockMode() 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.

hasAliasSpecificLockModes

public boolean hasAliasSpecificLockModes()

Does this LockOptions instance define alias-specific lock modes?

Returns:

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

getAliasLockCount

public int getAliasLockCount()

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

Returns:

the number of explicitly defined alias lock modes.

getAliasLockIterator

@Deprecated
public Iterator<Map.Entry<String,LockMode>> getAliasLockIterator()

Deprecated.

use getAliasSpecificLocks()

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

Returns:

an iterator over the Map.Entrys

getAliasSpecificLocks

public Set<Map.Entry<String,LockMode>> getAliasSpecificLocks()

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

Returns:

an iterable with the Map.Entrys

findGreatestLockMode

public LockMode findGreatestLockMode()

Currently needed for follow-on locking.

Returns:

The greatest of all requested lock modes.

getTimeOut

public int getTimeOut()

The current timeout, a maximum amount of time in milliseconds that the database should wait to obtain a pessimistic lock before returning an error to the client.

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)

Set the timeout, that is, the maximum amount of time in milliseconds that the database should wait to obtain a pessimistic lock before returning an error to the client.

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

Parameters:

timeout - the new timeout setting, in milliseconds

Returns:

this for method chaining

See Also:

getTimeOut()

getLockScope

public PessimisticLockScope getLockScope()

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

public LockOptions setLockScope(PessimisticLockScope scope)

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:

scope - the new PessimisticLockScope

Returns:

this for method chaining

getScope

@Deprecated(since="6.2")
public boolean getScope()

Deprecated.

use getLockScope()

The current lock scope setting:

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

Returns:

true if the lock extends to owned associations

setScope

@Deprecated(since="6.2")
public LockOptions setScope(boolean scope)

Deprecated.

use setLockScope(PessimisticLockScope)

Set the lock scope setting:

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

Parameters:

scope - the new scope setting

Returns:

this for method chaining

getFollowOnLocking

public Boolean getFollowOnLocking()

Returns a value indicating if follow-on locking was force enabled or disabled, overriding the default behavior of the SQL dialect.

Returns:

true if follow-on locking was force enabled, false if follow-on locking was force disabled, or null if the default behavior of the dialect has not been overridden.

See Also:

HibernateHints.HINT_FOLLOW_ON_LOCKING, Dialect.useFollowOnLocking(String, QueryOptions)

setFollowOnLocking

public LockOptions setFollowOnLocking(Boolean followOnLocking)

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:

HibernateHints.HINT_FOLLOW_ON_LOCKING, Dialect.useFollowOnLocking(String, QueryOptions)

makeCopy

public LockOptions makeCopy()

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

Returns:

The copy

makeDefensiveCopy

public LockOptions makeDefensiveCopy()

Make a copy, unless this is an immutable instance.

Returns:

The copy, or this if it was immutable.

overlay

public void overlay(LockOptions lockOptions)

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

copy

public static LockOptions copy(LockOptions source,
                               LockOptions destination)

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

equals

public boolean equals(Object object)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object