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();