org.apache.geode.distributed

## Class DistributedLockService

- java.lang.Object
- - org.apache.geode.distributed.DistributedLockService

-     public abstract class DistributedLockService
      extends java.lang.Object

  A named instance of DistributedLockService defines a space for locking arbitrary names across the distributed system defined by a specified distribution manager. Any number of DistributedLockService instances can be created with different service names. For all processes in the distributed system that have created an instance of DistributedLockService with the same name, no more than one thread is permitted to own the lock on a given name in that instance at any point in time. Additionally, a thread can lock the entire service, preventing any other threads in the system from locking the service or any names in the service.

- - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `DistributedLockService()` Public instance creation is prohibited - use `create(String, DistributedSystem)`

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `abstract void` | `becomeLockGrantor()` Specifies this member to become the grantor for this lock service.
    `static void` | `becomeLockGrantor(java.lang.String serviceName)` Specifies that this member should become the grantor for the named locking service.
    `static DistributedLockService` | `create(java.lang.String serviceName, DistributedSystem ds)` Create a DistributedLockService with the given serviceName for the given DistributedSystem.
    `static void` | `destroy(java.lang.String serviceName)` Destroy a previously created DistributedLockService with the given `serviceName`.
    `abstract void` | `freeResources(java.lang.Object name)` Free internal resources associated with the given `name`.
    `static DistributedLockService` | `getServiceNamed(java.lang.String serviceName)` Look up and return the DistributedLockService with the given name, if it has been created in this VM.
    `abstract boolean` | `isHeldByCurrentThread(java.lang.Object name)` Determine whether the current thread owns the lock on the given object.
    `abstract boolean` | `isLockGrantor()` Returns true if this member is currently the lock authority responsible for granting locks for this service.
    `static boolean` | `isLockGrantor(java.lang.String serviceName)` Returns true if this member is the grantor for the named service.
    `abstract boolean` | `isLockingSuspendedByCurrentThread()` Determine whether the current thread has suspended locking in this DistributedLockService.
    `abstract boolean` | `lock(java.lang.Object name, long waitTimeMillis, long leaseTimeMillis)` Attempts to acquire a lock named `name`.
    `abstract boolean` | `lockInterruptibly(java.lang.Object name, long waitTimeMillis, long leaseTimeMillis)` Deprecated. as of GemFire 5.1, use `lock(Object, long, long)` with waitTimeMillis instead
    `abstract void` | `resumeLocking()` Allow locking to resume in this DistributedLockService instance.
    `abstract boolean` | `suspendLocking(long waitTimeMillis)` Suspend granting of locks in this service.
    `abstract boolean` | `suspendLockingInterruptibly(long waitTimeMillis)` Deprecated. as of GemFire 5.1, use `suspendLocking(long)` with waitTimeMillis instead
    `abstract void` | `unlock(java.lang.Object name)` Release the lock previously granted for the given `name`.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### DistributedLockService

          protected DistributedLockService()

      Public instance creation is prohibited - use `create(String, DistributedSystem)`

  - ### Method Detail

    - #### create

          public static DistributedLockService create(java.lang.String serviceName,
                                                      DistributedSystem ds)
                                               throws java.lang.IllegalArgumentException

      Create a DistributedLockService with the given serviceName for the given DistributedSystem. This DistributedLockService will continue to manage locks until ``destroy(java.lang.String)`` is called, or `ds` is disconnected, at which point any locks that were held by this instance are released.
      Parameters:
        `serviceName` - the name of the DistributedLockService to create.
        `ds` - the `DistributedSystem` for the new service instance to use for distributed lock messaging.
      Throws:
        `java.lang.IllegalArgumentException` - if serviceName is an illegal name or this process has already created a DistributedLockService with the given `serviceName`.
        `java.lang.IllegalStateException` - if this process is in the middle of disconnecting from the `DistributedSystem`

    - #### getServiceNamed

          public static DistributedLockService getServiceNamed(java.lang.String serviceName)

      Look up and return the DistributedLockService with the given name, if it has been created in this VM. If it has not been created, return null.
      Parameters:
        `serviceName` - the name of the DistributedLockService to look up
      Returns:
        the DistributedLockService with the given name, or null if it hasn't been created in this VM.

    - #### destroy

          public static void destroy(java.lang.String serviceName)
                              throws java.lang.IllegalArgumentException

      Destroy a previously created DistributedLockService with the given `serviceName`. Any locks currently held in this DistributedLockService by this process are released. Attempts to access a destroyed lock service will result in a `LockServiceDestroyedException` being thrown.
      Parameters:
        `serviceName` - the name of the instance to destroy, previously supplied in the `create(String, DistributedSystem)` invocation.
      Throws:
        `java.lang.IllegalArgumentException` - if this process hasn't created a DistributedLockService with the given `serviceName` and `dm`.

    - #### lock

          public abstract boolean lock(java.lang.Object name,
                                       long waitTimeMillis,
                                       long leaseTimeMillis)

      Attempts to acquire a lock named `name`. Returns `true` as soon as the lock is acquired. If the lock is currently held by another thread in this or any other process in the distributed system, or another thread in the system has locked the entire service, this method keeps trying to acquire the lock for up to `waitTimeMillis` before giving up and returning `false`. If the lock is acquired, it is held until `unlock(Object name)` is invoked, or until `leaseTimeMillis` milliseconds have passed since the lock was granted - whichever comes first.

      Locks are reentrant. If a thread invokes this method n times on the same instance, specifying the same `name`, without an intervening release or lease expiration expiration on the lock, the thread must invoke `unlock(name)` the same number of times before the lock is released (unless the lease expires). When this method is invoked for a lock that is already acquired, the lease time will be set to the maximum of the remaining least time from the previous invocation, or `leaseTimeMillis`

      Parameters:
        `name` - the name of the lock to acquire in this service. This object must conform to the general contract of `equals(Object)` and `hashCode()` as described in `Object.hashCode()`.
        `waitTimeMillis` - the number of milliseconds to try to acquire the lock before giving up and returning false. A value of -1 causes this method to block until the lock is acquired. A value of 0 causes this method to return false without waiting for the lock if the lock is held by another member or thread.
        `leaseTimeMillis` - the number of milliseconds to hold the lock after granting it, before automatically releasing it if it hasn't already been released by invoking `unlock(Object)`. If `leaseTimeMillis` is -1, hold the lock until explicitly unlocked.
      Returns:
        true if the lock was acquired, false if the timeout `waitTimeMillis` passed without acquiring the lock.
      Throws:
        `LockServiceDestroyedException` - if this lock service has been destroyed

    - #### lockInterruptibly

          @Deprecated
          public abstract boolean lockInterruptibly(java.lang.Object name,
                                                                long waitTimeMillis,
                                                                long leaseTimeMillis)
                                                         throws java.lang.InterruptedException

      Deprecated. as of GemFire 5.1, use `lock(Object, long, long)` with waitTimeMillis instead

      Attempts to acquire a lock named `name`. Returns `true` as soon as the lock is acquired. If the lock is currently held by another thread in this or any other process in the distributed system, or another thread in the system has locked the entire service, this method keeps trying to acquire the lock for up to `waitTimeMillis` before giving up and returning `false`. If the lock is acquired, it is held until `unlock(Object name)` is invoked, or until `leaseTimeMillis` milliseconds have passed since the lock was granted - whichever comes first.

      Locks are reentrant. If a thread invokes this method n times on the same instance, specifying the same `name`, without an intervening release or lease expiration expiration on the lock, the thread must invoke `unlock(name)` the same number of times before the lock is released (unless the lease expires). When this method is invoked for a lock that is already acquired, the lease time will be set to the maximum of the remaining least time from the previous invocation, or `leaseTimeMillis`

      Parameters:
        `name` - the name of the lock to acquire in this service. This object must conform to the general contract of `equals(Object)` and `hashCode()` as described in `Object.hashCode()`.
        `waitTimeMillis` - the number of milliseconds to try to acquire the lock before giving up and returning false. A value of -1 causes this method to block until the lock is acquired.
        `leaseTimeMillis` - the number of milliseconds to hold the lock after granting it, before automatically releasing it if it hasn't already been released by invoking `unlock(Object)`. If `leaseTimeMillis` is -1, hold the lock until explicitly unlocked.
      Returns:
        true if the lock was acquired, false if the timeout `waitTimeMillis` passed without acquiring the lock.
      Throws:
        `java.lang.InterruptedException` - if the thread is interrupted before or during this method.
        `LockServiceDestroyedException` - if this lock service has been destroyed

    - #### unlock

          public abstract void unlock(java.lang.Object name)
                               throws LeaseExpiredException

      Release the lock previously granted for the given `name`.
      Parameters:
        `name` - the object to unlock in this service.
      Throws:
        `LockNotHeldException` - if the current thread is not the owner of this lock
        `LeaseExpiredException` - if the current thread was the owner of this lock, but it's lease has expired.
        `LockServiceDestroyedException` - if the service has been destroyed

    - #### isHeldByCurrentThread

          public abstract boolean isHeldByCurrentThread(java.lang.Object name)

      Determine whether the current thread owns the lock on the given object.
      Returns:
        true if the current thread owns the lock for `name`.
      Throws:
        `LockServiceDestroyedException` - if this service has been destroyed

    - #### suspendLockingInterruptibly

          @Deprecated
          public abstract boolean suspendLockingInterruptibly(long waitTimeMillis)
                                                                   throws java.lang.InterruptedException

      Deprecated. as of GemFire 5.1, use `suspendLocking(long)` with waitTimeMillis instead
      Suspend granting of locks in this service. When locking has been suspended, no other thread in the distributed system will be granted a lock for any new or existing name in that service until locking is resumed by the thread that suspended it. Only one thread at a time in a distributed system is permitted suspend locking on a given DistributedLockService instance. This method blocks until lock suspension can be granted to the current thread, and all outstanding locks on names in this service held by other threads in the distributed system have been released, or until `waitTimeMillis` milliseconds have passed without successfully granting suspension.
      Parameters:
        `waitTimeMillis` - the number of milliseconds to try to acquire suspension before giving up and returning false. A value of -1 causes this method to block until suspension is granted.
      Returns:
        true if suspension was granted, false if the timeout `waitTimeMillis` passed before it could be granted.
      Throws:
        `java.lang.IllegalStateException` - if the current thread already has suspended locking on this instance.
        `java.lang.InterruptedException` - if the current thread is interrupted.
        `LockServiceDestroyedException` - if the service has been destroyed

    - #### suspendLocking

          public abstract boolean suspendLocking(long waitTimeMillis)

      Suspend granting of locks in this service. When locking has been suspended, no other thread in the distributed system will be granted a lock for any new or existing name in that service until locking is resumed by the thread that suspended it. Only one thread at a time in a distributed system is permitted suspend locking on a given DistributedLockService instance. This method blocks until lock suspension can be granted to the current thread, and all outstanding locks on names in this service held by other threads in the distributed system have been released, or until `waitTimeMillis` milliseconds have passed without successfully granting suspension.
      Parameters:
        `waitTimeMillis` - the number of milliseconds to try to acquire suspension before giving up and returning false. A value of -1 causes this method to block until suspension is granted. A value of 0 causes this method to return false without waiting for the lock if the lock is held by another member or thread.
      Returns:
        true if suspension was granted, false if the timeout `waitTimeMillis` passed before it could be granted.
      Throws:
        `java.lang.IllegalStateException` - if the current thread already has suspended locking on this instance
        `LockServiceDestroyedException` - if the service has been destroyed

    - #### resumeLocking

          public abstract void resumeLocking()

      Allow locking to resume in this DistributedLockService instance.
      Throws:
        `java.lang.IllegalStateException` - if the current thread didn't previously suspend locking
        `LockServiceDestroyedException` - if the service has been destroyed

    - #### isLockingSuspendedByCurrentThread

          public abstract boolean isLockingSuspendedByCurrentThread()

      Determine whether the current thread has suspended locking in this DistributedLockService.
      Returns:
        true if locking is suspended by the current thread.
      Throws:
        `LockServiceDestroyedException` - if this service has been destroyed

    - #### freeResources

          public abstract void freeResources(java.lang.Object name)

      Free internal resources associated with the given `name`. This may reduce this VM's memory use, but may also prohibit performance optimizations if `name` is subsequently locked in this VM.
      Throws:
        `LockServiceDestroyedException` - if this service has been destroyed

    - #### becomeLockGrantor

          public abstract void becomeLockGrantor()

      Specifies this member to become the grantor for this lock service. The grantor will be the lock authority which is responsible for handling all lock requests for this service. Other members will request locks from this member. Locking for this member is optimized as it will not require messaging to acquire a given lock.

      Calls to this method will block until grantor authority has been transferred to this member.

      If another member calls `becomeLockGrantor` after this member, that member will transfer grantor authority from this member to itself.

      This operation should not be invoked repeatedly in an application. It is possible to create a lock service and have two or more members endlessly calling becomeLockGrantor to transfer grantorship back and forth.

      Throws:
        `LockServiceDestroyedException` - if this service has been destroyed

    - #### becomeLockGrantor

          public static void becomeLockGrantor(java.lang.String serviceName)
                                        throws java.lang.IllegalArgumentException

      Specifies that this member should become the grantor for the named locking service.
      Parameters:
        `serviceName` - the name of the locking service
      Throws:
        `java.lang.IllegalArgumentException` - if `serviceName`does not refer to any registered locking service in this process``
      See Also:
        `becomeLockGrantor()`

    - #### isLockGrantor

          public abstract boolean isLockGrantor()

      Returns true if this member is currently the lock authority responsible for granting locks for this service. This can be explicitly requested by calling `becomeLockGrantor()`. If no member has explicitly requested grantor authority, then one member participating in the service will be implicitly selected. In either case, this method returns true if the calling member is the grantor.
      Returns:
        true if this member is the grantor for this service
      Throws:
        `LockServiceDestroyedException` - if lock service has been destroyed

    - #### isLockGrantor

          public static boolean isLockGrantor(java.lang.String serviceName)
                                       throws java.lang.IllegalArgumentException

      Returns true if this member is the grantor for the named service.
      Parameters:
        `serviceName` - the name of the locking service
      Returns:
        true if this member is the grantor for this service
      Throws:
        `java.lang.IllegalArgumentException` - if `serviceName`does not refer to any registered locking service in this process``
      See Also:
        `isLockGrantor()`