You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by gg...@apache.org on 2025/08/20 22:24:18 UTC

(commons-lang) 02/07: Javadoc

This is an automated email from the ASF dual-hosted git repository.

ggregory pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-lang.git

commit d385969c523508ac5de9503f600ae1998e42224b
Author: Gary D. Gregory <ga...@gmail.com>
AuthorDate: Wed Aug 20 16:51:24 2025 -0400

    Javadoc
    
    Reduce vertical whitespace
---
 .../lang3/concurrent/AtomicInitializer.java        |  14 +--
 .../concurrent/CallableBackgroundInitializer.java  |  32 +++---
 .../commons/lang3/concurrent/LazyInitializer.java  |   6 +-
 .../concurrent/MultiBackgroundInitializer.java     | 120 +++++++++------------
 .../concurrent/BackgroundInitializerTest.java      |   4 +-
 5 files changed, 70 insertions(+), 106 deletions(-)

diff --git a/src/main/java/org/apache/commons/lang3/concurrent/AtomicInitializer.java b/src/main/java/org/apache/commons/lang3/concurrent/AtomicInitializer.java
index a1c88a155..649ea161d 100644
--- a/src/main/java/org/apache/commons/lang3/concurrent/AtomicInitializer.java
+++ b/src/main/java/org/apache/commons/lang3/concurrent/AtomicInitializer.java
@@ -62,7 +62,7 @@
  * {@link LazyInitializer} is more appropriate.
  * </p>
  *
