Package org.hibernate

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:

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:

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

    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, 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 scope)
    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.
    Copy the options in the first given instance of LockOptions to the second given instance.
    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.
    Currently needed for follow-on locking.
    int
    getAliasLockCount()
    Deprecated, for removal: This API element is subject to removal in a future version.
    The number of aliases that have alias-specific lock modes specified.
    Iterator<Map.Entry<String,LockMode>>
    getAliasLockIterator()
    Deprecated.
    use getAliasSpecificLocks()
    LockMode
    getAliasSpecificLockMode(String alias)
    Deprecated, for removal: This API element is subject to removal in a future version.
    Get the LockMode explicitly specified for the given alias via setAliasSpecificLockMode(String, LockMode).
    Set<Map.Entry<String,LockMode>>
    getAliasSpecificLocks()
    Deprecated, for removal: This API element is subject to removal in a future version.
    Set of Map.Entrys, each associating an alias with its specified alias-specific LockMode.
    LockMode
    getEffectiveLockMode(String alias)
    Deprecated, for removal: This API element is subject to removal in a future version.
    Determine the LockMode to apply to the given alias.
    Boolean
    getFollowOnLocking()
    Deprecated, for removal: This API element is subject to removal in a future version.
    Returns a value indicating if follow-on locking was force enabled or disabled, overriding the default behavior of the SQL dialect.
    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.
    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.
    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.
    Whether this LockOptions instance defines alias-specific lock-modes
    int
    hashCode()
    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", meaning it has any non-default values set (which is the same as
    LockOptions
    makeCopy()
    Deprecated, for removal: This API element is subject to removal in a future version.
    Make a copy.
    LockOptions
    makeDefensiveCopy()
    Deprecated, for removal: This API element is subject to removal in a future version.
    Make a copy, unless this is an immutable instance.
    void
    overlay(LockOptions lockOptions)
    Deprecated, for removal: This API element is subject to removal in a future version.
    Copy the given lock options into this instance, merging the alias-specific lock modes.
    LockOptions
    setAliasSpecificLockMode(String alias, LockMode lockMode)
    Deprecated, for removal: This API element is subject to removal in a future version.
    Specify the LockMode to be used for the given query alias.
    LockOptions
    setFollowOnLocking(Boolean followOnLocking)
    Deprecated, for removal: This API element is subject to removal in a future version.
    Force enable or disable the use of follow-on locking, overriding the default behavior of the SQL dialect.
    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 scope)
    Deprecated, for removal: This API element is subject to removal in a future version.
    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
    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 java.lang.Object

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

  • Field Details

  • 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:

    • 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:

    • 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

    • LockOptions

      public LockOptions(LockMode lockMode, Timeout timeout, PessimisticLockScope scope)
      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
      scope - The initial lock scope

    • 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.

    • 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", meaning it has any non-default values set (which is the same as
      Returns:
      true if the lock options are equivalent to 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

      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:

    • getLockScope

      public PessimisticLockScope getLockScope()
      Deprecated, for removal: This API element is subject to removal in a future version.
      The current lock scope:
      Returns:
      the current PessimisticLockScope

    • setLockScope

      public LockOptions setLockScope(PessimisticLockScope scope)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Set the lock scope:
      Parameters:
      scope - the new PessimisticLockScope
      Returns:
      this for method chaining

    • getFollowOnLocking

      public Boolean getFollowOnLocking()
      Deprecated, for removal: This API element is subject to removal in a future version.
      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:

    • setFollowOnLocking

      public LockOptions setFollowOnLocking(Boolean followOnLocking)
      Deprecated, for removal: This API element is subject to removal in a future version.
      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

      public LockOptions makeCopy()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Make a copy. The new copy will be mutable even if the original wasn't.
      Returns:
      The copy

    • makeDefensiveCopy

      public LockOptions makeDefensiveCopy()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Make a copy, unless this is an immutable instance.
      Returns:
      The copy, or this if it was immutable.

    • overlay

      public void overlay(LockOptions lockOptions)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Copy the given lock options into this instance, merging the alias-specific lock modes.

    • copy

      public static LockOptions copy(LockOptions source, LockOptions destination)
      Deprecated, for removal: This API element is subject to removal in a future version.
      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)
      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

    • getAliasSpecificLocks

      @Remove public Set<Map.Entry<String,LockMode>> getAliasSpecificLocks()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Set of Map.Entrys, each associating an alias with its specified alias-specific LockMode.
      Returns:
      an iterable with the Map.Entrys
      API Note:
      This will be removed in 7.1 and replaced with an extension to JPA's PessimisticLockScope

    • setAliasSpecificLockMode

      @Remove public LockOptions setAliasSpecificLockMode(String alias, LockMode lockMode)
      Deprecated, for removal: This API element is subject to removal in a future version.
      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:
      API Note:
      This will be removed in 7.1 and replaced with an extension to JPA's PessimisticLockScope

    • getAliasLockCount

      @Remove public int getAliasLockCount()
      Deprecated, for removal: This API element is subject to removal in a future version.
      The number of aliases that have alias-specific lock modes specified.
      Returns:
      the number of explicitly defined alias lock modes.
      API Note:
      This will be removed in 7.1 and replaced with an extension to JPA's PessimisticLockScope

    • hasAliasSpecificLockModes

      @Remove public boolean hasAliasSpecificLockModes()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Whether this LockOptions instance defines alias-specific lock-modes
      Returns:
      true if this object defines alias-specific lock modes; false otherwise.
      API Note:
      This will be removed in 7.1 and replaced with an extension to JPA's PessimisticLockScope

    • getAliasSpecificLockMode

      @Remove public LockMode getAliasSpecificLockMode(String alias)
      Deprecated, for removal: This API element is subject to removal in a future version.
      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.
      API Note:
      This will be removed in 7.1 and replaced with an extension to JPA's PessimisticLockScope

    • 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

    • getEffectiveLockMode

      @Remove public LockMode getEffectiveLockMode(String alias)
      Deprecated, for removal: This API element is subject to removal in a future version.
      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.
      API Note:
      This will be removed in 7.1 and replaced with an extension to JPA's PessimisticLockScope

    • findGreatestLockMode

      @Remove public LockMode findGreatestLockMode()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Currently needed for follow-on locking.
      Returns:
      The greatest of all requested lock modes.
      API Note:
      This will be removed in 7.1 and replaced with an extension to JPA's PessimisticLockScope. See getLockMode()