AbstractRaftFencedLockProxy (Hazelcast Root 3.12-BETA-2 API)

java.lang.Object
- com.hazelcast.cp.internal.session.SessionAwareProxy
- - com.hazelcast.cp.internal.datastructures.lock.proxy.AbstractRaftFencedLockProxy

All Implemented Interfaces:

DistributedObject, FencedLock, Lock

Direct Known Subclasses:

RaftFencedLockProxy
```
public abstract class AbstractRaftFencedLockProxy
extends SessionAwareProxy
implements FencedLock
```
Implements proxy methods for Raft-based FencedLock API. Lock reentrancy is implemented locally.

Field Summary

Fields
Modifier and Type Field and Description

protected String objectName

protected String proxyName
- Fields inherited from class com.hazelcast.cp.internal.session.SessionAwareProxy
  groupId
- Fields inherited from interface com.hazelcast.cp.lock.FencedLock
  INVALID_FENCE

Fields
Modifier and Type	Field and Description
`protected String`	`objectName`
`protected String`	`proxyName`

Constructor Summary

Constructors
Constructor and Description
`AbstractRaftFencedLockProxy(AbstractProxySessionManager sessionManager, RaftGroupId groupId, String proxyName, String objectName)`

Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`destroy()` Destroys this object cluster-wide.
`protected abstract InternalCompletableFuture<RaftLockOwnershipState>`	`doGetLockOwnershipState()`
`protected abstract InternalCompletableFuture<Long>`	`doLock(long sessionId, long threadId, UUID invocationUid)`
`protected abstract InternalCompletableFuture<Long>`	`doTryLock(long sessionId, long threadId, UUID invocationUid, long timeoutMillis)`
`protected abstract InternalCompletableFuture<Boolean>`	`doUnlock(long sessionId, long threadId, UUID invocationUid)`
`long`	`getFence()` Returns the fencing token if the lock is held by the current thread.
`int`	`getLockCount()` Returns the reentrant lock count if the lock is held by any thread in the cluster.
`Long`	`getLockedSessionId(long threadId)`
`String`	`getName()` Returns the unique name for this DistributedObject.
`String`	`getObjectName()`
`String`	`getPartitionKey()` Returns the key of the partition that this DistributedObject is assigned to.
`String`	`getServiceName()` Returns the service name for this object.
`boolean`	`isLocked()` Returns whether this lock is locked or not.
`boolean`	`isLockedByCurrentThread()` Returns whether the lock is held by the current thread or not.
`void`	`lock()` Acquires the lock.
`long`	`lockAndGetFence()` Acquires the lock and returns the fencing token assigned to the current thread for this lock acquire.
`void`	`lockInterruptibly()` Acquires the lock unless the current thread is interrupted.
`Condition`	`newCondition()` NOT IMPLEMENTED.
`boolean`	`tryLock()` Acquires the lock if it is available or already held by the current thread at the time of invocation & the acquire limit is not exceeded, and immediately returns with the value `true`.
`boolean`	`tryLock(long time, TimeUnit unit)` Acquires the lock if it is free within the given waiting time, or already held by the current thread.
`long`	`tryLockAndGetFence()` Acquires the lock only if it is free or already held by the current thread at the time of invocation & the acquire limit is not exceeded, and returns the fencing token assigned to the current thread for this lock acquire.
`long`	`tryLockAndGetFence(long time, TimeUnit unit)` Acquires the lock if it is free within the given waiting time, or already held by the current thread at the time of invocation & the acquire limit is not exceeded, and returns the fencing token assigned to the current thread for this lock acquire.
`void`	`unlock()` Releases the lock if the lock is currently held by the current thread.

Methods inherited from class com.hazelcast.cp.internal.session.SessionAwareProxy
acquireSession, acquireSession, getGroupId, getOrCreateUniqueThreadId, getSession, invalidateSession, releaseSession, releaseSession

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.hazelcast.cp.lock.FencedLock
getGroupId

- Field Detail
  - proxyName
