Merge cdc2992 into bfc23e3

.gitignore

@@ -0,0 +1,2 @@
+target
+site-content

checkstyle.xml

@@ -27,11 +27,6 @@
 
   <property name="localeLanguage" value="en"/>
 
-  <!-- Verify that EVERY source file has the appropriate license -->
-  <module name="Header">
-    <property name="headerFile" value="${checkstyle.header.file}"/>
-  </module>
-
   <!-- No tabs allowed! -->
   <module name="FileTabCharacter"/>
 

pom.xml

@@ -268,6 +268,19 @@
         <artifactId>cobertura-maven-plugin</artifactId>
         <version>2.7</version>
       </plugin>
+      <plugin>
+          <groupId>org.apache.rat</groupId>
+          <artifactId>apache-rat-plugin</artifactId>
+          <configuration>
+            <excludes>
+              <exclude>src/test/resources/test1</exclude>
+              <exclude>src/test/resources/test2</exclude>
+              <exclude>.checkstyle</exclude>
+              <exclude>.fbprefs</exclude>
+              <exclude>.pmd</exclude>
+            </excludes>
+          </configuration>
+        </plugin>
     </plugins>
   </reporting>
 

src/main/java/org/apache/commons/pool2/PoolUtils.java

@@ -562,6 +562,8 @@ private static Timer getMinIdleTimer() {
      * Timer task that adds objects to the pool until the number of idle
      * instances reaches the configured minIdle. Note that this is not the same
      * as the pool's minIdle setting.
+     *
+     * @param <T> type of objects in the pool
      */
     private static final class ObjectPoolMinIdleTimerTask<T> extends TimerTask {
 
@@ -631,6 +633,9 @@ public String toString() {
      * Timer task that adds objects to the pool until the number of idle
      * instances for the given key reaches the configured minIdle. Note that
      * this is not the same as the pool's minIdle setting.
+     *
+     * @param <K> object pool key type
+     * @param <V> object pool value type
      */
     private static final class KeyedObjectPoolMinIdleTimerTask<K, V> extends
             TimerTask {
@@ -715,6 +720,8 @@ public String toString() {
      * another layer of synchronization will cause liveliness issues or a
      * deadlock.
      * </p>
+     *
+     * @param <T> type of objects in the pool
      */
     private static final class SynchronizedObjectPool<T> implements ObjectPool<T> {
 
@@ -888,6 +895,9 @@ public String toString() {
      * another layer of synchronization will cause liveliness issues or a
      * deadlock.
      * </p>
+     *
+     * @param <K> object pool key type
+     * @param <V> object pool value type
      */
     private static final class SynchronizedKeyedObjectPool<K, V> implements
             KeyedObjectPool<K, V> {
@@ -1103,6 +1113,8 @@ public String toString() {
      * provide proper synchronization such as the pools provided in the Commons
      * Pool library.
      * </p>
+     *
+     * @param <T> pooled object factory type
      */
     private static final class SynchronizedPooledObjectFactory<T> implements
             PooledObjectFactory<T> {
@@ -1216,6 +1228,9 @@ public String toString() {
      * provide proper synchronization such as the pools provided in the Commons
      * Pool library.
      * </p>
+     *
+     * @param <K> pooled object factory key type
+     * @param <V> pooled object factory key value
      */
     private static final class SynchronizedKeyedPooledObjectFactory<K, V>
             implements KeyedPooledObjectFactory<K, V> {
@@ -1399,6 +1414,8 @@ public String toString() {
      * Decorates an object pool, adding "eroding" behavior. Based on the
      * configured {@link #factor erosion factor}, objects returning to the pool
      * may be invalidated instead of being added to idle capacity.
+     *
+     * @param <T> type of objects in the pool
      */
     private static class ErodingObjectPool<T> implements ObjectPool<T> {
         /** Underlying object pool */
@@ -1540,6 +1557,9 @@ public String toString() {
      * Decorates a keyed object pool, adding "eroding" behavior. Based on the
      * configured erosion factor, objects returning to the pool
      * may be invalidated instead of being added to idle capacity.
+     *
+     * @param <K> object pool key type
+     * @param <V> object pool value type
      */
     private static class ErodingKeyedObjectPool<K, V> implements
             KeyedObjectPool<K, V> {
@@ -1750,6 +1770,9 @@ public String toString() {
      * Extends ErodingKeyedObjectPool to allow erosion to take place on a
      * per-key basis. Timing of erosion events is tracked separately for
      * separate keyed pools.
+     *
+     * @param <K> object pool key type
+     * @param <V> object pool value type
      */
     private static final class ErodingPerKeyKeyedObjectPool<K, V> extends
             ErodingKeyedObjectPool<K, V> {

src/main/java/org/apache/commons/pool2/impl/CallStack.java

@@ -35,7 +35,7 @@ public interface CallStack {
      * Prints the current stack trace if available to a PrintWriter. The format is undefined and is primarily useful
      * for debugging issues with {@link PooledObject} usage in user code.
      *
-     * @param writer a PrintWriter to write the curren stack trace to if available
+     * @param writer a PrintWriter to write the current stack trace to if available
      * @return true if a stack trace was available to print or false if nothing was printed
      */
     boolean printStackTrace(final PrintWriter writer);

src/main/java/org/apache/commons/pool2/impl/CallStackUtils.java

@@ -31,6 +31,10 @@ public final class CallStackUtils {
         CAN_CREATE_SECURITY_MANAGER = canCreateSecurityManager();
     }
 
+    /**
+     * @return {@code true} if it is able to create a security manager in the current environment, {@code false}
+     *         otherwise.
+     */
     private static boolean canCreateSecurityManager() {
         final SecurityManager manager = System.getSecurityManager();
         if (manager == null) {
@@ -53,10 +57,13 @@ private static boolean canCreateSecurityManager() {
      * @return a new CallStack
      */
     public static CallStack newCallStack(final String messageFormat, final boolean useTimestamp) {
-        return CAN_CREATE_SECURITY_MANAGER ? new SecurityManagerCallStack(messageFormat, useTimestamp)
-            : new ThrowableCallStack(messageFormat, useTimestamp);
+        return CAN_CREATE_SECURITY_MANAGER ? new SecurityManagerCallStack(messageFormat, useTimestamp) :
+            new ThrowableCallStack(messageFormat, useTimestamp);
     }
 
+    /**
+     * Hidden constructor.
+     */
     private CallStackUtils() {
     }
 }

src/main/java/org/apache/commons/pool2/impl/DefaultPooledObjectInfoMBean.java

@@ -41,7 +41,7 @@ public interface DefaultPooledObjectInfoMBean {
     /**
      * Obtain the time that pooled object was created.
      *
-     * @return The creation time for the pooled object formated as
+     * @return The creation time for the pooled object formatted as
      *         <code>yyyy-MM-dd HH:mm:ss Z</code>
      */
     String getCreateTimeFormatted();

src/main/java/org/apache/commons/pool2/impl/EvictionTimer.java

@@ -27,7 +27,7 @@
  * Provides a shared idle object eviction timer for all pools. This class is
  * currently implemented using {@link ScheduledThreadPoolExecutor}. This
  * implementation may change in any future release. This class keeps track of
- * how many pools are using it. If no pools are using the timer, it is canceled.
+ * how many pools are using it. If no pools are using the timer, it is cancelled.
  * This prevents a thread being left running which, in application server
  * environments, can lead to memory leads and/or prevent applications from
  * shutting down or reloading cleanly.
@@ -106,6 +106,9 @@ static synchronized void cancel(final TimerTask task, final long timeout, final
         }
     }
 
+    /**
+     * Thread factory that creates a thread, with the context classloader from this class.
+     */
     private static class EvictorThreadFactory implements ThreadFactory {
 
         @Override

src/main/java/org/apache/commons/pool2/impl/GenericKeyedObjectPool.java

@@ -1460,6 +1460,8 @@ public Map<String,List<DefaultPooledObjectInfo>> listAllObjects() {
 
     /**
      * Maintains information on the per key queue for a given key.
+     *
+     * @param <S> type of objects in the pool
      */
     private class ObjectDeque<S> {
 

src/main/java/org/apache/commons/pool2/impl/LinkedBlockingDeque.java

@@ -89,7 +89,11 @@ class LinkedBlockingDeque<E> extends AbstractQueue<E>
 
     private static final long serialVersionUID = -387911632671998426L;
 
-    /** Doubly-linked list node class */
+    /**
+     * Doubly-linked list node class.
+     *
+     * @param <E> node item type
+     */
     private static final class Node<E> {
         /**
          * The item, or null if this node has been removed.

src/main/java/org/apache/commons/pool2/impl/SecurityManagerCallStack.java

@@ -43,6 +43,12 @@ public class SecurityManagerCallStack implements CallStack {
 
     private volatile Snapshot snapshot;
 
+    /**
+     * Create a new instance.
+     *
+     * @param messageFormat message format
+     * @param useTimestamp whether to format the dates in the output message or not
+     */
     public SecurityManagerCallStack(final String messageFormat, final boolean useTimestamp) {
         this.messageFormat = messageFormat;
         this.dateFormat = useTimestamp ? new SimpleDateFormat(messageFormat) : null;
@@ -85,7 +91,15 @@ public void clear() {
         snapshot = null;
     }
 
+    /**
+     * A custom security manager.
+     */
     private static class PrivateSecurityManager extends SecurityManager {
+        /**
+         * Get the class stack.
+         *
+         * @return class stack
+         */
         private List<WeakReference<Class<?>>> getCallStack() {
             final Class<?>[] classes = getClassContext();
             final List<WeakReference<Class<?>>> stack = new ArrayList<WeakReference<Class<?>>>(classes.length);
@@ -96,10 +110,18 @@ private List<WeakReference<Class<?>>> getCallStack() {
         }
     }
 
+    /**
+     * A snapshot of a class stack.
+     */
     private static class Snapshot {
         private final long timestamp = System.currentTimeMillis();
         private final List<WeakReference<Class<?>>> stack;
 
+        /**
+         * Create a new snapshot with a class stack.
+         *
+         * @param stack class stack
+         */
         private Snapshot(final List<WeakReference<Class<?>>> stack) {
             this.stack = stack;
         }

src/main/java/org/apache/commons/pool2/impl/ThrowableCallStack.java

@@ -36,6 +36,12 @@ public class ThrowableCallStack implements CallStack {
 
     private volatile Snapshot snapshot;
 
+    /**
+     * Create a new instance.
+     *
+     * @param messageFormat message format
+     * @param useTimestamp whether to format the dates in the output message or not
+     */
     public ThrowableCallStack(final String messageFormat, final boolean useTimestamp) {
         this.messageFormat = messageFormat;
         this.dateFormat = useTimestamp ? new SimpleDateFormat(messageFormat) : null;
@@ -70,6 +76,9 @@ public void clear() {
         snapshot = null;
     }
 
+    /**
+     * A snapshot of a throwable.
+     */
     private static class Snapshot extends Throwable {
         private final long timestamp = System.currentTimeMillis();
     }