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 2021/06/23 14:24:48 UTC
[commons-pool] branch master updated: Javadoc. Close HTML tags.
First paragraph does not need to be in a para. Sentences end in a period.
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-pool.git
The following commit(s) were added to refs/heads/master by this push:
new 95b4f53 Javadoc. Close HTML tags. First paragraph does not need to be in a para. Sentences end in a period.
95b4f53 is described below
commit 95b4f5351f97759d5f8cf0307ca9f89f6c6653b9
Author: Gary Gregory <ga...@gmail.com>
AuthorDate: Wed Jun 23 10:24:44 2021 -0400
Javadoc. Close HTML tags. First paragraph does not need to be in a para.
Sentences end in a period.
---
.../commons/pool2/BasePooledObjectFactory.java | 5 ++--
.../java/org/apache/commons/pool2/PoolUtils.java | 1 +
.../org/apache/commons/pool2/PooledObject.java | 2 +-
.../apache/commons/pool2/impl/AbandonedConfig.java | 16 ++++++------
.../commons/pool2/impl/BaseGenericObjectPool.java | 8 +++---
.../commons/pool2/impl/GenericKeyedObjectPool.java | 20 ++++++++++++++-
.../commons/pool2/impl/GenericObjectPool.java | 6 +++--
.../pool2/impl/InterruptibleReentrantLock.java | 2 +-
.../commons/pool2/impl/LinkedBlockingDeque.java | 29 ++++++++++++++++------
.../commons/pool2/impl/PooledSoftReference.java | 1 +
.../pool2/impl/SoftReferenceObjectPool.java | 3 +++
11 files changed, 65 insertions(+), 28 deletions(-)
diff --git a/src/main/java/org/apache/commons/pool2/BasePooledObjectFactory.java b/src/main/java/org/apache/commons/pool2/BasePooledObjectFactory.java
index d65f01c..6302f17 100644
--- a/src/main/java/org/apache/commons/pool2/BasePooledObjectFactory.java
+++ b/src/main/java/org/apache/commons/pool2/BasePooledObjectFactory.java
@@ -31,6 +31,7 @@ package org.apache.commons.pool2;
* @since 2.0
*/
public abstract class BasePooledObjectFactory<T> extends BaseObject implements PooledObjectFactory<T> {
+
/**
* No-op.
*
@@ -81,7 +82,7 @@ public abstract class BasePooledObjectFactory<T> extends BaseObject implements P
}
/**
- * This implementation always returns {@code true}.
+ * Always returns {@code true}.
*
* @param p ignored
*
@@ -93,7 +94,7 @@ public abstract class BasePooledObjectFactory<T> extends BaseObject implements P
}
/**
- * Wrap the provided instance with an implementation of
+ * Wraps the provided instance with an implementation of
* {@link PooledObject}.
*
* @param obj the instance to wrap
diff --git a/src/main/java/org/apache/commons/pool2/PoolUtils.java b/src/main/java/org/apache/commons/pool2/PoolUtils.java
index bed3257..70c9f37 100644
--- a/src/main/java/org/apache/commons/pool2/PoolUtils.java
+++ b/src/main/java/org/apache/commons/pool2/PoolUtils.java
@@ -1806,6 +1806,7 @@ public final class PoolUtils {
if (pool == null) {
throw new IllegalArgumentException(MSG_NULL_POOL);
}
+
/*
* assert !(pool instanceof GenericObjectPool) :
* "GenericObjectPool is already thread-safe"; assert !(pool instanceof
diff --git a/src/main/java/org/apache/commons/pool2/PooledObject.java b/src/main/java/org/apache/commons/pool2/PooledObject.java
index 19bfc13..83ed7c0 100644
--- a/src/main/java/org/apache/commons/pool2/PooledObject.java
+++ b/src/main/java/org/apache/commons/pool2/PooledObject.java
@@ -296,7 +296,7 @@ public interface PooledObject<T> extends Comparable<PooledObject<T>> {
/**
* Gets a String form of the wrapper for debug purposes. The format is
* not fixed and may change at any time.
- * <p>
+ *
* {@inheritDoc}
*/
@Override
diff --git a/src/main/java/org/apache/commons/pool2/impl/AbandonedConfig.java b/src/main/java/org/apache/commons/pool2/impl/AbandonedConfig.java
index 202e567..6187189 100644
--- a/src/main/java/org/apache/commons/pool2/impl/AbandonedConfig.java
+++ b/src/main/java/org/apache/commons/pool2/impl/AbandonedConfig.java
@@ -222,8 +222,8 @@ public class AbandonedConfig {
}
/**
- * <p>Flag to remove abandoned objects if they exceed the
- * removeAbandonedTimeout when borrowObject is invoked.</p>
+ * Flag to remove abandoned objects if they exceed the
+ * removeAbandonedTimeout when borrowObject is invoked.
*
* @param removeAbandonedOnBorrow true means abandoned objects will be
* removed by borrowObject
@@ -234,8 +234,8 @@ public class AbandonedConfig {
}
/**
- * <p>Flag to remove abandoned objects if they exceed the
- * removeAbandonedTimeout when pool maintenance runs.</p>
+ * Flag to remove abandoned objects if they exceed the
+ * removeAbandonedTimeout when pool maintenance runs.
*
* @param removeAbandonedOnMaintenance true means abandoned objects will be
* removed by pool maintenance
@@ -246,8 +246,8 @@ public class AbandonedConfig {
}
/**
- * <p>Sets the timeout before an abandoned object can be
- * removed</p>
+ * Sets the timeout before an abandoned object can be
+ * removed.
*
* <p>Setting this property has no effect if
* {@link #getRemoveAbandonedOnBorrow() removeAbandonedOnBorrow} and
@@ -263,8 +263,8 @@ public class AbandonedConfig {
}
/**
- * <p>Sets the timeout in seconds before an abandoned object can be
- * removed</p>
+ * Sets the timeout in seconds before an abandoned object can be
+ * removed.
*
* <p>Setting this property has no effect if
* {@link #getRemoveAbandonedOnBorrow() removeAbandonedOnBorrow} and
diff --git a/src/main/java/org/apache/commons/pool2/impl/BaseGenericObjectPool.java b/src/main/java/org/apache/commons/pool2/impl/BaseGenericObjectPool.java
index edc8ab0..000a6eb 100644
--- a/src/main/java/org/apache/commons/pool2/impl/BaseGenericObjectPool.java
+++ b/src/main/java/org/apache/commons/pool2/impl/BaseGenericObjectPool.java
@@ -356,10 +356,8 @@ public abstract class BaseGenericObjectPool<T> extends BaseObject {
final AtomicLong destroyedByBorrowValidationCount = new AtomicLong(0);
private final StatsStore activeTimes = new StatsStore(MEAN_TIMING_STATS_CACHE_SIZE);
-
private final StatsStore idleTimes = new StatsStore(MEAN_TIMING_STATS_CACHE_SIZE);
-
private final StatsStore waitTimes = new StatsStore(MEAN_TIMING_STATS_CACHE_SIZE);
private final AtomicLong maxBorrowWaitTimeMillis = new AtomicLong(0L);
@@ -421,12 +419,12 @@ public abstract class BaseGenericObjectPool<T> extends BaseObject {
abstract void ensureMinIdle() throws Exception;
/**
- * <p>Perform {@code numTests} idle object eviction tests, evicting
+ * Perform {@code numTests} idle object eviction tests, evicting
* examined objects that meet the criteria for eviction. If
* {@code testWhileIdle} is true, examined objects are validated
* when visited (and removed if invalid); otherwise only objects that
* have been idle for more than {@code minEvicableIdleTimeMillis}
- * are removed.</p>
+ * are removed.
*
* @throws Exception when there is a problem evicting idle objects.
*/
@@ -1022,6 +1020,7 @@ public abstract class BaseGenericObjectPool<T> extends BaseObject {
public final void setBlockWhenExhausted(final boolean blockWhenExhausted) {
this.blockWhenExhausted = blockWhenExhausted;
}
+
/**
* Initializes the receiver with the given configuration.
*
@@ -1050,7 +1049,6 @@ public abstract class BaseGenericObjectPool<T> extends BaseObject {
setEvictorShutdownTimeout(config.getEvictorShutdownTimeout());
}
-
// Monitoring (primarily JMX) related methods
/**
diff --git a/src/main/java/org/apache/commons/pool2/impl/GenericKeyedObjectPool.java b/src/main/java/org/apache/commons/pool2/impl/GenericKeyedObjectPool.java
index 9774657..11fd633 100644
--- a/src/main/java/org/apache/commons/pool2/impl/GenericKeyedObjectPool.java
+++ b/src/main/java/org/apache/commons/pool2/impl/GenericKeyedObjectPool.java
@@ -345,7 +345,7 @@ public class GenericKeyedObjectPool<K, T> extends BaseGenericObjectPool<T>
/**
* Equivalent to <code>{@link #borrowObject(Object, long) borrowObject}(key,
* {@link #getMaxWaitDuration()})</code>.
- * <p>
+ *
* {@inheritDoc}
*/
@Override
@@ -366,6 +366,7 @@ public class GenericKeyedObjectPool<K, T> extends BaseGenericObjectPool<T>
* {@code true} and validation fails, the instance is destroyed and the
* next available instance is examined. This continues until either a valid
* instance is returned or there are no more idle instances available.
+ * </p>
* <p>
* If there are no idle instances available in the sub-pool associated with
* the given key, behavior depends on the {@link #getMaxTotalPerKey()
@@ -378,6 +379,7 @@ public class GenericKeyedObjectPool<K, T> extends BaseGenericObjectPool<T>
* instance is created, activated and (if applicable) validated and returned
* to the caller. If validation fails, a {@code NoSuchElementException}
* will be thrown.
+ * </p>
* <p>
* If the associated sub-pool is exhausted (no available idle instances and
* no capacity to create new ones), this method will either block
@@ -387,16 +389,19 @@ public class GenericKeyedObjectPool<K, T> extends BaseGenericObjectPool<T>
* The length of time that this method will block when
* {@link #getBlockWhenExhausted()} is true is determined by the value
* passed in to the {@code borrowMaxWait} parameter.
+ * </p>
* <p>
* When {@code maxTotal} is set to a positive value and this method is
* invoked when at the limit with no idle instances available under the requested
* key, an attempt is made to create room by clearing the oldest 15% of the
* elements from the keyed sub-pools.
+ * </p>
* <p>
* When the pool is exhausted, multiple calling threads may be
* simultaneously blocked waiting for instances to become available. A
* "fairness" algorithm has been implemented to ensure that threads receive
* available instances in request arrival order.
+ * </p>
*
* @param key pool key
* @param borrowMaxWaitMillis The time to wait in milliseconds for an object
@@ -559,6 +564,7 @@ public class GenericKeyedObjectPool<K, T> extends BaseGenericObjectPool<T>
* method on each idle instance.
* <p>
* Implementation notes:
+ * </p>
* <ul>
* <li>This method does not destroy or effect in any way instances that are
* checked out when it is invoked.</li>
@@ -673,6 +679,7 @@ public class GenericKeyedObjectPool<K, T> extends BaseGenericObjectPool<T>
* returned objects destroyed on return.
* <p>
* Destroys idle instances in the pool by invoking {@link #clear()}.
+ * </p>
*/
@Override
public void close() {
@@ -814,6 +821,7 @@ public class GenericKeyedObjectPool<K, T> extends BaseGenericObjectPool<T>
* De-register the use of a key by an object.
* <p>
* register() and deregister() must always be used as a pair.
+ * </p>
*
* @param k The key to de-register
*/
@@ -942,6 +950,7 @@ public class GenericKeyedObjectPool<K, T> extends BaseGenericObjectPool<T>
* Successive activations of this method examine objects in keyed sub-pools
* in sequence, cycling through the keys and examining objects in
* oldest-to-youngest order within the keyed sub-pools.
+ * </p>
*/
@Override
public void evict() throws Exception {
@@ -1153,6 +1162,7 @@ public class GenericKeyedObjectPool<K, T> extends BaseGenericObjectPool<T>
* If the configured value of minIdlePerKey is greater than the configured
* value for maxIdlePerKey then the value of maxIdlePerKey will be used
* instead.
+ * </p>
*
* @return minimum size of the each keyed pool
*
@@ -1380,6 +1390,7 @@ public class GenericKeyedObjectPool<K, T> extends BaseGenericObjectPool<T>
* <p>
* Activation of this method decrements the active count associated with
* the given keyed pool and attempts to destroy {@code obj.}
+ * </p>
*
* @param key pool key
* @param obj instance to invalidate
@@ -1399,6 +1410,7 @@ public class GenericKeyedObjectPool<K, T> extends BaseGenericObjectPool<T>
* <p>
* Activation of this method decrements the active count associated with
* the given keyed pool and attempts to destroy {@code obj.}
+ * </p>
*
* @param key pool key
* @param obj instance to invalidate
@@ -1447,6 +1459,7 @@ public class GenericKeyedObjectPool<K, T> extends BaseGenericObjectPool<T>
* JMX. That means it won't be invoked unless the explicitly requested
* whereas all attributes will be automatically requested when viewing the
* attributes for an object in a tool like JConsole.
+ * </p>
*
* @return Information grouped by key on all the objects in the pool
*/
@@ -1490,6 +1503,7 @@ public class GenericKeyedObjectPool<K, T> extends BaseGenericObjectPool<T>
* Register the use of a key by an object.
* <p>
* register() and deregister() must always be used as a pair.
+ * </p>
*
* @param k The key to register
*
@@ -1577,14 +1591,17 @@ public class GenericKeyedObjectPool<K, T> extends BaseGenericObjectPool<T>
* If {@link #getMaxIdlePerKey() maxIdle} is set to a positive value and the
* number of idle instances under the given key has reached this value, the
* returning instance is destroyed.
+ * </p>
* <p>
* If {@link #getTestOnReturn() testOnReturn} == true, the returning
* instance is validated before being returned to the idle instance sub-pool
* under the given key. In this case, if validation fails, the instance is
* destroyed.
+ * </p>
* <p>
* Exceptions encountered destroying objects for any reason are swallowed
* but notified via a {@link SwallowedExceptionListener}.
+ * </p>
*
* @param key pool key
* @param obj instance to return to the keyed pool
@@ -1807,6 +1824,7 @@ public class GenericKeyedObjectPool<K, T> extends BaseGenericObjectPool<T>
* If the configured value of minIdlePerKey is greater than the configured
* value for maxIdlePerKey then the value of maxIdlePerKey will be used
* instead.
+ * </p>
*
* @param minIdlePerKey The minimum size of the each keyed pool
*
diff --git a/src/main/java/org/apache/commons/pool2/impl/GenericObjectPool.java b/src/main/java/org/apache/commons/pool2/impl/GenericObjectPool.java
index d9fe585..ee27b58 100644
--- a/src/main/java/org/apache/commons/pool2/impl/GenericObjectPool.java
+++ b/src/main/java/org/apache/commons/pool2/impl/GenericObjectPool.java
@@ -224,9 +224,8 @@ public class GenericObjectPool<T> extends BaseGenericObjectPool<T>
/**
* Equivalent to <code>{@link #borrowObject(long)
* borrowObject}({@link #getMaxWaitDuration()})</code>.
- * <p>
+ *
* {@inheritDoc}
- * </p>
*/
@Override
public T borrowObject() throws Exception {
@@ -1201,6 +1200,7 @@ public class GenericObjectPool<T> extends BaseGenericObjectPool<T>
}
updateStatsReturn(activeTime);
}
+
/**
* Sets the abandoned object removal configuration.
*
@@ -1223,6 +1223,7 @@ public class GenericObjectPool<T> extends BaseGenericObjectPool<T>
this.abandonedConfig.setRequireFullStackTrace(abandonedConfig.getRequireFullStackTrace());
}
}
+
/**
* Sets the base pool configuration.
*
@@ -1236,6 +1237,7 @@ public class GenericObjectPool<T> extends BaseGenericObjectPool<T>
setMinIdle(conf.getMinIdle());
setMaxTotal(conf.getMaxTotal());
}
+
/**
* Sets the cap on the number of "idle" instances in the pool. If maxIdle
* is set too low on heavily loaded systems it is possible you will see
diff --git a/src/main/java/org/apache/commons/pool2/impl/InterruptibleReentrantLock.java b/src/main/java/org/apache/commons/pool2/impl/InterruptibleReentrantLock.java
index 1f1b322..c75c547 100644
--- a/src/main/java/org/apache/commons/pool2/impl/InterruptibleReentrantLock.java
+++ b/src/main/java/org/apache/commons/pool2/impl/InterruptibleReentrantLock.java
@@ -45,7 +45,7 @@ class InterruptibleReentrantLock extends ReentrantLock {
}
/**
- * Interrupt the threads that are waiting on a specific condition
+ * Interrupts the threads that are waiting on a specific condition
*
* @param condition the condition on which the threads are waiting.
*/
diff --git a/src/main/java/org/apache/commons/pool2/impl/LinkedBlockingDeque.java b/src/main/java/org/apache/commons/pool2/impl/LinkedBlockingDeque.java
index 69b69cb..142b3e6 100644
--- a/src/main/java/org/apache/commons/pool2/impl/LinkedBlockingDeque.java
+++ b/src/main/java/org/apache/commons/pool2/impl/LinkedBlockingDeque.java
@@ -1028,7 +1028,9 @@ class LinkedBlockingDeque<E> extends AbstractQueue<E>
* Links the provided element as the last in the queue, waiting until there
* is space to do so if the queue is full.
*
- * <p>This method is equivalent to {@link #putLast(Object)}.
+ * <p>
+ * This method is equivalent to {@link #putLast(Object)}.
+ * </p>
*
* @param e element to link
*
@@ -1115,10 +1117,12 @@ class LinkedBlockingDeque<E> extends AbstractQueue<E>
* blocking. This is always equal to the initial capacity of this deque
* less the current {@code size} of this deque.
*
- * <p>Note that you <em>cannot</em> always tell if an attempt to insert
+ * <p>
+ * Note that you <em>cannot</em> always tell if an attempt to insert
* an element will succeed by inspecting {@code remainingCapacity}
* because it may be the case that another thread is about to
* insert or remove an element.
+ * </p>
*
* @return The number of additional elements the queue is able to accept
*/
@@ -1138,7 +1142,9 @@ class LinkedBlockingDeque<E> extends AbstractQueue<E>
* This method differs from {@link #poll poll} only in that it throws an
* exception if this deque is empty.
*
- * <p>This method is equivalent to {@link #removeFirst() removeFirst}.
+ * <p>
+ * This method is equivalent to {@link #removeFirst() removeFirst}.
+ * </p>
*
* @return the head of the queue represented by this deque
* @throws NoSuchElementException if this deque is empty
@@ -1156,8 +1162,10 @@ class LinkedBlockingDeque<E> extends AbstractQueue<E>
* Returns {@code true} if this deque contained the specified element
* (or equivalently, if this deque changed as a result of the call).
*
- * <p>This method is equivalent to
+ * <p>
+ * This method is equivalent to
* {@link #removeFirstOccurrence(Object) removeFirstOccurrence}.
+ * </p>
*
* @param o element to be removed from this deque, if present
* @return {@code true} if this deque changed as a result of the call
@@ -1289,7 +1297,9 @@ class LinkedBlockingDeque<E> extends AbstractQueue<E>
* Unlinks the first element in the queue, waiting until there is an element
* to unlink if the queue is empty.
*
- * <p>This method is equivalent to {@link #takeFirst()}.
+ * <p>
+ * This method is equivalent to {@link #takeFirst()}.
+ * </p>
*
* @return the unlinked element
* @throws InterruptedException if the current thread is interrupted
@@ -1342,12 +1352,15 @@ class LinkedBlockingDeque<E> extends AbstractQueue<E>
* Returns an array containing all of the elements in this deque, in
* proper sequence (from first to last element).
*
- * <p>The returned array will be "safe" in that no references to it are
+ * <p>
+ * The returned array will be "safe" in that no references to it are
* maintained by this deque. (In other words, this method must allocate
* a new array). The caller is thus free to modify the returned array.
- *
- * <p>This method acts as bridge between array-based and collection-based
+ * </p>
+ * <p>
+ * This method acts as bridge between array-based and collection-based
* APIs.
+ * </p>
*
* @return an array containing all of the elements in this deque
*/
diff --git a/src/main/java/org/apache/commons/pool2/impl/PooledSoftReference.java b/src/main/java/org/apache/commons/pool2/impl/PooledSoftReference.java
index 4984cc8..be10346 100644
--- a/src/main/java/org/apache/commons/pool2/impl/PooledSoftReference.java
+++ b/src/main/java/org/apache/commons/pool2/impl/PooledSoftReference.java
@@ -48,6 +48,7 @@ public class PooledSoftReference<T> extends DefaultPooledObject<T> {
* <p>
* Note that if the reference has been cleared, this method will return
* null.
+ * </p>
*
* @return Object referred to by the SoftReference
*/
diff --git a/src/main/java/org/apache/commons/pool2/impl/SoftReferenceObjectPool.java b/src/main/java/org/apache/commons/pool2/impl/SoftReferenceObjectPool.java
index de18fc2..849629f 100644
--- a/src/main/java/org/apache/commons/pool2/impl/SoftReferenceObjectPool.java
+++ b/src/main/java/org/apache/commons/pool2/impl/SoftReferenceObjectPool.java
@@ -93,6 +93,7 @@ public class SoftReferenceObjectPool<T> extends BaseObjectPool<T> {
* generated by the factory {@code makeObject} or
* {@code passivate} are propagated to the caller. Exceptions
* destroying instances are silently swallowed.
+ * </p>
*
* @throws IllegalStateException
* if invoked on a {@link #close() closed} pool
@@ -161,6 +162,7 @@ public class SoftReferenceObjectPool<T> extends BaseObjectPool<T> {
* {@code ThreadDeath} or {@code VirtualMachineError}, exceptions
* generated by activation, validation or destroy methods are swallowed
* silently.
+ * </p>
*
* @throws NoSuchElementException
* if a valid object cannot be provided
@@ -255,6 +257,7 @@ public class SoftReferenceObjectPool<T> extends BaseObjectPool<T> {
* Calling {@link #addObject} or {@link #borrowObject} after invoking this
* method on a pool will cause them to throw an
* {@link IllegalStateException}.
+ * </p>
*/
@Override
public void close() {