```
protected final String proxyName
```
  - objectName
```
protected final String objectName
```
- Constructor Detail
  - AbstractRaftFencedLockProxy
```
public AbstractRaftFencedLockProxy(AbstractProxySessionManager sessionManager,
                                   RaftGroupId groupId,
                                   String proxyName,
                                   String objectName)
```
- Method Detail
  - doLock
```
protected abstract InternalCompletableFuture<Long> doLock(long sessionId,
                                                          long threadId,
                                                          UUID invocationUid)
```
  - doTryLock
```
protected abstract InternalCompletableFuture<Long> doTryLock(long sessionId,
                                                             long threadId,
                                                             UUID invocationUid,
                                                             long timeoutMillis)
```
  - doUnlock
```
protected abstract InternalCompletableFuture<Boolean> doUnlock(long sessionId,
                                                               long threadId,
                                                               UUID invocationUid)
```
  - doGetLockOwnershipState
```
protected abstract InternalCompletableFuture<RaftLockOwnershipState> doGetLockOwnershipState()
```
  - lock
```
public void lock()
```
    Description copied from interface: FencedLock
    Acquires the lock.
    When the caller already holds the lock and the current lock() call is reentrant, the call can fail with LockAcquireLimitExceededException if the lock acquire limit is exceeded. Please see FencedLockConfig for more information.
    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.
    Consider the following scenario:
```
     FencedLock lock = ...;
     lock.lock();
     // JVM of the caller thread hits a long pause
     // and its CP session is closed on the CP group.
     lock.lock();
 
```
    In this scenario, a thread acquires the lock, then its JVM instance encounters a long pause, which is longer than CPSubsystemConfig.getSessionTimeToLiveSeconds(). In this case, its CP session will be closed on the corresponding CP group because it could not commit session heartbeats in the meantime. After the JVM instance wakes up again, the same thread attempts to acquire the lock reentrantly. In this case, the second lock() call fails by throwing LockOwnershipLostException which extends IllegalMonitorStateException. If the caller wants to deal with its session loss by taking some custom actions, it can handle the thrown LockOwnershipLostException instance. Otherwise, it can treat it as a regular IllegalMonitorStateException.
    Specified by:
    
    lock in interface FencedLock
    
    Specified by:
    
    lock in interface Lock
  - lockInterruptibly
```
public void lockInterruptibly()
                       throws InterruptedException
```
    Description copied from interface: FencedLock
    Acquires the lock unless the current thread is interrupted.
    When the caller already holds the lock and the current lock() call is reentrant, the call can fail with LockAcquireLimitExceededException if the lock acquire limit is exceeded. Please see FencedLockConfig for more information.
    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. Interruption may not be possible after the lock request arrives to the CP group, if the proxy does not attempt to retry its lock request because of a failure in the system.
    Please note that even if InterruptedException is thrown, the lock may be acquired on the CP group.
    When InterruptedException is thrown, the current thread's interrupted status is cleared.
    Consider the following scenario:
```
     FencedLock lock = ...;
     lock.lockInterruptibly();
     // JVM of the caller thread hits a long pause
     // and its CP session is closed on the CP group.
     lock.lockInterruptibly();
 
```
    In this scenario, a thread acquires the lock, then its JVM instance encounters a long pause, which is longer than CPSubsystemConfig.getSessionTimeToLiveSeconds(). In this case, its CP session will be closed on the corresponding CP group because it could not commit session heartbeats in the meantime. After the JVM instance wakes up again, the same thread attempts to acquire the lock reentrantly. In this case, the second lock() call fails by throwing LockOwnershipLostException which extends IllegalMonitorStateException. If the caller wants to deal with its session loss by taking some custom actions, it can handle the thrown LockOwnershipLostException instance. Otherwise, it can treat it as a regular IllegalMonitorStateException.
    Specified by:
    
    lockInterruptibly in interface FencedLock
    
    Specified by:
    
    lockInterruptibly in interface Lock
    
    Throws:
    
    InterruptedException - if the current thread is interrupted while acquiring the lock.
  - lockAndGetFence
