LockingVisitors.LockVisitor (Apache Commons Lang 3.17.0 API)
Description: declaration: package: org.apache.commons.lang3.concurrent.locks, class: LockingVisitors, class: LockVisitor

Package org.apache.commons.lang3.concurrent.locks

# Class LockingVisitors.LockVisitor<O,L>

java.lang.Object
org.apache.commons.lang3.concurrent.locks.LockingVisitors.LockVisitor<O,L>

Type Parameters:
  `O` - the wrapped object type.
  `L` - the wrapped lock type.

Direct Known Subclasses:
  `LockingVisitors.ReadWriteLockVisitor`, `LockingVisitors.StampedLockVisitor`

Enclosing class:
  LockingVisitors

public static class LockingVisitors.LockVisitor<O,L> extends Object
Wraps a domain object and a lock for access by lambdas.

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `LockVisitor(O object, L lock, Supplier<Lock> readLockSupplier, Supplier<Lock> writeLockSupplier)`
  Constructs an instance.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `acceptReadLocked(FailableConsumer<O,?> consumer)`
  Provides read (shared, non-exclusive) access to the locked (hidden) object.
  `void`
  `acceptWriteLocked(FailableConsumer<O,?> consumer)`
  Provides write (exclusive) access to the locked (hidden) object.
  `<T> T`
  `applyReadLocked(FailableFunction<O,T,?> function)`
  Provides read (shared, non-exclusive) access to the locked (hidden) object for the purpose of computing a result object.
  `<T> T`
  `applyWriteLocked(FailableFunction<O,T,?> function)`
  Provides write (exclusive) access to the locked (hidden) object for the purpose of computing a result object.
  `L`
  `getLock()`
  Gets the lock.
  `O`
  `getObject()`
  Gets the guarded object.
  `protected void`
  `lockAcceptUnlock(Supplier<Lock> lockSupplier, FailableConsumer<O,?> consumer)`
  This method provides the default implementation for `acceptReadLocked(FailableConsumer)`, and `acceptWriteLocked(FailableConsumer)`.
  `protected <T> T`
  `lockApplyUnlock(Supplier<Lock> lockSupplier, FailableFunction<O,T,?> function)`
  This method provides the actual implementation for `applyReadLocked(FailableFunction)`, and `applyWriteLocked(FailableFunction)`.

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

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

- ## Constructor Details

  - ### LockVisitor

    protected LockVisitor(O object, L lock, Supplier<Lock> readLockSupplier, Supplier<Lock> writeLockSupplier)
    Constructs an instance.
    Parameters:
      `object` - The object to guard.
      `lock` - The locking object.
      `readLockSupplier` - Supplies the read lock, usually from the lock object.
      `writeLockSupplier` - Supplies the write lock, usually from the lock object.

