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

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

# Class LockingVisitors

java.lang.Object
org.apache.commons.lang3.concurrent.locks.LockingVisitors

public class LockingVisitors extends Object
Combines the monitor and visitor pattern to work with `locked objects`. Locked objects are an alternative to synchronization. This, on Wikipedia, is known as the Visitor pattern (https://en.wikipedia.org/wiki/Visitor_pattern), and from the "Gang of Four" "Design Patterns" book's Visitor pattern [Gamma, E., Helm, R., & Johnson, R. (1998). Visitor. In Design patterns elements of reusable object oriented software (pp. 331-344). Reading: Addison Wesley.].

Locking is preferable, if there is a distinction between read access (multiple threads may have read access concurrently), and write access (only one thread may have write access at any given time). In comparison, synchronization doesn't support read access, because synchronized access is exclusive.

Using this class is fairly straightforward:

1. While still in single thread mode, create an instance of `LockingVisitors.StampedLockVisitor` by calling `stampedLockVisitor(Object)`, passing the object which needs to be locked. Discard all references to the locked object. Instead, use references to the lock.
2. If you want to access the locked object, create a `FailableConsumer`. The consumer will receive the locked object as a parameter. For convenience, the consumer may be implemented as a Lambda. Then invoke `LockingVisitors.LockVisitor.acceptReadLocked(FailableConsumer)`, or `LockingVisitors.LockVisitor.acceptWriteLocked(FailableConsumer)`, passing the consumer.
3. As an alternative, if you need to produce a result object, you may use a `FailableFunction`. This function may also be implemented as a Lambda. To have the function executed, invoke `LockingVisitors.LockVisitor.applyReadLocked(FailableFunction)`, or `LockingVisitors.LockVisitor.applyWriteLocked(FailableFunction)`.

Example: A thread safe logger class.

       public class SimpleLogger {

         private final StampedLockVisitor<PrintStream> lock;

         public SimpleLogger(OutputStream out) {
             lock = LockingVisitors.stampedLockVisitor(new PrintStream(out));
         }

         public void log(String message) {
             lock.acceptWriteLocked(ps -> ps.println(message));
         }

         public void log(byte[] buffer) {
             lock.acceptWriteLocked(ps -> { ps.write(buffer); ps.println(); });
         }
     }

Since:
  3.11

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static class`
  `LockingVisitors.LockVisitor<O,L>`
  Wraps a domain object and a lock for access by lambdas.
  `static class`
  `LockingVisitors.ReadWriteLockVisitor<O>`
  This class implements a wrapper for a locked (hidden) object, and provides the means to access it.
  `static class`
  `LockingVisitors.StampedLockVisitor<O>`
  This class implements a wrapper for a locked (hidden) object, and provides the means to access it.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `LockingVisitors()`
  Deprecated.
  TODO Make private in 4.0.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static <O> LockingVisitors.ReadWriteLockVisitor<O>`
  `create(O object, ReadWriteLock readWriteLock)`
  Creates a new instance of `LockingVisitors.ReadWriteLockVisitor` with the given (hidden) object and lock.
  `static <O> LockingVisitors.ReadWriteLockVisitor<O>`
  `reentrantReadWriteLockVisitor(O object)`
  Creates a new instance of `LockingVisitors.ReadWriteLockVisitor` with the given (hidden) object.
  `static <O> LockingVisitors.StampedLockVisitor<O>`
  `stampedLockVisitor(O object)`
  Creates a new instance of `LockingVisitors.StampedLockVisitor` with the given (hidden) object.

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

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

- ## Constructor Details

  - ### LockingVisitors

    @Deprecated public LockingVisitors()
    Deprecated.
    TODO Make private in 4.0.
    Make private in 4.0.

- ## Method Details

  - ### create

    public static <O> LockingVisitors.ReadWriteLockVisitor<O> create(O object, ReadWriteLock readWriteLock)
    Creates a new instance of `LockingVisitors.ReadWriteLockVisitor` with the given (hidden) object and lock.
    Type Parameters:
      `O` - The locked objects type.
    Parameters:
      `object` - The locked (hidden) object.
      `readWriteLock` - The lock to use.
    Returns:
      The created instance, a `lock` for the given object.
    Since:
      3.13.0

  - ### reentrantReadWriteLockVisitor

    public static <O> LockingVisitors.ReadWriteLockVisitor<O> reentrantReadWriteLockVisitor(O object)
    Creates a new instance of `LockingVisitors.ReadWriteLockVisitor` with the given (hidden) object.
    Type Parameters:
      `O` - The locked objects type.
    Parameters:
      `object` - The locked (hidden) object.
    Returns:
      The created instance, a `lock` for the given object.

  - ### stampedLockVisitor

    public static <O> LockingVisitors.StampedLockVisitor<O> stampedLockVisitor(O object)
    Creates a new instance of `LockingVisitors.StampedLockVisitor` with the given (hidden) object.
    Type Parameters:
      `O` - The locked objects type.
    Parameters:
      `object` - The locked (hidden) object.
    Returns:
      The created instance, a `lock` for the given object.