```
public final long lockAndGetFence()
```
    Description copied from interface: FencedLock
    Acquires the lock and returns the fencing token assigned to the current thread for this lock acquire. If the lock is acquired reentrantly, the same fencing token is returned, or the lock() call can fail with LockAcquireLimitExceededException if the lock acquire limit is exceeded. Please see FencedLockConfig for more information.
    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.
    This is a convenience method for the following pattern:
```
     FencedLock lock = ...;
     lock.lock();
     return lock.getFence();
 
```
    Consider the following scenario where the lock is free initially:
```
     FencedLock lock = ...; // the lock is free
     lock.lockAndGetFence();
     // JVM of the caller thread hits a long pause
     // and its CP session is closed on the CP group.
     lock.lockAndGetFence();
 
```
    In this scenario, a thread acquires the lock, then its JVM instance encounters a long pause, which is longer than CPSubsystemConfig.getSessionTimeToLiveSeconds(). In this case, its CP session will be closed on the corresponding CP group because it could not commit session heartbeats in the meantime. After the JVM instance wakes up again, the same thread attempts to acquire the lock reentrantly. In this case, the second lock() call fails by throwing LockOwnershipLostException which extends IllegalMonitorStateException. If the caller wants to deal with its session loss by taking some custom actions, it can handle the thrown LockOwnershipLostException instance. Otherwise, it can treat it as a regular IllegalMonitorStateException.
    Fencing tokens are monotonic numbers that are incremented each time the lock switches from the free state to the acquired state. They are simply used for ordering lock holders. A lock holder can pass its fencing to the shared resource to fence off previous lock holders. When this resource receives an operation, it can validate the fencing token in the operation.
    Consider the following scenario where the lock is free initially:
```
     FencedLock lock = ...; // the lock is free
     long fence1 = lock.lockAndGetFence(); // (1)
     long fence2 = lock.lockAndGetFence(); // (2)
     assert fence1 == fence2;
     lock.unlock();
     lock.unlock();
     long fence3 = lock.lockAndGetFence(); // (3)
     assert fence3 > fence1;
 
```
    In this scenario, the lock is acquired by a thread in the cluster. Then, the same thread reentrantly acquires the lock again. The fencing token returned from the second acquire is equal to the one returned from the first acquire, because of reentrancy. After the second acquire, the lock is released 2 times, hence becomes free. There is a third lock acquire here, which returns a new fencing token. Because this last lock acquire is not reentrant, its fencing token is guaranteed to be larger than the previous tokens, independent of the thread that has acquired the lock.
    Specified by:
    
    lockAndGetFence in interface FencedLock
  - tryLock
```
public boolean tryLock()
```
    Description copied from interface: FencedLock
    Acquires the lock if it is available or already held by the current thread at the time of invocation & the acquire limit is not exceeded, and immediately returns with the value true. If the lock is not available, then this method immediately returns with the value false. When the call is reentrant, it can return false if the lock acquire limit is exceeded. Please see FencedLockConfig for more information.
    A typical usage idiom for this method would be:
```
     FencedLock lock = ...;
     if (lock.tryLock()) {
         try {
             // manipulate protected state
         } finally {
             lock.unlock();
         }
     } else {
         // perform alternative actions
     }
 
```
    This usage ensures that the lock is unlocked if it was acquired, and doesn't try to unlock if the lock was not acquired.
    Specified by:
    
    tryLock in interface FencedLock
    
    Specified by:
    
    tryLock in interface Lock
    
    Returns:
    
    true if the lock was acquired and false otherwise
  - tryLockAndGetFence
```
public final long tryLockAndGetFence()
```
    Description copied from interface: FencedLock
    Acquires the lock only if it is free or already held by the current thread at the time of invocation & the acquire limit is not exceeded, and returns the fencing token assigned to the current thread for this lock acquire. If the lock is acquired reentrantly, the same fencing token is returned. If the lock is already held by another caller or the lock acquire limit is exceeded, then this method immediately returns FencedLock.INVALID_FENCE that represents a failed lock attempt. Please see FencedLockConfig for more information.
    This is a convenience method for the following pattern:
```
     FencedLock lock = ...;
     if (lock.tryLock()) {
         return lock.getFence();
     } else {
         return FencedLock.INVALID_FENCE;
     }
 
```
    Consider the following scenario where the lock is free initially:
```
     FencedLock lock = ...; // the lock is free
     lock.tryLockAndGetFence();
     // JVM of the caller thread hits a long pause
     // and its CP session is closed on the CP group.
     lock.tryLockAndGetFence();
 
```
    In this scenario, a thread acquires the lock, then its JVM instance encounters a long pause, which is longer than CPSubsystemConfig.getSessionTimeToLiveSeconds(). In this case, its CP session will be closed on the corresponding CP group because it could not commit session heartbeats in the meantime. After the JVM instance wakes up again, the same thread attempts to acquire the lock reentrantly. In this case, the second lock() call fails by throwing LockOwnershipLostException which extends IllegalMonitorStateException. If the caller wants to deal with its session loss by taking some custom actions, it can handle the thrown LockOwnershipLostException instance. Otherwise, it can treat it as a regular IllegalMonitorStateException.
    Fencing tokens are monotonic numbers that are incremented each time the lock switches from the free state to the acquired state. They are simply used for ordering lock holders. A lock holder can pass its fencing to the shared resource to fence off previous lock holders. When this resource receives an operation, it can validate the fencing token in the operation.
    Consider the following scenario where the lock is free initially:
```
     FencedLock lock = ...; // the lock is free
     long fence1 = lock.tryLockAndGetFence(); // (1)
     long fence2 = lock.tryLockAndGetFence(); // (2)
     assert fence1 == fence2;
     lock.unlock();
     lock.unlock();
     long fence3 = lock.tryLockAndGetFence(); // (3)
     assert fence3 > fence1;
 
```
    In this scenario, the lock is acquired by a thread in the cluster. Then, the same thread reentrantly acquires the lock again. The fencing token returned from the second acquire is equal to the one returned from the first acquire, because of reentrancy. After the second acquire, the lock is released 2 times, hence becomes free. There is a third lock acquire here, which returns a new fencing token. Because this last lock acquire is not reentrant, its fencing token is guaranteed to be larger than the previous tokens, independent of the thread that has acquired the lock.
    Specified by:
    
    tryLockAndGetFence in interface FencedLock
    
    Returns:
    
    the fencing token if the lock was acquired and FencedLock.INVALID_FENCE otherwise
  - tryLock
```
public boolean tryLock(long time,
                       @Nonnull
                       TimeUnit unit)
```
    Description copied from interface: FencedLock
    
    Acquires the lock if it is free within the given waiting time, or already held by the current thread.
    If the lock is available, this method returns immediately with the value true. When the call is reentrant, it immediately returns true if the lock acquire limit is not exceeded. Otherwise, it returns false on the reentrant lock attempt if the acquire limit is exceeded. Please see FencedLockConfig for more information.
    If the lock is not available then the current thread becomes disabled for thread scheduling purposes and lies dormant until the lock is acquired by the current thread or the specified waiting time elapses.
    If the lock is acquired, then the value true is returned.
    If the specified waiting time elapses, then the value false is returned. If the time is less than or equal to zero, the method does not wait at all.
    
    Specified by:
    
    tryLock in interface FencedLock
    
    Specified by:
    
    tryLock in interface Lock
    
    Parameters:
    
    time - the maximum time to wait for the lock
    
    unit - the time unit of the time argument
    
    Returns:
    
    true if the lock was acquired and false if the waiting time elapsed before the lock was acquired
  - tryLockAndGetFence
