Add builders for LockingVisitors implementations

Author: garydgregory

src/changes/changes.xml

@@ -136,6 +136,7 @@ The <action> type attribute can be add,update,fix,remove.
     <action                   type="add" dev="ggregory" due-to="Gary Gregory">Add org.apache.commons.lang3.concurrent.locks.LockingVisitors.reentrantLockVisitor(Object).</action>
     <action                   type="add" dev="ggregory" due-to="Gary Gregory">Add org.apache.commons.lang3.concurrent.locks.LockingVisitors.create(Object, ReentrantLock).</action>
     <action                   type="add" dev="ggregory" due-to="Gary Gregory">Add org.apache.commons.lang3.concurrent.locks.LockingVisitors.ReentrantLockVisitor.</action>
+    <action                   type="add" dev="ggregory" due-to="Gary Gregory">Add builders for LockingVisitors implementations.</action>
     <!-- UPDATE -->
     <action                   type="update" dev="ggregory" due-to="Gary Gregory, Dependabot">Bump org.apache.commons:commons-parent from 73 to 85 #1267, #1277, #1283, #1288, #1302, #1377.</action>
     <action                   type="update" dev="ggregory" due-to="Gary Gregory, Dependabot">[site] Bump org.codehaus.mojo:taglist-maven-plugin from 3.1.0 to 3.2.1 #1300.</action>

src/main/java/org/apache/commons/lang3/concurrent/locks/LockingVisitors.java

@@ -24,6 +24,7 @@
 import java.util.concurrent.locks.StampedLock;
 import java.util.function.Supplier;
 
+import org.apache.commons.lang3.builder.AbstractSupplier;
 import org.apache.commons.lang3.function.Failable;
 import org.apache.commons.lang3.function.FailableConsumer;
 import org.apache.commons.lang3.function.FailableFunction;
