CloseableLock (UnboundID LDAP SDK for Java 7.0.1)

java.lang.Object
- com.unboundid.util.CloseableLock

@Mutable
 @ThreadSafety(level=COMPLETELY_THREADSAFE)
public final class CloseableLock
extends java.lang.Object

This class provides an implementation of a reentrant lock that can be used with the Java try-with-resources facility. It does not implement the java.util.concurrent.locks.Lock interface in order to ensure that it can only be used through lock-with-resources mechanism, but it uses a java.util.concurrent.locks.ReentrantLock behind the scenes to provide its functionality.

Example

The following example demonstrates how to use this lock using the Java try-with-resources facility:

 // Wait for up to 5 seconds to acquire the lock.
 try (CloseableLock.Lock lock =
           closeableLock.tryLock(5L, TimeUnit.SECONDS))
 {
   // NOTE:  If you don't reference the lock object inside the try block, the
   // compiler will issue a warning.
   lock.avoidCompilerWarning();

   // Do something while the lock is held.  The lock will automatically be
   // released once code execution leaves this block.
 }
 catch (final InterruptedException e)
 {
   // The thread was interrupted before the lock could be acquired.
 }
 catch (final TimeoutException)
 {
   // The lock could not be acquired within the specified 5-second timeout.
 }

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`class`	`CloseableLock.Lock` This class provides a `Closeable` implementation that may be used to unlock a `CloseableLock` via Java's try-with-resources facility.

Constructor Summary

Constructors
Constructor and Description
`CloseableLock()` Creates a new instance of this lock with a non-fair ordering policy.
`CloseableLock(boolean fair)` Creates a new instance of this lock with the specified ordering policy.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`int`	`getHoldCount()` Retrieves the number of holds that the current thread has on the lock.
`int`	`getQueueLength()` Retrieves an estimate of the number of threads currently waiting to acquire this lock.
`boolean`	`hasQueuedThread(java.lang.Thread thread)` Indicates whether the specified thread is currently waiting to acquire this lock, or `false` if not.
`boolean`	`hasQueuedThreads()` Indicates whether any threads are currently waiting to acquire this lock.
`boolean`	`isFair()` Indicates whether this lock uses fair ordering.
`boolean`	`isHeldByCurrentThread()` Indicates whether this lock is currently held by the current thread.
`boolean`	`isLocked()` Indicates whether this lock is currently held by any thread.
`CloseableLock.Lock`	`lock()` Acquires this lock, blocking until the lock is available.
`CloseableLock.Lock`	`lockInterruptibly()` Acquires this lock, blocking until the lock is available.
`java.lang.String`	`toString()` Retrieves a string representation of this lock.
`CloseableLock.Lock`	`tryLock(long waitTime, java.util.concurrent.TimeUnit timeUnit)` Tries to acquire the lock, waiting up to the specified length of time for it to become available.

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

- Constructor Detail
  - CloseableLock
```
public CloseableLock()
```
    Creates a new instance of this lock with a non-fair ordering policy.
  - CloseableLock
```
public CloseableLock(boolean fair)
```
    Creates a new instance of this lock with the specified ordering policy.
    
    Parameters:
    
    fair - Indicates whether the lock should use fair ordering. If true, then if multiple threads are waiting on the lock, then the one that has been waiting the longest is the one that will get it. If false, then no guarantee will be made about the order. Fair ordering can incur a performance penalty.
- Method Detail
  - lock
```
@NotNull
public CloseableLock.Lock lock()
```
    Acquires this lock, blocking until the lock is available.
    
    Returns:
    
    The CloseableLock.Lock instance that may be used to perform the unlock via the try-with-resources facility.
  - lockInterruptibly
```
@NotNull
public CloseableLock.Lock lockInterruptibly()
                                              throws java.lang.InterruptedException
```
    Acquires this lock, blocking until the lock is available.
    
    Returns:
    
    The CloseableLock.Lock instance that may be used to perform the unlock via the try-with-resources facility.
    
    Throws:
    
    java.lang.InterruptedException - If the thread is interrupted while waiting to acquire the lock.
  - tryLock
```
@NotNull
public CloseableLock.Lock tryLock(long waitTime,
                                           @NotNull
                                           java.util.concurrent.TimeUnit timeUnit)
                                    throws java.lang.InterruptedException,
                                           java.util.concurrent.TimeoutException
```
    Tries to acquire the lock, waiting up to the specified length of time for it to become available.
    
    Parameters:
    
    waitTime - The maximum length of time to wait for the lock. It must be greater than zero.
    
    timeUnit - The time unit that should be used when evaluating the waitTime value.
    
    Returns:
    
    The CloseableLock.Lock instance that may be used to perform the unlock via the try-with-resources facility.
    
    Throws:
    
    java.lang.InterruptedException - If the thread is interrupted while waiting to acquire the lock.
    
    java.util.concurrent.TimeoutException - If the lock could not be acquired within the specified length of time.
  - isFair
```
public boolean isFair()
```
    Indicates whether this lock uses fair ordering.
    
    Returns:
    
    true if this lock uses fair ordering, or false if not.
  - isLocked
```
public boolean isLocked()
```
    Indicates whether this lock is currently held by any thread.
    
    Returns:
    
    true if this lock is currently held by any thread, or false if not.
  - isHeldByCurrentThread
```
public boolean isHeldByCurrentThread()
```
    Indicates whether this lock is currently held by the current thread.
    
    Returns:
    
    true if this lock is currently held by the current thread, or false if not.
  - getHoldCount
```
public int getHoldCount()
```
    Retrieves the number of holds that the current thread has on the lock.
    
    Returns:
    
    The number of holds that the current thread has on the lock.
  - hasQueuedThreads
```
public boolean hasQueuedThreads()
```
    Indicates whether any threads are currently waiting to acquire this lock.
    
    Returns:
    
    true if any threads are currently waiting to acquire this lock, or false if not.
  - hasQueuedThread
```
public boolean hasQueuedThread(@NotNull
                               java.lang.Thread thread)
```
    Indicates whether the specified thread is currently waiting to acquire this lock, or false if not.
    
    Parameters:
    
    thread - The thread for which to make the determination. It must not be null.
    
    Returns:
    
    true if the specified thread is currently waiting to acquire this lock, or false if not.
  - getQueueLength
```
public int getQueueLength()
```
    Retrieves an estimate of the number of threads currently waiting to acquire this lock.
    
    Returns:
    
    An estimate of the number of threads currently waiting to acquire this lock.
  - toString
```
@NotNull
public java.lang.String toString()
```
    Retrieves a string representation of this lock.
    
    Overrides:
    
    toString in class java.lang.Object
    
    Returns:
    
    A string representation of this lock.

Class CloseableLock

Example

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

CloseableLock

CloseableLock

Method Detail

lock

lockInterruptibly

tryLock

isFair

isLocked

isHeldByCurrentThread

getHoldCount

hasQueuedThreads

hasQueuedThread

getQueueLength

toString