Class LockOptions
- All Implemented Interfaces:
FindOption
,RefreshOption
,Serializable
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:
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final int
Indicates that the database should not wait at all to acquire a pessimistic lock which is not immediately available.static final LockOptions
RepresentsLockMode.NONE
, to which timeout and scope are not applicable.static final LockOptions
RepresentsLockMode.READ
, to which timeout and scope are not applicable.static final int
Deprecated.static final LockOptions
RepresentsLockMode.PESSIMISTIC_WRITE
with no timeout, and no extension of the lock to owned collections.static final int
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
ConstructorsConstructorDescriptionConstruct an instance with modeLockMode.NONE
and timeoutWAIT_FOREVER
.LockOptions
(LockMode lockMode) Construct an instance with the given mode andWAIT_FOREVER
.LockOptions
(LockMode lockMode, int timeout) Construct an instance with the given mode and timeout.LockOptions
(LockMode lockMode, int timeout, PessimisticLockScope scope) -
Method Summary
Modifier and TypeMethodDescriptionstatic LockOptions
copy
(LockOptions source, LockOptions destination) Copy the options in the first given instance ofLockOptions
to the second given instance.boolean
Currently needed for follow-on locking.int
The number of aliases that have alias-specific lock modes specified.Deprecated.getAliasSpecificLockMode
(String alias) Get theLockMode
explicitly specified for the given alias viasetAliasSpecificLockMode(String, LockMode)
.getEffectiveLockMode
(String alias) Determine theLockMode
to apply to the given alias.Returns a value indicating if follow-on locking was force enabled or disabled, overriding the default behavior of the SQL dialect.Retrieve the overall lock mode in effect for this set of options.The current lock scope:PessimisticLockScope.EXTENDED
means the lock extends to rows of owned collections, butPessimisticLockScope.NORMAL
means only the entity table and secondary tables are locked.int
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
Does thisLockOptions
instance define alias-specific lock modes?int
hashCode()
boolean
isEmpty()
Determine of the lock options are empty.makeCopy()
Make a copy.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.setAliasSpecificLockMode
(String alias, LockMode lockMode) Specify theLockMode
to be used for the given query alias.setFollowOnLocking
(Boolean followOnLocking) Force enable or disable the use of follow-on locking, overriding the default behavior of the SQL dialect.setLockMode
(LockMode lockMode) Set the overall lock mode.setLockScope
(PessimisticLockScope scope) Set the lock scope:PessimisticLockScope.EXTENDED
means the lock extends to rows of owned collections, butPessimisticLockScope.NORMAL
means only the entity table and secondary tables are locked.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.
-
Field Details
-
NONE
RepresentsLockMode.NONE
, to which timeout and scope are not applicable. -
READ
RepresentsLockMode.READ
, to which timeout and scope are not applicable. -
UPGRADE
RepresentsLockMode.PESSIMISTIC_WRITE
with no timeout, and no extension of the lock to owned collections. -
NO_WAIT
public static final int NO_WAITIndicates that the database should not wait at all to acquire a pessimistic lock which is not immediately available. This has the same effect asLockMode.UPGRADE_NOWAIT
.- See Also:
-
WAIT_FOREVER
public static final int WAIT_FOREVERIndicates 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:
-
SKIP_LOCKED
Deprecated.Indicates that rows which are already locked should be skipped.- See Also:
-
-
Constructor Details
-
LockOptions
public LockOptions()Construct an instance with modeLockMode.NONE
and timeoutWAIT_FOREVER
. -
LockOptions
Construct an instance with the given mode andWAIT_FOREVER
.- Parameters:
lockMode
- The initial lock mode
-
LockOptions
Construct an instance with the given mode and timeout.- Parameters:
lockMode
- The initial lock modetimeout
- The initial timeout
-
LockOptions
- Parameters:
lockMode
- The initial lock modetimeout
- The initial timeoutscope
- The initial lock scope
-
-
Method Details
-
isEmpty
public boolean isEmpty()Determine of the lock options are empty.- Returns:
true
if the lock options are equivalent toNONE
.
-
getLockMode
Retrieve the overall lock mode in effect for this set of options.- Returns:
- the overall lock mode
-
setLockMode
Set the overall lock mode. The default isLockMode.NONE
, that is, no locking at all.- Parameters:
lockMode
- the new overall lock mode- Returns:
this
for method chaining
-
setAliasSpecificLockMode
Specify theLockMode
to be used for the given query alias.- Parameters:
alias
- the query alias to which the lock mode applieslockMode
- the lock mode to apply to the given alias- Returns:
this
for method chaining- See Also:
-
getAliasSpecificLockMode
Get theLockMode
explicitly specified for the given alias viasetAliasSpecificLockMode(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
Determine theLockMode
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 alsonull
,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 thisLockOptions
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.- Returns:
- an iterator over the
Map.Entry
s
-
getAliasSpecificLocks
- Returns:
- an iterable with the
Map.Entry
s
-
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
, orSKIP_LOCKED
represent 3 "magic" values.- Returns:
- a timeout in milliseconds,
NO_WAIT
,WAIT_FOREVER
, orSKIP_LOCKED
-
setTimeOut
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
, orSKIP_LOCKED
represent 3 "magic" values.- Parameters:
timeout
- the new timeout setting, in milliseconds- Returns:
this
for method chaining- See Also:
-
getLockScope
The current lock scope:PessimisticLockScope.EXTENDED
means the lock extends to rows of owned collections, butPessimisticLockScope.NORMAL
means only the entity table and secondary tables are locked.
- Returns:
- the current
PessimisticLockScope
-
setLockScope
Set the lock scope:PessimisticLockScope.EXTENDED
means the lock extends to rows of owned collections, butPessimisticLockScope.NORMAL
means only the entity table and secondary tables are locked.
- Parameters:
scope
- the newPessimisticLockScope
- Returns:
this
for method chaining
-
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, ornull
if the default behavior of the dialect has not been overridden.- See Also:
-
setFollowOnLocking
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:
-
makeCopy
Make a copy. The new copy will be mutable even if the original wasn't.- Returns:
- The copy
-
makeDefensiveCopy
Make a copy, unless this is an immutable instance.- Returns:
- The copy, or this if it was immutable.
-
overlay
Copy the given lock options into this instance, merging the alias-specific lock modes. -
copy
Copy the options in the first given instance ofLockOptions
to the second given instance.- Parameters:
source
- Source for the copy (copied from)destination
- Destination for the copy (copied to)- Returns:
- destination
-
equals
-
hashCode
public int hashCode()
-
LockMode.UPGRADE_SKIPLOCKED