```
public final long tryLockAndGetFence(long time,
                                     @Nonnull
                                     TimeUnit unit)
```
    Description copied from interface: FencedLock
    Acquires the lock if it is free within the given waiting time, or already held by the current thread at the time of invocation & the acquire limit is not exceeded, and returns the fencing token assigned to the current thread for this lock acquire. If the lock is acquired reentrantly, the same fencing token is returned. If the lock acquire limit is exceeded, then this method immediately returns FencedLock.INVALID_FENCE that represents a failed lock attempt. Please see FencedLockConfig for more information.
    If the lock is not available then the current thread becomes disabled for thread scheduling purposes and lies dormant until the lock is acquired by the current thread or the specified waiting time elapses.
    If the specified waiting time elapses, then FencedLock.INVALID_FENCE is returned. If the time is less than or equal to zero, the method does not wait at all.
    This is a convenience method for the following pattern:
```
     FencedLock lock = ...;
     if (lock.tryLock(time, unit)) {
         return lock.getFence();
     } else {
         return FencedLock.INVALID_FENCE;
     }
 
```
    Consider the following scenario where the lock is free initially:
```
      FencedLock lock = ...; // the lock is free
      lock.tryLockAndGetFence(time, unit);
      // JVM of the caller thread hits a long pause and its CP session
      is closed on the CP group.
      lock.tryLockAndGetFence(time, unit);
 
```
    In this scenario, a thread acquires the lock, then its JVM instance encounters a long pause, which is longer than CPSubsystemConfig.getSessionTimeToLiveSeconds(). In this case, its CP session will be closed on the corresponding CP group because it could not commit session heartbeats in the meantime. After the JVM instance wakes up again, the same thread attempts to acquire the lock reentrantly. In this case, the second lock() call fails by throwing LockOwnershipLostException which extends IllegalMonitorStateException. If the caller wants to deal with its session loss by taking some custom actions, it can handle the thrown LockOwnershipLostException instance. Otherwise, it can treat it as a regular IllegalMonitorStateException.
    Fencing tokens are monotonic numbers that are incremented each time the lock switches from the free state to the acquired state. They are simply used for ordering lock holders. A lock holder can pass its fencing to the shared resource to fence off previous lock holders. When this resource receives an operation, it can validate the fencing token in the operation.
    Consider the following scenario where the lock is free initially:
```
     FencedLock lock = ...; // the lock is free
     long fence1 = lock.tryLockAndGetFence(time, unit); // (1)
     long fence2 = lock.tryLockAndGetFence(time, unit); // (2)
     assert fence1 == fence2;
     lock.unlock();
     lock.unlock();
     long fence3 = lock.tryLockAndGetFence(time, unit); // (3)
     assert fence3 > fence1;
 
```
    In this scenario, the lock is acquired by a thread in the cluster. Then, the same thread reentrantly acquires the lock again. The fencing token returned from the second acquire is equal to the one returned from the first acquire, because of reentrancy. After the second acquire, the lock is released 2 times, hence becomes free. There is a third lock acquire here, which returns a new fencing token. Because this last lock acquire is not reentrant, its fencing token is guaranteed to be larger than the previous tokens, independent of the thread that has acquired the lock.
    Specified by:
    
    tryLockAndGetFence in interface FencedLock
    
    Parameters:
    
    time - the maximum time to wait for the lock
    
    unit - the time unit of the time argument
    
    Returns:
    
    the fencing token if the lock was acquired and FencedLock.INVALID_FENCE otherwise
  - unlock
```
public final void unlock()
```
    Description copied from interface: FencedLock
    
    Releases the lock if the lock is currently held by the current thread.
    
    Specified by:
    
    unlock in interface FencedLock
    
    Specified by:
    
    unlock in interface Lock
  - newCondition
```
public final Condition newCondition()
```
    Description copied from interface: FencedLock
    
    NOT IMPLEMENTED. Fails by throwing UnsupportedOperationException.
    May the force be the one who dares to implement a linearizable distributed Condition :)
    
    Specified by:
    
    newCondition in interface FencedLock
    
    Specified by:
    
    newCondition in interface Lock
  - getFence
