com.hazelcast.core

## Interface ILock

- All Superinterfaces:
    DistributedObject, Lock
  All Known Implementing Classes:
    ClientLockProxy, LockProxy

      public interface ILock
      extends Lock, DistributedObject

  Distributed implementation of `Lock`.

  # Example

           Lock mylock = Hazelcast.getLock(mylockobject); mylock.lock();
       try {
            // do something
       } finally {
            mylock.unlock();
       }
       //Lock on Map
            IMap map = Hazelcast.getMap("customers"); map.lock("1");
       try {
            // do something
       } finally {
       map.unlock("1"); }

  Behaviour of `ILock` under split-brain scenarios should be taken into account when using this data structure. During a split, each partitioned cluster will either create a brand new and un-acquired `ILock` or it will continue to use the primary or back-up version. As the acquirer of the `ILock` might reside in a different partitioned network this can lead to situations where the lock is never obtainable.

  When the split heals, Hazelcast performs a default largest cluster wins resolution. Where the clusters are the same size a winner of the merge will be randomly chosen. In any case, this can lead to situations where (post-merge) multiple acquirers think they hold the same lock, when in fact the `ILock` itself records only one owner. When the false owners come to release the `ILock` an `IllegalMonitorStateException` is thrown.

  Acquiring an `ILock` with a lease time `lock(long, TimeUnit)` can help to mitigate such scenarios.

  As a defensive mechanism against such inconsistency, consider using the in-built split-brain protection for lock. Using this functionality it is possible to restrict operations in smaller partitioned clusters. It should be noted that there is still an inconsistency window between the time of the split and the actual detection. Therefore using this reduces the window of inconsistency but can never completely eliminate it.

  See Also:
    `Lock`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `forceUnlock()` Releases the lock regardless of the lock owner.
    `Object` | `getKey()` Deprecated. use `DistributedObject.getName()` instead.
    `int` | `getLockCount()` Returns re-entrant lock hold count, regardless of lock ownership.
    `long` | `getRemainingLeaseTime()` Returns remaining lease time in milliseconds.
    `boolean` | `isLocked()` Returns whether this lock is locked or not.
    `boolean` | `isLockedByCurrentThread()` Returns whether this lock is locked by current thread or not.
    `void` | `lock()`
    `void` | `lock(long leaseTime, TimeUnit timeUnit)` Acquires the lock for the specified lease time.
    `Condition` | `newCondition()` This method is not implemented! Use `newCondition(String)` instead.
    `ICondition` | `newCondition(String name)` Returns a new `ICondition` instance that is bound to this `ILock` instance with given name.
    `boolean` | `tryLock()`
    `boolean` | `tryLock(long time, TimeUnit unit)`
    `boolean` | `tryLock(long time, TimeUnit unit, long leaseTime, TimeUnit leaseUnit)` Tries to acquire the lock for the specified lease time.
    `void` | `unlock()` Releases the lock.

    - ### Methods inherited from interface java.util.concurrent.locks.Lock

      `lockInterruptibly`

    - ### Methods inherited from interface com.hazelcast.core.DistributedObject

      `destroy, getName, getPartitionKey, getServiceName`

- - ### Method Detail

    - #### getKey

          @Deprecated
          Object getKey()

      Deprecated. use `DistributedObject.getName()` instead.
      Returns the lock object, the key for this lock instance.
      Returns:
        lock object.

    - #### lock

          void lock()

      Specified by:
        `lock` in interface `Lock`

    - #### tryLock

          boolean tryLock()

      Specified by:
        `tryLock` in interface `Lock`

    - #### tryLock

          boolean tryLock(long time,
                          TimeUnit unit)
                   throws InterruptedException

      Specified by:
        `tryLock` in interface `Lock`
      Throws:
        `InterruptedException`

    - #### tryLock

          boolean tryLock(long time,
                          TimeUnit unit,
                          long leaseTime,
                          TimeUnit leaseUnit)
                   throws InterruptedException

      Tries to acquire the lock for the specified lease time.

      After lease time, the lock will be released.

      If the lock is not available, then the current thread becomes disabled for thread scheduling purposes and lies dormant until one of two things happens:

      - the lock is acquired by the current thread, or
      - the specified waiting time elapses.
      Parameters:
        `time` - maximum time to wait for the lock.
        `unit` - time unit of the `time` argument.
        `leaseTime` - time to wait before releasing the lock.
        `leaseUnit` - unit of time to specify lease time.
      Returns:
        `true` if the lock was acquired and `false` if the waiting time elapsed before the lock was acquired.
      Throws:
        `InterruptedException`

    - #### unlock

          void unlock()

      Releases the lock.
      Specified by:
        `unlock` in interface `Lock`

    - #### lock

          void lock(long leaseTime,
                    TimeUnit timeUnit)

      Acquires the lock for the specified lease time.

      After lease time, lock will be released..

      If the lock is not available then the current thread becomes disabled for thread scheduling purposes and lies dormant until the lock has been acquired.

      Parameters:
        `leaseTime` - time to wait before releasing the lock.
        `timeUnit` - unit of time for the lease time.
      Throws:
        `IllegalMonitorStateException` - if the current thread does not hold this lock

    - #### forceUnlock

          void forceUnlock()

      Releases the lock regardless of the lock owner. It always successfully unlocks, never blocks, and returns immediately.

    - #### newCondition

          Condition newCondition()

      This method is not implemented! Use `newCondition(String)` instead.
      Specified by:
        `newCondition` in interface `Lock`
      Throws:
        `UnsupportedOperationException` - the exception is always thrown, since this method is not implemented

    - #### newCondition

          ICondition newCondition(String name)

      Returns a new `ICondition` instance that is bound to this `ILock` instance with given name.

      Before waiting on the condition the lock must be held by the current thread. A call to `Condition.await()` will atomically release the lock before waiting and re-acquire the lock before the wait returns.

      Parameters:
        `name` - identifier of the new condition instance
      Returns:
        A new `ICondition` instance for this `ILock` instance
      Throws:
        `NullPointerException` - if name is null.

    - #### isLocked

          boolean isLocked()

      Returns whether this lock is locked or not.
      Returns:
        `true` if this lock is locked, `false` otherwise.

    - #### isLockedByCurrentThread

          boolean isLockedByCurrentThread()

      Returns whether this lock is locked by current thread or not.
      Returns:
        `true` if this lock is locked by current thread, `false` otherwise.

    - #### getLockCount

          int getLockCount()

      Returns re-entrant lock hold count, regardless of lock ownership.
      Returns:
        the lock hold count.

    - #### getRemainingLeaseTime

          long getRemainingLeaseTime()

      Returns remaining lease time in milliseconds. If the lock is not locked then -1 will be returned.
      Returns:
        remaining lease time in milliseconds.

Copyright © 2018. All rights reserved.