- * @param <T> the type of the object managed by this initializer class
+ * @param <T> the type of the object managed by this initializer class.
  * @since 3.0
  */
 public class AtomicInitializer<T> extends AbstractConcurrentInitializer<T, ConcurrentException> {
@@ -125,18 +125,15 @@ private AtomicInitializer(final FailableSupplier<T, ConcurrentException> initial
     }
 
     /**
-     * Gets the object managed by this initializer. The object is created if
-     * it is not available yet and stored internally. This method always returns
-     * the same object.
+     * Gets the object managed by this initializer. The object is created if it is not available yet and stored internally. This method always returns the same
+     * object.
      *
-     * @return the object created by this {@link AtomicInitializer}
-     * @throws ConcurrentException if an error occurred during initialization of
-     * the object
+     * @return the object created by this {@link AtomicInitializer}.
+     * @throws ConcurrentException if an error occurred during initialization of the object.
      */
     @Override
     public T get() throws ConcurrentException {
         T result = reference.get();
-
         if (result == getNoInit()) {
             result = initialize();
             if (!reference.compareAndSet(getNoInit(), result)) {
@@ -144,7 +141,6 @@ public T get() throws ConcurrentException {
                 result = reference.get();
             }
         }
-
         return result;
     }
 
diff --git a/src/main/java/org/apache/commons/lang3/concurrent/CallableBackgroundInitializer.java b/src/main/java/org/apache/commons/lang3/concurrent/CallableBackgroundInitializer.java
index 42bdd1e0b..20fa6b03a 100644
--- a/src/main/java/org/apache/commons/lang3/concurrent/CallableBackgroundInitializer.java
+++ b/src/main/java/org/apache/commons/lang3/concurrent/CallableBackgroundInitializer.java
@@ -72,8 +72,8 @@ public class CallableBackgroundInitializer<T> extends BackgroundInitializer<T> {
      * Creates a new instance of {@link CallableBackgroundInitializer} and sets
      * the {@link Callable} to be executed in a background thread.
      *
-     * @param call the {@link Callable} (must not be <strong>null</strong>)
-     * @throws IllegalArgumentException if the {@link Callable} is <strong>null</strong>
+     * @param call the {@link Callable} (must not be <strong>null</strong>).
+     * @throws IllegalArgumentException if the {@link Callable} is <strong>null</strong>.
      */
     public CallableBackgroundInitializer(final Callable<T> call) {
         checkCallable(call);
@@ -81,15 +81,12 @@ public CallableBackgroundInitializer(final Callable<T> call) {
     }
 
     /**
-     * Creates a new instance of {@link CallableBackgroundInitializer} and
-     * initializes it with the {@link Callable} to be executed in a background
-     * thread and the {@link ExecutorService} for managing the background
-     * execution.
+     * Creates a new instance of {@link CallableBackgroundInitializer} and initializes it with the {@link Callable} to be executed in a background thread and
+     * the {@link ExecutorService} for managing the background execution.
      *
-     * @param call the {@link Callable} (must not be <strong>null</strong>)
-     * @param exec an external {@link ExecutorService} to be used for task
-     * execution
-     * @throws IllegalArgumentException if the {@link Callable} is <strong>null</strong>
+     * @param call the {@link Callable} (must not be <strong>null</strong>).
+     * @param exec an external {@link ExecutorService} to be used for task execution.
+     * @throws IllegalArgumentException if the {@link Callable} is <strong>null</strong>.
      */
     public CallableBackgroundInitializer(final Callable<T> call, final ExecutorService exec) {
         super(exec);
@@ -98,11 +95,10 @@ public CallableBackgroundInitializer(final Callable<T> call, final ExecutorServi
     }
 
     /**
-     * Tests the passed in {@link Callable} and throws an exception if it is
-     * undefined.
+     * Tests the passed in {@link Callable} and throws an exception if it is undefined.
      *
-     * @param callable the object to check
-     * @throws IllegalArgumentException if the {@link Callable} is <strong>null</strong>
+     * @param callable the object to check.
+     * @throws IllegalArgumentException if the {@link Callable} is <strong>null</strong>.
      */
     private void checkCallable(final Callable<T> callable) {
         Objects.requireNonNull(callable, "callable");
@@ -118,12 +114,10 @@ protected Exception getTypedException(final Exception e) {
     }
 
     /**
-     * Performs initialization in a background thread. This implementation
-     * delegates to the {@link Callable} passed at construction time of this
-     * object.
+     * Performs initialization in a background thread. This implementation delegates to the {@link Callable} passed at construction time of this object.
      *
-     * @return the result of the initialization
-     * @throws Exception if an error occurs
+     * @return the result of the initialization.
+     * @throws Exception if an error occurs.
      */
     @Override
     protected T initialize() throws Exception {
diff --git a/src/main/java/org/apache/commons/lang3/concurrent/LazyInitializer.java b/src/main/java/org/apache/commons/lang3/concurrent/LazyInitializer.java
index 2d4cab13e..a5271eba6 100644
--- a/src/main/java/org/apache/commons/lang3/concurrent/LazyInitializer.java
+++ b/src/main/java/org/apache/commons/lang3/concurrent/LazyInitializer.java
@@ -135,15 +135,14 @@ private LazyInitializer(final FailableSupplier<T, ConcurrentException> initializ
     /**
      * Gets the object wrapped by this instance. On first access the object is created. After that it is cached and can be accessed pretty fast.
      *
-     * @return the object initialized by this {@link LazyInitializer}
-     * @throws ConcurrentException if an error occurred during initialization of the object
+     * @return the object initialized by this {@link LazyInitializer}.
+     * @throws ConcurrentException if an error occurred during initialization of the object.
      */
     @Override
     public T get() throws ConcurrentException {
         // use a temporary variable to reduce the number of reads of the
         // volatile field
         T result = object;
-
         if (result == NO_INIT) {
             synchronized (this) {
                 result = object;
@@ -152,7 +151,6 @@ public T get() throws ConcurrentException {
                 }
             }
         }
-
         return result;
     }
 
diff --git a/src/main/java/org/apache/commons/lang3/concurrent/MultiBackgroundInitializer.java b/src/main/java/org/apache/commons/lang3/concurrent/MultiBackgroundInitializer.java
index e1ce1f84c..631078394 100644
--- a/src/main/java/org/apache/commons/lang3/concurrent/MultiBackgroundInitializer.java
+++ b/src/main/java/org/apache/commons/lang3/concurrent/MultiBackgroundInitializer.java
@@ -93,9 +93,7 @@
  *
  * @since 3.0
  */
-public class MultiBackgroundInitializer
-        extends
-        BackgroundInitializer<MultiBackgroundInitializer.MultiBackgroundInitializerResults> {
+public class MultiBackgroundInitializer extends BackgroundInitializer<MultiBackgroundInitializer.MultiBackgroundInitializerResults> {
 
     /**
      * A data class for storing the results of the background initialization
@@ -118,21 +116,18 @@ public static class MultiBackgroundInitializerResults {
         private final Map<String, ConcurrentException> exceptions;
 
         /**
-         * Creates a new instance of {@link MultiBackgroundInitializerResults}
-         * and initializes it with maps for the {@link BackgroundInitializer}
-         * objects, their result objects and the exceptions thrown by them.
+         * Creates a new instance of {@link MultiBackgroundInitializerResults} and initializes it with maps for the {@link BackgroundInitializer} objects, their
+         * result objects and the exceptions thrown by them.
          *
-         * @param inits the {@link BackgroundInitializer} objects
-         * @param results the result objects
-         * @param excepts the exceptions
+         * @param initializers  the {@link BackgroundInitializer} objects.
+         * @param resultObjects the result objects.
+         * @param exceptions    the exceptions.
          */
-        private MultiBackgroundInitializerResults(
-                final Map<String, BackgroundInitializer<?>> inits,
-                final Map<String, Object> results,
-                final Map<String, ConcurrentException> excepts) {
-            initializers = inits;
-            resultObjects = results;
-            exceptions = excepts;
+        private MultiBackgroundInitializerResults(final Map<String, BackgroundInitializer<?>> initializers, final Map<String, Object> resultObjects,
+                final Map<String, ConcurrentException> exceptions) {
+            this.initializers = initializers;
+            this.resultObjects = resultObjects;
+            this.exceptions = exceptions;
         }
 
         /**
@@ -140,17 +135,15 @@ private MultiBackgroundInitializerResults(
          * throws an exception. If it exists, the associated child initializer
          * is returned.
          *
-         * @param name the name to check
-         * @return the initializer with this name
-         * @throws NoSuchElementException if the name is unknown
+         * @param name the name to check.
+         * @return the initializer with this name.
+         * @throws NoSuchElementException if the name is unknown.
          */
         private BackgroundInitializer<?> checkName(final String name) {
             final BackgroundInitializer<?> init = initializers.get(name);
             if (init == null) {
-                throw new NoSuchElementException(
-                        "No child initializer with name " + name);
+                throw new NoSuchElementException("No child initializer with name " + name);
             }
-
             return init;
         }
 
@@ -160,9 +153,9 @@ private BackgroundInitializer<?> checkName(final String name) {
          * initializer did not throw an exception, the return value is
          * <strong>null</strong>. If the name cannot be resolved, an exception is thrown.
          *
-         * @param name the name of the {@link BackgroundInitializer}
-         * @return the exception thrown by this initializer
-         * @throws NoSuchElementException if the name cannot be resolved
+         * @param name the name of the {@link BackgroundInitializer}.
+         * @return the exception thrown by this initializer.
+         * @throws NoSuchElementException if the name cannot be resolved.
          */
         public ConcurrentException getException(final String name) {
             checkName(name);
@@ -173,9 +166,9 @@ public ConcurrentException getException(final String name) {
          * Gets the {@link BackgroundInitializer} with the given name. If the
          * name cannot be resolved, an exception is thrown.
          *
-         * @param name the name of the {@link BackgroundInitializer}
-         * @return the {@link BackgroundInitializer} with this name
-         * @throws NoSuchElementException if the name cannot be resolved
+         * @param name the name of the {@link BackgroundInitializer}.
+         * @return the {@link BackgroundInitializer} with this name.
+         * @throws NoSuchElementException if the name cannot be resolved.
          */
         public BackgroundInitializer<?> getInitializer(final String name) {
             return checkName(name);
@@ -183,15 +176,12 @@ public BackgroundInitializer<?> getInitializer(final String name) {
 
         /**
          * Gets the result object produced by the {@code
-         * BackgroundInitializer} with the given name. This is the object
-         * returned by the initializer's {@code initialize()} method. If this
-         * {@link BackgroundInitializer} caused an exception, <strong>null</strong> is
-         * returned. If the name cannot be resolved, an exception is thrown.
+         * BackgroundInitializer} with the given name. This is the object returned by the initializer's {@code initialize()} method. If this
+         * {@link BackgroundInitializer} caused an exception, <strong>null</strong> is returned. If the name cannot be resolved, an exception is thrown.
          *
-         * @param name the name of the {@link BackgroundInitializer}
-         * @return the result object produced by this {@code
-         * BackgroundInitializer}
-         * @throws NoSuchElementException if the name cannot be resolved
+         * @param name the name of the {@link BackgroundInitializer}.
+         * @return the result object produced by this {@code BackgroundInitializer}.
+         * @throws NoSuchElementException if the name cannot be resolved.
          */
         public Object getResultObject(final String name) {
             checkName(name);
@@ -199,11 +189,9 @@ public Object getResultObject(final String name) {
         }
 
         /**
-         * Returns a set with the names of all {@link BackgroundInitializer}
-         * objects managed by the {@link MultiBackgroundInitializer}.
+         * Returns a set with the names of all {@link BackgroundInitializer} objects managed by the {@link MultiBackgroundInitializer}.
          *
-         * @return an (unmodifiable) set with the names of the managed {@code
-         * BackgroundInitializer} objects
+         * @return an (unmodifiable) set with the names of the managed {@code BackgroundInitializer} objects.
          */
         public Set<String> initializerNames() {
             return Collections.unmodifiableSet(initializers.keySet());
@@ -213,9 +201,9 @@ public Set<String> initializerNames() {
          * Tests whether the {@link BackgroundInitializer} with the
          * given name caused an exception.
          *
-         * @param name the name of the {@link BackgroundInitializer}
-         * @return a flag whether this initializer caused an exception
-         * @throws NoSuchElementException if the name cannot be resolved
+         * @param name the name of the {@link BackgroundInitializer}.
+         * @return a flag whether this initializer caused an exception.
+         * @throws NoSuchElementException if the name cannot be resolved.
          */
         public boolean isException(final String name) {
             checkName(name);
@@ -226,7 +214,7 @@ public boolean isException(final String name) {
          * Tests whether the whole initialization was successful. This
          * is the case if no child initializer has thrown an exception.
          *
-         * @return a flag whether the initialization was successful
+         * @return a flag whether the initialization was successful.
          */
         public boolean isSuccessful() {
             return exceptions.isEmpty();
@@ -246,30 +234,24 @@ public MultiBackgroundInitializer() {
      * Constructs a new instance of {@link MultiBackgroundInitializer} and
      * initializes it with the given external {@link ExecutorService}.
      *
-     * @param exec the {@link ExecutorService} for executing the background
-     * tasks
+     * @param exec the {@link ExecutorService} for executing the background tasks.
      */
     public MultiBackgroundInitializer(final ExecutorService exec) {
         super(exec);
     }
 
     /**
-     * Adds a new {@link BackgroundInitializer} to this object. When this
-     * {@link MultiBackgroundInitializer} is started, the given initializer will
-     * be processed. This method must not be called after {@link #start()} has
-     * been invoked.
+     * Adds a new {@link BackgroundInitializer} to this object. When this {@link MultiBackgroundInitializer} is started, the given initializer will be
+     * processed. This method must not be called after {@link #start()} has been invoked.
      *
-     * @param name the name of the initializer (must not be <strong>null</strong>)
-     * @param backgroundInitializer the {@link BackgroundInitializer} to add (must not be
-     * <strong>null</strong>)
-     * @throws NullPointerException if either {@code name} or {@code backgroundInitializer}
-     *         is {@code null}
-     * @throws IllegalStateException if {@code start()} has already been called
+     * @param name                  the name of the initializer (must not be <strong>null</strong>).
+     * @param backgroundInitializer the {@link BackgroundInitializer} to add (must not be <strong>null</strong>).
+     * @throws NullPointerException  if either {@code name} or {@code backgroundInitializer} is {@code null}.
+     * @throws IllegalStateException if {@code start()} has already been called.
      */
     public void addInitializer(final String name, final BackgroundInitializer<?> backgroundInitializer) {
         Objects.requireNonNull(name, "name");
         Objects.requireNonNull(backgroundInitializer, "backgroundInitializer");
-
         synchronized (this) {
             if (isStarted()) {
                 throw new IllegalStateException("addInitializer() must not be called after start()!");
@@ -279,15 +261,15 @@ public void addInitializer(final String name, final BackgroundInitializer<?> bac
     }
 
     /**
-     * Calls the closer of all child {@code BackgroundInitializer} objects
+     * Calls the closer of all child {@code BackgroundInitializer} objects.
      *
-     * @throws ConcurrentException throws an ConcurrentException that will have all other exceptions as suppressed exceptions. ConcurrentException thrown by children will be unwrapped.
+     * @throws ConcurrentException throws an ConcurrentException that will have all other exceptions as suppressed exceptions. ConcurrentException thrown by
+     *                             children will be unwrapped.
      * @since 3.14.0
      */
     @Override
     public void close() throws ConcurrentException {
         ConcurrentException exception = null;
-
         for (final BackgroundInitializer<?> child : childInitializers.values()) {
             try {
                 child.close();
@@ -295,7 +277,6 @@ public void close() throws ConcurrentException {
                 if (exception == null) {
                     exception = new ConcurrentException();
                 }
-
                 if (e instanceof ConcurrentException) {
                     // Because ConcurrentException is only created by classes in this package
                     // we can safely unwrap it.
@@ -305,7 +286,6 @@ public void close() throws ConcurrentException {
                 }
             }
         }
-
         if (exception != null) {
             throw exception;
         }
@@ -319,7 +299,7 @@ public void close() throws ConcurrentException {
      * ). Then it adds 1 for the control task that waits for the completion of
      * the children.
      *
-     * @return the number of tasks required for background processing
+     * @return the number of tasks required for background processing.
      */
     @Override
     protected int getTaskCount() {
@@ -333,8 +313,8 @@ protected int getTaskCount() {
      * data. If a child initializer throws a checked exceptions, it is added to
      * the results object. Unchecked exceptions are propagated.
      *
-     * @return the results object
-     * @throws Exception if an error occurs
+     * @return the results object.
+     * @throws Exception if an error occurs.
      */
     @Override
     protected MultiBackgroundInitializerResults initialize() throws Exception {
@@ -343,7 +323,6 @@ protected MultiBackgroundInitializerResults initialize() throws Exception {
             // create a snapshot to operate on
             inits = new HashMap<>(childInitializers);
         }
-
         // start the child initializers
         final ExecutorService exec = getActiveExecutor();
         inits.values().forEach(bi -> {
@@ -353,7 +332,6 @@ protected MultiBackgroundInitializerResults initialize() throws Exception {
             }
             bi.start();
         });
-
         // collect the results
         final Map<String, Object> results = new HashMap<>();
         final Map<String, ConcurrentException> excepts = new HashMap<>();
@@ -364,15 +342,14 @@ protected MultiBackgroundInitializerResults initialize() throws Exception {
                 excepts.put(k, cex);
             }
         });
-
         return new MultiBackgroundInitializerResults(inits, results, excepts);
     }
 
     /**
-     * Tests whether this all child {@code BackgroundInitializer} objects are initialized.
-     * Once initialized, always returns true.
+     * Tests whether this all child {@code BackgroundInitializer} objects are initialized. Once initialized, always returns true.
      *
-     * @return whether all child {@code BackgroundInitializer} objects instance are initialized. Once initialized, always returns true. If there are no child {@code BackgroundInitializer} objects return false.
+     * @return Whether all child {@code BackgroundInitializer} objects instance are initialized. Once initialized, always returns true. If there are no child
+     *         {@code BackgroundInitializer} objects return false.
      * @since 3.14.0
      */
     @Override
@@ -380,7 +357,6 @@ public boolean isInitialized() {
         if (childInitializers.isEmpty()) {
             return false;
         }
-
         return childInitializers.values().stream().allMatch(BackgroundInitializer::isInitialized);
     }
 }
diff --git a/src/test/java/org/apache/commons/lang3/concurrent/BackgroundInitializerTest.java b/src/test/java/org/apache/commons/lang3/concurrent/BackgroundInitializerTest.java
index 0034b7deb..f167cacb3 100644
--- a/src/test/java/org/apache/commons/lang3/concurrent/BackgroundInitializerTest.java
+++ b/src/test/java/org/apache/commons/lang3/concurrent/BackgroundInitializerTest.java
@@ -76,7 +76,7 @@ public CloseableCounter getCloseableCounter() {
          * Records this invocation. Optionally throws an exception or sleeps a
          * while.
          *
-         * @throws Exception in case of an error
+         * @throws Exception in case of an error.
          */
         protected CloseableCounter initializeInternal() throws Exception {
             if (ex != null) {
@@ -140,7 +140,7 @@ protected CloseableCounter initialize() throws Exception {
      * Helper method for checking whether the initialize() method was correctly
      * called. start() must already have been invoked.
      *
-     * @param init the initializer to test
+     * @param init the initializer to test.
      */
     private void checkInitialize(final AbstractBackgroundInitializerTestImpl init) throws ConcurrentException {
         final Integer result = init.get().getInitializeCalls();