@@ -94,6 +95,103 @@ public class LockingVisitors {
      */
     public static class LockVisitor<O, L> {
 
+        /**
+         * Builds {@link LockVisitor} instances.
+         *
+         * @param <O> the wrapped object type.
+         * @param <L> the wrapped lock type.
+         * @param <B> the builder type.
+         * @since 3.18.0
+         */
+        public static class LVBuilder<O, L, B extends LVBuilder<O, L, B>> extends AbstractSupplier<LockVisitor<O, L>, B, RuntimeException> {
+
+            /**
+             * The lock object, untyped, since, for example {@link StampedLock} does not implement a locking interface in
+             * Java 8.
+             */
+            L lock;
+
+            /**
+             * The guarded object.
+             */
+            O object;
+
+            /**
+             * Supplies the read lock, usually from the lock object.
+             */
+            private Supplier<Lock> readLockSupplier;
+
+            /**
+             * Supplies the write lock, usually from the lock object.
+             */
+            private Supplier<Lock> writeLockSupplier;
+
+            /**
+             * Constructs a new instance.
+             */
+            public LVBuilder() {
+                // empty
+            }
+
+            @Override
+            public LockVisitor<O, L> get() {
+                return new LockVisitor<>(this);
+            }
+
+            Supplier<Lock> getReadLockSupplier() {
+                return readLockSupplier;
+            }
+
+
+            Supplier<Lock> getWriteLockSupplier() {
+                return writeLockSupplier;
+            }
+
+            /**
+             * Set the lock used from accept methods.
+             *
+             * @param lock the lock.
+             * @return {@code this} instance.
+             */
+            public B setLock(final L lock) {
+                this.lock = lock;
+                return asThis();
+            }
+
+            /**
+             * Set the resource.
+             *
+             * @param object the resource.
+             * @return {@code this} instance.
+             */
+            public B setObject(final O object) {
+                this.object = object;
+                return asThis();
+            }
+
+            /**
+             * Supplies the read lock.
+             *
+             * @param readLockSupplier Supplies the read lock.
+             * @return {@code this} instance.
+             */
+            public B setReadLockSupplier(final Supplier<Lock> readLockSupplier) {
+                this.readLockSupplier = readLockSupplier;
+                return asThis();
+            }
+
+            /**
+             * Supplies the write lock.
+             *
+             * @param writeLockSupplier Supplies the write lock.
+             * @return {@code this} instance.
+             */
+            public B setWriteLockSupplier(final Supplier<Lock> writeLockSupplier) {
+                this.writeLockSupplier = writeLockSupplier;
+                return asThis();
+            }
+        }
+
         /**
          * The lock object, untyped, since, for example {@link StampedLock} does not implement a locking interface in
          * Java 8.
@@ -115,6 +213,18 @@ public static class LockVisitor<O, L> {
          */
         private final Supplier<Lock> writeLockSupplier;
 
+        /**
+         * Constructs an instance from a builder.
+         *
+         * @param builder The builder.
+         */
+        private LockVisitor(final LVBuilder<O, L, ?> builder) {
+            this.object = Objects.requireNonNull(builder.object, "object");
+            this.lock = Objects.requireNonNull(builder.lock, "lock");
+            this.readLockSupplier = Objects.requireNonNull(builder.readLockSupplier, "readLockSupplier");
+            this.writeLockSupplier = Objects.requireNonNull(builder.writeLockSupplier, "writeLockSupplier");
+        }
+
         /**
          * Constructs an instance.
          *
@@ -316,6 +426,54 @@ protected <T> T lockApplyUnlock(final Supplier<Lock> lockSupplier, final Failabl
      */
     public static class ReadWriteLockVisitor<O> extends LockVisitor<O, ReadWriteLock> {
 
+        /**
+         * Builds {@link LockVisitor} instances.
+         *
+         * @param <O> the wrapped object type.
+         * @since 3.18.0
+         */
+        public static class Builder<O> extends LVBuilder<O, ReadWriteLock, Builder<O>> {
+
+            /**
+             * Constructs a new instance.
+             */
+            public Builder() {
+                // empty
+            }
+
+            @Override
+            public ReadWriteLockVisitor<O> get() {
+                return new ReadWriteLockVisitor<>(this);
+            }
+
+            @Override
+            public Builder<O> setLock(final ReadWriteLock readWriteLock) {
+                setReadLockSupplier(readWriteLock::readLock);
+                setWriteLockSupplier(readWriteLock::writeLock);
+                return super.setLock(readWriteLock);
+            }
+        }
+
+        /**
+         * Creates a new builder.
+         *
+         * @param <O> the wrapped object type.
+         * @return a new builder.
+         * @since 3.18.0
+         */
+        public static <O> Builder<O> builder() {
+            return new Builder<>();
+        }
+
+        /**
+         * Constructs a new instance from a builder.
+         *
+         * @param builder a builder.
+         */
+        private ReadWriteLockVisitor(final Builder<O> builder) {
+            super(builder);
+        }
+
         /**
          * Creates a new instance with the given locked object. This constructor is supposed to be used for subclassing
          * only. In general, it is suggested to use {@link LockingVisitors#stampedLockVisitor(Object)} instead.
@@ -326,6 +484,7 @@ public static class ReadWriteLockVisitor<O> extends LockVisitor<O, ReadWriteLock
         protected ReadWriteLockVisitor(final O object, final ReadWriteLock readWriteLock) {
             super(object, readWriteLock, readWriteLock::readLock, readWriteLock::writeLock);
         }
+
     }
 
     /**
@@ -340,6 +499,56 @@ protected ReadWriteLockVisitor(final O object, final ReadWriteLock readWriteLock
      */
     public static class ReentrantLockVisitor<O> extends LockVisitor<O, ReentrantLock> {
 
+        /**
+         * Builds {@link LockVisitor} instances.
+         *
+         * @param <O> the wrapped object type.
+         * @since 3.18.0
+         */
+        public static class Builder<O> extends LVBuilder<O, ReentrantLock, Builder<O>> {
+
+            /**
+             * Constructs a new instance.
+             */
+            public Builder() {
+                // empty
+            }
+
+            @Override
+            public ReentrantLockVisitor<O> get() {
+                return new ReentrantLockVisitor<>(this);
+            }
+
+
+            @Override
+            public Builder<O> setLock(final ReentrantLock reentrantLock) {
+                setReadLockSupplier(() -> reentrantLock);
+                setWriteLockSupplier(() -> reentrantLock);
+                return super.setLock(reentrantLock);
+            }
+        }
+
+        /**
+         * Creates a new builder.
+         *
+         * @param <O> the wrapped object type.
+         * @return a new builder.
+         * @since 3.18.0
+         */
+        public static <O> Builder<O> builder() {
+            return new Builder<>();
+        }
+
+        /**
+         * Constructs a new instance from a builder.
+         *
+         * @param builder a builder.
+         */
+        private ReentrantLockVisitor(final Builder<O> builder) {
+            super(builder);
+        }
+
+
         /**
          * Creates a new instance with the given locked object. This constructor is supposed to be used for subclassing
          * only. In general, it is suggested to use {@link LockingVisitors#reentrantLockVisitor(Object)} instead.
@@ -363,6 +572,55 @@ protected ReentrantLockVisitor(final O object, final ReentrantLock reentrantLock
      */
     public static class StampedLockVisitor<O> extends LockVisitor<O, StampedLock> {
 
+        /**
+         * Builds {@link LockVisitor} instances.
+         *
+         * @param <O> the wrapped object type.
+         * @since 3.18.0
+         */
+        public static class Builder<O> extends LVBuilder<O, StampedLock, Builder<O>> {
+
+            /**
+             * Constructs a new instance.
+             */
+            public Builder() {
+                // empty
+            }
+
+            @Override
+            public StampedLockVisitor<O> get() {
+                return new StampedLockVisitor<>(this);
+            }
+
+
+            @Override
+            public Builder<O> setLock(final StampedLock stampedLock) {
+                setReadLockSupplier(stampedLock::asReadLock);
+                setWriteLockSupplier(stampedLock::asWriteLock);
+                return super.setLock(stampedLock);
+            }
+        }
+
+        /**
+         * Creates a new builder.
+         *
+         * @param <O> the wrapped object type.
+         * @return a new builder.
+         * @since 3.18.0
+         */
+        public static <O> Builder<O> builder() {
+            return new Builder<>();
+        }
+
+        /**
+         * Constructs a new instance from a builder.
+         *
+         * @param builder a builder.
+         */
+        private StampedLockVisitor(final Builder<O> builder) {
+            super(builder);
+        }
+
         /**
          * Creates a new instance with the given locked object. This constructor is supposed to be used for subclassing
          * only. In general, it is suggested to use {@link LockingVisitors#stampedLockVisitor(Object)} instead.