Author: markt
Date: Thu May 3 14:44:48 2012
New Revision: 1333481
URL: http://svn.apache.org/viewvc?rev=1333481&view=rev
Log:
Javadoc. Clean up rest of impl package
Modified:
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/GenericObjectPoolMBean.java
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/InterruptibleReentrantLock.java
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/LinkedBlockingDeque.java
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/PooledObject.java
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/SoftReferenceObjectPool.java
Modified:
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/GenericObjectPoolMBean.java
URL:
http://svn.apache.org/viewvc/commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/GenericObjectPoolMBean.java?rev=1333481&r1=1333480&r2=1333481&view=diff
==============================================================================
---
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/GenericObjectPoolMBean.java
(original)
+++
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/GenericObjectPoolMBean.java
Thu May 3 14:44:48 2012
@@ -21,36 +21,117 @@ package org.apache.commons.pool2.impl;
*/
public interface GenericObjectPoolMBean {
// Getters for configuration settings
+ /**
+ * See {@link GenericObjectPool#getBlockWhenExhausted()}
+ */
boolean getBlockWhenExhausted();
/**
* See {@link GenericObjectPool#getLifo()}
*/
boolean getLifo();
+ /**
+ * See {@link GenericObjectPool#getMaxIdle()}
+ */
int getMaxIdle();
+ /**
+ * See {@link GenericObjectPool#getMaxTotal()}
+ */
int getMaxTotal();
+ /**
+ * See {@link GenericObjectPool#getMaxWaitMillis()}
+ */
long getMaxWaitMillis();
+ /**
+ * See {@link GenericObjectPool#getMinEvictableIdleTimeMillis()}
+ */
long getMinEvictableIdleTimeMillis();
+ /**
+ * See {@link GenericObjectPool#getMinIdle()}
+ */
int getMinIdle();
+ /**
+ * See {@link GenericObjectPool#getNumActive()}
+ */
int getNumActive();
+ /**
+ * See {@link GenericObjectPool#getNumIdle()}
+ */
int getNumIdle();
+ /**
+ * See {@link GenericObjectPool#getNumTestsPerEvictionRun()}
+ */
int getNumTestsPerEvictionRun();
+ /**
+ * See {@link GenericObjectPool#getTestOnBorrow()}
+ */
boolean getTestOnBorrow();
+ /**
+ * See {@link GenericObjectPool#getTestOnReturn()}
+ */
boolean getTestOnReturn();
+ /**
+ * See {@link GenericObjectPool#getTestWhileIdle()}
+ */
boolean getTestWhileIdle();
+ /**
+ * See {@link GenericObjectPool#getTimeBetweenEvictionRunsMillis()}
+ */
long getTimeBetweenEvictionRunsMillis();
+ /**
+ * See {@link GenericObjectPool#isClosed()}
+ */
boolean isClosed();
// Getters for monitoring attributes
+ /**
+ * See {@link GenericObjectPool#getBorrowedCount()}
+ */
long getBorrowedCount();
+ /**
+ * See {@link GenericObjectPool#getReturnedCount()}
+ */
long getReturnedCount();
+ /**
+ * See {@link GenericObjectPool#getCreatedCount()}
+ */
long getCreatedCount();
+ /**
+ * See {@link GenericObjectPool#getDestroyedCount()}
+ */
long getDestroyedCount();
+ /**
+ * See {@link GenericObjectPool#getDestroyedByEvictorCount()}
+ */
long getDestroyedByEvictorCount();
+ /**
+ * See {@link GenericObjectPool#getDestroyedByBorrowValidationCount()}
+ */
long getDestroyedByBorrowValidationCount();
+ /**
+ * See {@link GenericObjectPool#getMeanActiveTimeMillis()}
+ */
long getMeanActiveTimeMillis();
+ /**
+ * See {@link GenericObjectPool#getMeanIdleTimeMillis()}
+ */
long getMeanIdleTimeMillis();
+ /**
+ * See {@link GenericObjectPool#getMeanBorrowWaitTimeMillis()}
+ */
long getMeanBorrowWaitTimeMillis();
+ /**
+ * See {@link GenericObjectPool#getMaxBorrowWaitTimeMillis()}
+ */
long getMaxBorrowWaitTimeMillis();
+ /**
+ * See {@link GenericObjectPool#getSwallowedExceptions()}
+ */
String[] getSwallowedExceptions();
+ /**
+ * See {@link GenericObjectPool#getCreationStackTrace()}
+ */
String getCreationStackTrace();
+ /**
+ * See {@link GenericObjectPool#getNumWaiters()}
+ */
int getNumWaiters();
}
Modified:
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/InterruptibleReentrantLock.java
URL:
http://svn.apache.org/viewvc/commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/InterruptibleReentrantLock.java?rev=1333481&r1=1333480&r2=1333481&view=diff
==============================================================================
---
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/InterruptibleReentrantLock.java
(original)
+++
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/InterruptibleReentrantLock.java
Thu May 3 14:44:48 2012
@@ -21,9 +21,13 @@ import java.util.concurrent.locks.Condit
import java.util.concurrent.locks.ReentrantLock;
/**
+ * This sub-class was created to expose the waiting threads so that they can be
+ * interrupted when the pool using the queue that uses this lock is closed. The
+ * class is intended for internal use only.
+ * <p>
* This class is intended to be thread-safe.
*/
-public class InterruptibleReentrantLock extends ReentrantLock {
+class InterruptibleReentrantLock extends ReentrantLock {
private static final long serialVersionUID = 1L;
Modified:
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/LinkedBlockingDeque.java
URL:
http://svn.apache.org/viewvc/commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/LinkedBlockingDeque.java?rev=1333481&r1=1333480&r2=1333481&view=diff
==============================================================================
---
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/LinkedBlockingDeque.java
(original)
+++
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/LinkedBlockingDeque.java
Thu May 3 14:44:48 2012
@@ -14,7 +14,6 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
-
package org.apache.commons.pool2.impl;
import java.util.AbstractQueue;
@@ -51,13 +50,12 @@ import java.util.concurrent.locks.Reentr
* Java Collections Framework</a>.
*
* @param <E> the type of elements held in this collection
- *
+ *
* Note: This was copied from Apache Harmony and modified to suit the needs of
* Commons Pool.
*/
-public class LinkedBlockingDeque<E>
- extends AbstractQueue<E>
- implements java.io.Serializable {
+class LinkedBlockingDeque<E> extends AbstractQueue<E>
+ implements java.io.Serializable {
/*
* Implemented as a simple doubly-linked list protected by a
@@ -1167,13 +1165,13 @@ public class LinkedBlockingDeque<E>
add(item);
}
}
-
+
// Monitoring methods
-
+
/**
* Returns true if there are threads waiting to take instances from this
deque.
* See disclaimer on accuracy in {@link
ReentrantLock#hasWaiters(Condition)}.
- *
+ *
* @return true if there is at least one thread waiting on this deque's
notEmpty condition.
*/
public boolean hasTakeWaiters() {
@@ -1184,11 +1182,11 @@ public class LinkedBlockingDeque<E>
lock.unlock();
}
}
-
+
/**
* Returns the length of the queue of threads waiting to take instances
from this deque.
* See disclaimer on accuracy in {@link
ReentrantLock#getWaitQueueLength(Condition)}.
- *
+ *
* @return number of threads waiting on this deque's notEmpty condition.
*/
public int getTakeQueueLength() {
@@ -1197,7 +1195,7 @@ public class LinkedBlockingDeque<E>
return lock.getWaitQueueLength(notEmpty);
} finally {
lock.unlock();
- }
+ }
}
/**
@@ -1211,6 +1209,6 @@ public class LinkedBlockingDeque<E>
lock.interruptWaiters(notEmpty);
} finally {
lock.unlock();
- }
+ }
}
}
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=1333481&r1=1333480&r2=1333481&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
Thu May 3 14:44:48 2012
@@ -16,7 +16,6 @@
*/
package org.apache.commons.pool2.impl;
-
/**
* This wrapper is used to track the additional information, such as state, for
* the pooled objects.
@@ -34,7 +33,7 @@ public class PooledObject<T> implements
public PooledObject(T object) {
this.object = object;
}
-
+
/**
* Obtain the underlying object that is wrapped by this instance of
* {@link PooledObject}.
@@ -60,14 +59,14 @@ public class PooledObject<T> implements
// Take copies to avoid threading issues
long rTime = lastReturnTime;
long bTime = lastBorrowTime;
-
+
if (rTime > bTime) {
return rTime - bTime;
} else {
return System.currentTimeMillis() - bTime;
}
}
-
+
/**
* Obtain the time in milliseconds that this object last spend in the the
* idle state (it may still be idle in which case subsequent calls will
@@ -76,7 +75,7 @@ public class PooledObject<T> implements
public long getIdleTimeMillis() {
return System.currentTimeMillis() - lastReturnTime;
}
-
+
public long getLastBorrowTime() {
return lastBorrowTime;
}
@@ -118,7 +117,7 @@ public class PooledObject<T> implements
state = PooledObjectState.MAINTAIN_EVICTION;
return true;
}
-
+
return false;
}
@@ -133,7 +132,7 @@ public class PooledObject<T> implements
// TODO - Should never happen
}
}
-
+
return false;
}
Modified:
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/SoftReferenceObjectPool.java
URL:
http://svn.apache.org/viewvc/commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/SoftReferenceObjectPool.java?rev=1333481&r1=1333480&r2=1333481&view=diff
==============================================================================
---
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/SoftReferenceObjectPool.java
(original)
+++
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/SoftReferenceObjectPool.java
Thu May 3 14:44:48 2012
@@ -14,7 +14,6 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
-
package org.apache.commons.pool2.impl;
import java.lang.ref.Reference;
@@ -31,13 +30,12 @@ import org.apache.commons.pool2.PoolUtil
import org.apache.commons.pool2.PoolableObjectFactory;
/**
- * A {@link java.lang.ref.SoftReference SoftReference} based
- * {@link ObjectPool}.
+ * A {@link java.lang.ref.SoftReference SoftReference} based {@link
ObjectPool}.
* <p>
* This class is intended to be thread-safe.
- *
- * @param <T> Type of element pooled in this pool.
*
+ * @param <T>
+ * Type of element pooled in this pool.
* @version $Revision$
* @since Pool 1.0
*/
@@ -45,33 +43,43 @@ public class SoftReferenceObjectPool<T>
/**
* Create a <code>SoftReferenceObjectPool</code> with the specified
factory.
*
- * @param factory object factory to use.
+ * @param factory
+ * object factory to use.
*/
public SoftReferenceObjectPool(PoolableObjectFactory<T> factory) {
_pool = new ArrayList<SoftReference<T>>();
_factory = factory;
}
-
/**
- * <p>Borrow an object from the pool. If there are no idle instances
available in the pool, the configured
- * factory's {@link PoolableObjectFactory#makeObject()} method is invoked
to create a new instance.</p>
- *
- * <p>All instances are {@link
PoolableObjectFactory#activateObject(Object) activated} and
- * {@link PoolableObjectFactory#validateObject(Object) validated} before
being returned by this
- * method. If validation fails or an exception occurs activating or
validating an idle instance,
- * the failing instance is {@link
PoolableObjectFactory#destroyObject(Object) destroyed} and another
- * instance is retrieved from the pool, validated and activated. This
process continues until either the
- * pool is empty or an instance passes validation. If the pool is empty
on activation or
- * it does not contain any valid instances, the factory's
<code>makeObject</code> method is used
- * to create a new instance. If the created instance either raises an
exception on activation or
- * fails validation, <code>NoSuchElementException</code> is thrown.
Exceptions thrown by <code>MakeObject</code>
- * are propagated to the caller; but other than <code>ThreadDeath</code>
or <code>VirtualMachineError</code>,
- * exceptions generated by activation, validation or destroy methods are
swallowed silently.</p>
- *
- * @throws NoSuchElementException if a valid object cannot be provided
- * @throws IllegalStateException if invoked on a {@link #close() closed}
pool
- * @throws Exception if an exception occurs creating a new instance
+ * Borrow an object from the pool. If there are no idle instances available
+ * in the pool, the configured factory's
+ * {@link PoolableObjectFactory#makeObject()} method is invoked to create a
+ * new instance.
+ * <p>
+ * All instances are {@link PoolableObjectFactory#activateObject(Object)
+ * activated} and {@link PoolableObjectFactory#validateObject(Object)
+ * validated} before being returned by this method. If validation fails or
+ * an exception occurs activating or validating an idle instance, the
+ * failing instance is {@link PoolableObjectFactory#destroyObject(Object)
+ * destroyed} and another instance is retrieved from the pool, validated
and
+ * activated. This process continues until either the pool is empty or an
+ * instance passes validation. If the pool is empty on activation or it
does
+ * not contain any valid instances, the factory's <code>makeObject</code>
+ * method is used to create a new instance. If the created instance either
+ * raises an exception on activation or fails validation,
+ * <code>NoSuchElementException</code> is thrown. Exceptions thrown by
+ * <code>MakeObject</code> are propagated to the caller; but other than
+ * <code>ThreadDeath</code> or <code>VirtualMachineError</code>, exceptions
+ * generated by activation, validation or destroy methods are swallowed
+ * silently.
+ *
+ * @throws NoSuchElementException
+ * if a valid object cannot be provided
+ * @throws IllegalStateException
+ * if invoked on a {@link #close() closed} pool
+ * @throws Exception
+ * if an exception occurs creating a new instance
* @return a valid, activated object instance
*/
@Override
@@ -79,9 +87,9 @@ public class SoftReferenceObjectPool<T>
assertOpen();
T obj = null;
boolean newlyCreated = false;
- while(null == obj) {
- if(_pool.isEmpty()) {
- if(null == _factory) {
+ while (null == obj) {
+ if (_pool.isEmpty()) {
+ if (null == _factory) {
throw new NoSuchElementException();
} else {
newlyCreated = true;
@@ -90,7 +98,8 @@ public class SoftReferenceObjectPool<T>
} else {
SoftReference<T> ref = _pool.remove(_pool.size() - 1);
obj = ref.get();
- ref.clear(); // prevent this ref from being enqueued with
refQueue.
+ ref.clear(); // prevent this ref from being enqueued with
+ // refQueue.
}
if (null != _factory && null != obj) {
try {
@@ -110,8 +119,8 @@ public class SoftReferenceObjectPool<T>
}
if (newlyCreated) {
throw new NoSuchElementException(
- "Could not create a validated object, cause: " +
- t.getMessage());
+ "Could not create a validated object, cause: "
+
+ t.getMessage());
}
}
}
@@ -121,29 +130,32 @@ public class SoftReferenceObjectPool<T>
}
/**
- * <p>Returns an instance to the pool after successful validation and
passivation. The returning instance
- * is destroyed if any of the following are true:<ul>
- * <li>the pool is closed</li>
- * <li>{@link PoolableObjectFactory#validateObject(Object) validation}
fails</li>
- * <li>{@link PoolableObjectFactory#passivateObject(Object) passivation}
throws an exception</li>
+ * Returns an instance to the pool after successful validation and
+ * passivation. The returning instance is destroyed if any of the following
+ * are true:
+ * <ul>
+ * <li>the pool is closed</li>
+ * <li>{@link PoolableObjectFactory#validateObject(Object) validation}
fails
+ * </li>
+ * <li>{@link PoolableObjectFactory#passivateObject(Object) passivation}
+ * throws an exception</li>
* </ul>
- *</p>
- *
- * <p>Exceptions passivating or destroying instances are silently
swallowed. Exceptions validating
- * instances are propagated to the client.</p>
- *
- * @param obj instance to return to the pool
+ * Exceptions passivating or destroying instances are silently swallowed.
+ * Exceptions validating instances are propagated to the client.
+ *
+ * @param obj
+ * instance to return to the pool
*/
@Override
public synchronized void returnObject(T obj) throws Exception {
boolean success = !isClosed();
if (_factory != null) {
- if(!_factory.validateObject(obj)) {
+ if (!_factory.validateObject(obj)) {
success = false;
} else {
try {
_factory.passivateObject(obj);
- } catch(Exception e) {
+ } catch (Exception e) {
success = false;
}
}
@@ -151,7 +163,7 @@ public class SoftReferenceObjectPool<T>
boolean shouldDestroy = !success;
_numActive--;
- if(success) {
+ if (success) {
_pool.add(new SoftReference<T>(obj, refQueue));
}
notifyAll(); // _numActive has changed
@@ -159,7 +171,7 @@ public class SoftReferenceObjectPool<T>
if (shouldDestroy && _factory != null) {
try {
_factory.destroyObject(obj);
- } catch(Exception e) {
+ } catch (Exception e) {
// ignored
}
}
@@ -178,52 +190,59 @@ public class SoftReferenceObjectPool<T>
}
/**
- * <p>Create an object, and place it into the pool.
- * addObject() is useful for "pre-loading" a pool with idle objects.</p>
- *
- * <p>Before being added to the pool, the newly created instance is
- * {@link PoolableObjectFactory#validateObject(Object) validated} and
- * {@link PoolableObjectFactory#passivateObject(Object) passivated}. If
validation
- * fails, the new instance is {@link
PoolableObjectFactory#destroyObject(Object) destroyed}.
- * Exceptions generated by the factory <code>makeObject</code> or
<code>passivate</code> are
- * propagated to the caller. Exceptions destroying instances are silently
swallowed.</p>
- *
- * @throws IllegalStateException if invoked on a {@link #close() closed}
pool
- * @throws Exception when the {@link #getFactory() factory} has a problem
creating or passivating an object.
+ * Create an object, and place it into the pool. addObject() is useful for
+ * "pre-loading" a pool with idle objects.
+ * <p>
+ * Before being added to the pool, the newly created instance is
+ * {@link PoolableObjectFactory#validateObject(Object) validated} and
+ * {@link PoolableObjectFactory#passivateObject(Object) passivated}. If
+ * validation fails, the new instance is
+ * {@link PoolableObjectFactory#destroyObject(Object) destroyed}.
Exceptions
+ * generated by the factory <code>makeObject</code> or
+ * <code>passivate</code> are propagated to the caller. Exceptions
+ * destroying instances are silently swallowed.
+ *
+ * @throws IllegalStateException
+ * if invoked on a {@link #close() closed} pool
+ * @throws Exception
+ * when the {@link #getFactory() factory} has a problem
creating
+ * or passivating an object.
*/
@Override
public synchronized void addObject() throws Exception {
assertOpen();
if (_factory == null) {
- throw new IllegalStateException("Cannot add objects without a
factory.");
+ throw new IllegalStateException(
+ "Cannot add objects without a factory.");
}
T obj = _factory.makeObject();
boolean success = true;
- if(!_factory.validateObject(obj)) {
+ if (!_factory.validateObject(obj)) {
success = false;
} else {
_factory.passivateObject(obj);
}
boolean shouldDestroy = !success;
- if(success) {
+ if (success) {
_pool.add(new SoftReference<T>(obj, refQueue));
notifyAll(); // _numActive has changed
}
- if(shouldDestroy) {
+ if (shouldDestroy) {
try {
_factory.destroyObject(obj);
- } catch(Exception e) {
+ } catch (Exception e) {
// ignored
}
}
}
/**
- * Returns an approximation not less than the of the number of idle
instances in the pool.
- *
+ * Returns an approximation not less than the of the number of idle
+ * instances in the pool.
+ *
* @return estimated number of idle instances in the pool
*/
@Override
@@ -247,15 +266,15 @@ public class SoftReferenceObjectPool<T>
*/
@Override
public synchronized void clear() {
- if(null != _factory) {
+ if (null != _factory) {
Iterator<SoftReference<T>> iter = _pool.iterator();
- while(iter.hasNext()) {
+ while (iter.hasNext()) {
try {
T obj = iter.next().get();
- if(null != obj) {
+ if (null != obj) {
_factory.destroyObject(obj);
}
- } catch(Exception e) {
+ } catch (Exception e) {
// ignore error, keep destroying the rest
}
}
@@ -265,14 +284,15 @@ public class SoftReferenceObjectPool<T>
}
/**
- * <p>Close this pool, and free any resources associated with it. Invokes
- * {@link #clear()} to destroy and remove instances in the pool.</p>
- *
- * <p>Calling {@link #addObject} or {@link #borrowObject} after invoking
- * this method on a pool will cause them to throw an
- * {@link IllegalStateException}.</p>
+ * Close this pool, and free any resources associated with it. Invokes
+ * {@link #clear()} to destroy and remove instances in the pool.
+ * <p>
+ * Calling {@link #addObject} or {@link #borrowObject} after invoking this
+ * method on a pool will cause them to throw an
+ * {@link IllegalStateException}.
*
- * @throws Exception never - exceptions clearing the pool are swallowed
+ * @throws Exception
+ * never - exceptions clearing the pool are swallowed
*/
@Override
public void close() throws Exception {
@@ -280,7 +300,7 @@ public class SoftReferenceObjectPool<T>
clear();
}
- /**
+ /**
* If any idle objects were garbage collected, remove their
* {@link Reference} wrappers from the idle object pool.
*/
@@ -294,30 +314,28 @@ public class SoftReferenceObjectPool<T>
}
}
}
-
+
/**
- * Returns the {@link PoolableObjectFactory} used by this pool to create
and manage object instances.
- *
+ * Returns the {@link PoolableObjectFactory} used by this pool to create
and
+ * manage object instances.
+ *
* @return the factory
* @since 1.5.5
*/
- public synchronized PoolableObjectFactory<T> getFactory() {
+ public synchronized PoolableObjectFactory<T> getFactory() {
return _factory;
}
- /** My pool. */
private final List<SoftReference<T>> _pool;
- /** My {@link PoolableObjectFactory}. */
private final PoolableObjectFactory<T> _factory;
/**
- * Queue of broken references that might be able to be removed from
<code>_pool</code>.
- * This is used to help {@link #getNumIdle()} be more accurate with
minimial
- * performance overhead.
+ * Queue of broken references that might be able to be removed from
+ * <code>_pool</code>. This is used to help {@link #getNumIdle()} be more
+ * accurate with minimial performance overhead.
*/
private final ReferenceQueue<T> refQueue = new ReferenceQueue<T>();
- /** Number of active objects. */
- private int _numActive = 0; // @GuardedBy("this")
+ private int _numActive = 0; // @GuardedBy("this")
}
