svn commit: r1334503 - /commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/PooledObject.java

[ma...@apache.org]

Author: markt
Date: Sat May  5 20:54:50 2012
New Revision: 1334503

URL: http://svn.apache.org/viewvc?rev=1334503&view=rev
Log:
Fix POOL-220. Update javadoc for compareTo

Modified:
    commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/PooledObject.java

Modified: commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/PooledObject.java
URL: http://svn.apache.org/viewvc/commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/PooledObject.java?rev=1334503&r1=1334502&r2=1334503&view=diff
==============================================================================
--- commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/PooledObject.java (original)
+++ commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/PooledObject.java Sat May  5 20:54:50 2012
@@ -23,7 +23,7 @@ package org.apache.commons.pool2.impl;
  * This class is intended to be thread-safe.
  *
  * @param <T> the type of object in the pool
- * 
+ *
  * @version $Revision: $
  *
  * @since 2.0
@@ -90,12 +90,21 @@ public class PooledObject<T> implements 
         return lastReturnTime;
     }
 
+    /**
+     * Orders instances based on idle time - i.e. the length of time since the
+     * instance was returned to the pool. Used by the GKOP idle object evictor.
+     * <p>
+     * Note: This class has a natural ordering that is inconsistent with
+     *       equals if distinct objects have the same identity hash code.
+     */
     @Override
     public int compareTo(PooledObject<T> other) {
         final long lastActiveDiff =
                 this.getLastReturnTime() - other.getLastReturnTime();
         if (lastActiveDiff == 0) {
-            // make sure the natural ordering is consistent with equals
+            // Make sure the natural ordering is broadly consistent with equals
+            // although this will break down if distinct objects have the same
+            // identity hash code.
             // see java.lang.Comparable Javadocs
             return System.identityHashCode(this) - System.identityHashCode(other);
         }
@@ -144,8 +153,8 @@ public class PooledObject<T> implements 
 
     /**
      * Allocates the object.
-     * 
-     * @return {@code true} if the original state was {@link PooledObjectState#IDLE IDLE} 
+     *
+     * @return {@code true} if the original state was {@link PooledObjectState#IDLE IDLE}
      */
     public synchronized boolean allocate() {
         if (state == PooledObjectState.IDLE) {
@@ -165,7 +174,7 @@ public class PooledObject<T> implements 
     /**
      * Deallocates the object and sets it {@link PooledObjectState#IDLE IDLE}
      * if it is currently {@link PooledObjectState#ALLOCATED ALLOCATED}.
-     * 
+     *
      * @return {@code true} if the state was {@link PooledObjectState#ALLOCATED ALLOCATED}
      */
     public synchronized boolean deallocate() {