- ## Method Details

  - ### acceptReadLocked

    public void acceptReadLocked(FailableConsumer<O,?> consumer)
    Provides read (shared, non-exclusive) access to the locked (hidden) object. More precisely, what the method will do (in the given order):
    1. Obtain a read (shared) lock on the locked (hidden) object. The current thread may block, until such a lock is granted.
    2. Invokes the given `consumer`, passing the locked object as the parameter.
    3. Release the lock, as soon as the consumers invocation is done. If the invocation results in an error, the lock will be released anyways.
    Parameters:
      `consumer` - The consumer, which is being invoked to use the hidden object, which will be passed as the consumers parameter.
    See Also:
      - `acceptWriteLocked(FailableConsumer)`
      - `applyReadLocked(FailableFunction)`

  - ### acceptWriteLocked

    public void acceptWriteLocked(FailableConsumer<O,?> consumer)
    Provides write (exclusive) access to the locked (hidden) object. More precisely, what the method will do (in the given order):
    1. Obtain a write (shared) lock on the locked (hidden) object. The current thread may block, until such a lock is granted.
    2. Invokes the given `consumer`, passing the locked object as the parameter.
    3. Release the lock, as soon as the consumers invocation is done. If the invocation results in an error, the lock will be released anyways.
    Parameters:
      `consumer` - The consumer, which is being invoked to use the hidden object, which will be passed as the consumers parameter.
    See Also:
      - `acceptReadLocked(FailableConsumer)`
      - `applyWriteLocked(FailableFunction)`

  - ### applyReadLocked

    public <T> T applyReadLocked(FailableFunction<O,T,?> function)
    Provides read (shared, non-exclusive) access to the locked (hidden) object for the purpose of computing a result object. More precisely, what the method will do (in the given order):
    1. Obtain a read (shared) lock on the locked (hidden) object. The current thread may block, until such a lock is granted.
    2. Invokes the given `function`, passing the locked object as the parameter, receiving the functions result.
    3. Release the lock, as soon as the consumers invocation is done. If the invocation results in an error, the lock will be released anyways.
    4. Return the result object, that has been received from the functions invocation.

    Example: Consider that the hidden object is a list, and we wish to know the current size of the list. This might be achieved with the following:

         private Lock<List<Object>> listLock;

         public int getCurrentListSize() {
             final Integer sizeInteger = listLock.applyReadLocked(list -> Integer.valueOf(list.size));
             return sizeInteger.intValue();
         }

    Type Parameters:
      `T` - The result type (both the functions, and this method's.)
    Parameters:
      `function` - The function, which is being invoked to compute the result. The function will receive the hidden object.
    Returns:
      The result object, which has been returned by the functions invocation.
    Throws:
      `IllegalStateException` - The result object would be, in fact, the hidden object. This would extend access to the hidden object beyond this methods lifetime and will therefore be prevented.
    See Also:
      - `acceptReadLocked(FailableConsumer)`
      - `applyWriteLocked(FailableFunction)`

  - ### applyWriteLocked

    public <T> T applyWriteLocked(FailableFunction<O,T,?> function)
    Provides write (exclusive) access to the locked (hidden) object for the purpose of computing a result object. More precisely, what the method will do (in the given order):
    1. Obtain a read (shared) lock on the locked (hidden) object. The current thread may block, until such a lock is granted.
    2. Invokes the given `function`, passing the locked object as the parameter, receiving the functions result.
    3. Release the lock, as soon as the consumers invocation is done. If the invocation results in an error, the lock will be released anyways.
    4. Return the result object, that has been received from the functions invocation.
    Type Parameters:
      `T` - The result type (both the functions, and this method's.)
    Parameters:
      `function` - The function, which is being invoked to compute the result. The function will receive the hidden object.
    Returns:
      The result object, which has been returned by the functions invocation.
    Throws:
      `IllegalStateException` - The result object would be, in fact, the hidden object. This would extend access to the hidden object beyond this methods lifetime and will therefore be prevented.
    See Also:
      - `acceptReadLocked(FailableConsumer)`
      - `applyWriteLocked(FailableFunction)`

  - ### getLock

    public L getLock()
    Gets the lock.
    Returns:
      the lock.

  - ### getObject

    public O getObject()
    Gets the guarded object.
    Returns:
      the object.

  - ### lockAcceptUnlock

    protected void lockAcceptUnlock(Supplier<Lock> lockSupplier, FailableConsumer<O,?> consumer)
    This method provides the default implementation for `acceptReadLocked(FailableConsumer)`, and `acceptWriteLocked(FailableConsumer)`.
    Parameters:
      `lockSupplier` - A supplier for the lock. (This provides, in fact, a long, because a `StampedLock` is used internally.)
      `consumer` - The consumer, which is to be given access to the locked (hidden) object, which will be passed as a parameter.
    See Also:
      - `acceptReadLocked(FailableConsumer)`
      - `acceptWriteLocked(FailableConsumer)`

  - ### lockApplyUnlock

    protected <T> T lockApplyUnlock(Supplier<Lock> lockSupplier, FailableFunction<O,T,?> function)
    This method provides the actual implementation for `applyReadLocked(FailableFunction)`, and `applyWriteLocked(FailableFunction)`.
    Type Parameters:
      `T` - The result type (both the functions, and this method's.)
    Parameters:
      `lockSupplier` - A supplier for the lock. (This provides, in fact, a long, because a `StampedLock` is used internally.)
      `function` - The function, which is being invoked to compute the result object. This function will receive the locked (hidden) object as a parameter.
    Returns:
      The result object, which has been returned by the functions invocation.
    Throws:
      `IllegalStateException` - The result object would be, in fact, the hidden object. This would extend access to the hidden object beyond this methods lifetime and will therefore be prevented.
    See Also:
      - `applyReadLocked(FailableFunction)`
      - `applyWriteLocked(FailableFunction)`