```
public final long getFence()
```
    Description copied from interface: FencedLock
    
    Returns the fencing token if the lock is held by the current thread.
    Fencing tokens are monotonic numbers that are incremented each time the lock switches from the free state to the acquired state. They are simply used for ordering lock holders. A lock holder can pass its fencing to the shared resource to fence off previous lock holders. When this resource receives an operation, it can validate the fencing token in the operation.
    
    Specified by:
    
    getFence in interface FencedLock
    
    Returns:
    
    the fencing token if the lock is held by the current thread
  - isLocked
```
public final boolean isLocked()
```
    Description copied from interface: FencedLock
    
    Returns whether this lock is locked or not.
    
    Specified by:
    
    isLocked in interface FencedLock
    
    Returns:
    
    true if this lock is locked by any thread in the cluster, false otherwise.
  - isLockedByCurrentThread
```
public final boolean isLockedByCurrentThread()
```
    Description copied from interface: FencedLock
    
    Returns whether the lock is held by the current thread or not.
    
    Specified by:
    
    isLockedByCurrentThread in interface FencedLock
    
    Returns:
    
    true if the lock is held by the current thread or not, false otherwise.
  - getLockCount
```
public final int getLockCount()
```
    Description copied from interface: FencedLock
    
    Returns the reentrant lock count if the lock is held by any thread in the cluster.
    
    Specified by:
    
    getLockCount in interface FencedLock
    
    Returns:
    
    the reentrant lock count if the lock is held by any thread in the cluster
  - destroy
```
public void destroy()
```
    Description copied from interface: DistributedObject
    
    Destroys this object cluster-wide. Clears and releases all resources for this object.
    
    Specified by:
    
    destroy in interface DistributedObject
  - getName
```
public final String getName()
```
    Description copied from interface: DistributedObject
    
    Returns the unique name for this DistributedObject. The returned value will never be null. The suggested way for getting name is retrieving it through DistributedObjectUtil.getName(DistributedObject) because this might be also a PrefixedDistributedObject.
    
    Specified by:
    
    getName in interface DistributedObject
    
    Returns:
    
    the unique name for this object.
  - getObjectName
```
public String getObjectName()
```
  - getPartitionKey
```
public String getPartitionKey()
```
    Description copied from interface: DistributedObject
    
    Returns the key of the partition that this DistributedObject is assigned to. The returned value only has meaning for a non-partitioned data structure like an IAtomicLong. For a partitioned data structure like an IMap, the returned value will not be null, but otherwise undefined.
    
    Specified by:
    
    getPartitionKey in interface DistributedObject
    
    Returns:
    
    the partition key.
  - getServiceName
```
public String getServiceName()
```
    Description copied from interface: DistributedObject
    
    Returns the service name for this object.
    
    Specified by:
    
    getServiceName in interface DistributedObject
    
    Returns:
    
    the service name for this object.
  - getLockedSessionId
```
public Long getLockedSessionId(long threadId)
```

Class AbstractRaftFencedLockProxy

Field Summary

Fields inherited from class com.hazelcast.cp.internal.session.SessionAwareProxy

Fields inherited from interface com.hazelcast.cp.lock.FencedLock

Constructor Summary

Method Summary

Methods inherited from class com.hazelcast.cp.internal.session.SessionAwareProxy

Methods inherited from class java.lang.Object

Methods inherited from interface com.hazelcast.cp.lock.FencedLock

Field Detail

proxyName

objectName

Constructor Detail

AbstractRaftFencedLockProxy

Method Detail

doLock

doTryLock

doUnlock

doGetLockOwnershipState

lock

lockInterruptibly

lockAndGetFence

tryLock

tryLockAndGetFence

tryLock

tryLockAndGetFence

unlock

newCondition

getFence

isLocked

isLockedByCurrentThread

getLockCount

destroy

getName

getObjectName

getPartitionKey

getServiceName

getLockedSessionId