You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by ma...@apache.org on 2012/04/24 15:33:22 UTC
svn commit: r1329709 - in
/commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl:
BaseObjectPoolConfig.java GenericKeyedObjectPool.java
GenericKeyedObjectPoolMBean.java GenericObjectPool.java
GenericObjectPoolMBean.java
Author: markt
Date: Tue Apr 24 13:33:22 2012
New Revision: 1329709
URL: http://svn.apache.org/viewvc?rev=1329709&view=rev
Log:
Javadoc for LIFO
- reduce duplication
- use @link / @see rather than copy/paste
Modified:
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/BaseObjectPoolConfig.java
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/GenericKeyedObjectPool.java
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/GenericKeyedObjectPoolMBean.java
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/GenericObjectPool.java
commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/GenericObjectPoolMBean.java
Modified: commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/BaseObjectPoolConfig.java
URL: http://svn.apache.org/viewvc/commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/BaseObjectPoolConfig.java?rev=1329709&r1=1329708&r2=1329709&view=diff
==============================================================================
--- commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/BaseObjectPoolConfig.java (original)
+++ commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/BaseObjectPoolConfig.java Tue Apr 24 13:33:22 2012
@@ -17,20 +17,17 @@
package org.apache.commons.pool2.impl;
/**
- * Provides the common configuration attributes used by object pool
- * configurations.
+ * Provides the implementation for the common attributes shared by the
+ * sub-classes.
* <p>
- * This class is not thread-safe; it is only intended to be used to provide
- * attributes used when creating a pool.
+ * This class is not thread-safe.
*/
public abstract class BaseObjectPoolConfig implements Cloneable {
/**
- * The default LIFO status. True means that borrowObject returns the most
- * recently used ("last in") idle object in the pool (if there are idle
- * instances available). False means that the pool behaves as a FIFO queue -
- * objects are taken from the idle object pool in the order that they are
- * returned to the pool.
+ * The default LIFO status.
+ * @see GenericObjectPool#getLifo()
+ * @see GenericKeyedObjectPool#getLifo()
*/
public static final boolean DEFAULT_LIFO = true;
@@ -96,7 +93,7 @@ public abstract class BaseObjectPoolConf
* The default policy that will be used to evict objects from the pool.
*/
public static final String DEFAULT_EVICTION_POLICY_CLASS_NAME =
- DefaultEvictionPolicy.class.getName();
+ "org.apache.commons.pool2.impl.DefaultEvictionPolicy";
private boolean lifo = DEFAULT_LIFO;
@@ -128,10 +125,20 @@ public abstract class BaseObjectPoolConf
private String jmxNamePrefix = DEFAULT_JMX_NAME_PREFIX;
+ /**
+ * Get the LIFO status for pools created with this configuration instance.
+ * @see GenericObjectPool#getLifo()
+ * @see GenericKeyedObjectPool#getLifo()
+ */
public boolean getLifo() {
return lifo;
}
+ /**
+ * Set the LIFO status for pools created with this configuration instance.
+ * @see GenericObjectPool#getLifo()
+ * @see GenericKeyedObjectPool#getLifo()
+ */
public void setLifo(boolean lifo) {
this.lifo = lifo;
}
Modified: commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/GenericKeyedObjectPool.java
URL: http://svn.apache.org/viewvc/commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/GenericKeyedObjectPool.java?rev=1329709&r1=1329708&r2=1329709&view=diff
==============================================================================
--- commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/GenericKeyedObjectPool.java (original)
+++ commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/GenericKeyedObjectPool.java Tue Apr 24 13:33:22 2012
@@ -188,19 +188,6 @@ import org.apache.commons.pool2.PoolUtil
* </li>
* </ul>
* <p>
- * The pools can be configured to behave as LIFO queues with respect to idle
- * objects - always returning the most recently used object from the pool,
- * or as FIFO queues, where borrowObject always returns the oldest object
- * in the idle object pool.
- * <ul>
- * <li>
- * {@link #setLifo <i>Lifo</i>}
- * determines whether or not the pools return idle objects in
- * last-in-first-out order. The default setting for this parameter is
- * <code>true.</code>
- * </li>
- * </ul>
- * <p>
* GenericKeyedObjectPool is not usable without a {@link KeyedPoolableObjectFactory}. A
* non-<code>null</code> factory must be provided as a constructor argument
* before the pool is used.
@@ -737,6 +724,34 @@ public class GenericKeyedObjectPool<K,T>
}
/**
+ * The pools can be configured to behave as LIFO (last in, first out) queues
+ * with respect to idle objects - always returning the most recently used
+ * object from the pool, or as FIFO (first in, first out) queues, where
+ * {@link #borrowObject(Object)} and {@link #borrowObject(Object, long)}
+ * always return the oldest object in the idle object pool.
+ *
+ * @return <code>true</code> if the pools are configured to act as LIFO
+ * queues or <code>false</code> if the pools are configured to act
+ * as FIFO queues
+ * @since 1.4
+ */
+ @Override
+ public boolean getLifo() {
+ return lifo;
+ }
+
+ /**
+ * Sets the LIFO property of the pools.
+ *
+ * @param lifo the new value for the lifo property
+ * @since 1.4
+ * @see #getLifo()
+ */
+ public void setLifo(boolean lifo) {
+ this.lifo = lifo;
+ }
+
+ /**
* Sets the configuration.
* @param conf the new configuration to use.
* @see GenericKeyedObjectPoolConfig
@@ -761,35 +776,6 @@ public class GenericKeyedObjectPool<K,T>
setEvictionPolicyClassName(conf.getEvictionPolicyClassName());
}
- /**
- * Whether or not the idle object pools act as LIFO queues. True means
- * that borrowObject returns the most recently used ("last in") idle object
- * in a pool (if there are idle instances available). False means that
- * the pools behave as FIFO queues - objects are taken from idle object
- * pools in the order that they are returned.
- *
- * @return <code>true</code> if the pools are configured to act as LIFO queues
- * @since 1.4
- */
- @Override
- public boolean getLifo() {
- return lifo;
- }
-
- /**
- * Sets the LIFO property of the pools. True means that borrowObject returns
- * the most recently used ("last in") idle object in a pool (if there are
- * idle instances available). False means that the pools behave as FIFO
- * queues - objects are taken from idle object pools in the order that
- * they are returned.
- *
- * @param lifo the new value for the lifo property
- * @since 1.4
- */
- public void setLifo(boolean lifo) {
- this.lifo = lifo;
- }
-
/**
* Obtain a reference to the factory used to create, destroy and validate
* the objects used by this pool.
@@ -804,14 +790,16 @@ public class GenericKeyedObjectPool<K,T>
//-- ObjectPool methods ------------------------------------------
/**
- * <p>Borrows an object from the keyed pool associated with the given key.</p>
+ * <p>Borrows an object from the keyed pool associated with the given
+ * key.</p>
*
- * <p>If there is an idle instance available in the pool associated with the given key, then
- * either the most-recently returned (if {@link #getLifo() lifo} == true) or "oldest" (lifo == false)
- * instance sitting idle in the pool will be activated and returned. If activation fails, or
- * {@link #getTestOnBorrow() testOnBorrow} is set to 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 is one or more idle instances available in the pool
+ * associated with the given key, then an idle instance will be selected
+ * based on the value of {@link #getLifo()}, activated and returned. If
+ * activation fails, or {@link #getTestOnBorrow() testOnBorrow} is set to
+ * <code>true</code> 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 pool associated with the given key, behavior
* depends on the {@link #getMaxTotalPerKey() maxTotalPerKey}, {@link #getMaxTotal() maxTotal}, and (if applicable)
@@ -2414,7 +2402,7 @@ public class GenericKeyedObjectPool<K,T>
private volatile long softMinEvictableIdleTimeMillis =
GenericKeyedObjectPoolConfig.DEFAULT_SOFT_MIN_EVICTABLE_IDLE_TIME_MILLIS;
- /** Whether or not the pools behave as LIFO queues (last in first out) */
+ /** Whether or not the pools behave as LIFO queues. */
private boolean lifo = GenericKeyedObjectPoolConfig.DEFAULT_LIFO;
/** My {@link KeyedPoolableObjectFactory}. */
Modified: commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/GenericKeyedObjectPoolMBean.java
URL: http://svn.apache.org/viewvc/commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/GenericKeyedObjectPoolMBean.java?rev=1329709&r1=1329708&r2=1329709&view=diff
==============================================================================
--- commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/GenericKeyedObjectPoolMBean.java (original)
+++ commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/GenericKeyedObjectPoolMBean.java Tue Apr 24 13:33:22 2012
@@ -18,9 +18,15 @@ package org.apache.commons.pool2.impl;
import java.util.Map;
+/**
+ * Defines the methods that will be made available via JMX.
+ */
public interface GenericKeyedObjectPoolMBean<K> {
- // Expose standard attributes via JMX
+ // Expose getters for configuration settings
boolean getBlockWhenExhausted();
+ /**
+ * See {@link GenericKeyedObjectPool#getLifo()}
+ */
boolean getLifo();
int getMaxIdlePerKey();
int getMaxTotal();
@@ -36,7 +42,7 @@ public interface GenericKeyedObjectPoolM
boolean getTestWhileIdle();
long getTimeBetweenEvictionRunsMillis();
boolean isClosed();
- // JMX specific attributes
+ // Expose getters for monitoring attributes
Map<String,Integer> getNumActivePerKey();
long getBorrowedCount();
long getReturnedCount();
Modified: commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/GenericObjectPool.java
URL: http://svn.apache.org/viewvc/commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/GenericObjectPool.java?rev=1329709&r1=1329708&r2=1329709&view=diff
==============================================================================
--- commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/GenericObjectPool.java (original)
+++ commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl/GenericObjectPool.java Tue Apr 24 13:33:22 2012
@@ -157,17 +157,6 @@ import org.apache.commons.pool2.Poolable
* </ul>
* <p>
* <p>
- * The pool can be configured to behave as a LIFO queue with respect to idle
- * objects - always returning the most recently used object from the pool, or as
- * a FIFO queue, where borrowObject always returns the oldest object in the idle
- * object pool.
- * <ul>
- * <li>
- * {@link #setLifo <i>lifo</i>} determines whether or not the pool returns
- * idle objects in last-in-first-out order. The default setting for this
- * parameter is <code>true.</code></li>
- * </ul>
- * <p>
* GenericObjectPool is not usable without a {@link PoolableObjectFactory}. A
* non-<code>null</code> factory must be provided as a constructor
* argument before the pool is used.
@@ -668,13 +657,15 @@ public class GenericObjectPool<T> extend
}
/**
- * Whether or not the idle object pool acts as a LIFO queue. True means that
- * borrowObject returns the most recently used ("last in") idle object in
- * the pool (if there are idle instances available). False means that the
- * pool behaves as a FIFO queue - objects are taken from the idle object
- * pool in the order that they are returned to the pool.
- *
- * @return <code>true</true> if the pool is configured to act as a LIFO queue
+ * The pool can be configured to behave as a LIFO (last in, first out) queue
+ * with respect to idle objects - always returning the most recently used
+ * object from the pool, or as a FIFO (first in, first out) queue, where
+ * {@link #borrowObject} always returns the oldest object in the idle object
+ * pool.
+ *
+ * @return <code>true</true> if the pool is configured to act as a LIFO
+ * queue or <code>false</code> if the pool is configured to act as a
+ * FIFO queue
* @since 1.4
*/
@Override
@@ -683,15 +674,11 @@ public class GenericObjectPool<T> extend
}
/**
- * Sets the LIFO property of the pool. True means that borrowObject returns
- * the most recently used ("last in") idle object in the pool (if there are
- * idle instances available). False means that the pool behaves as a FIFO
- * queue - objects are taken from the idle object pool in the order that
- * they are returned to the pool.
+ * Sets the LIFO property of the pool.
*
- * @param lifo
- * the new value for the LIFO property
+ * @param lifo the new value for the LIFO property
* @since 1.4
+ * @see #getLifo()
*/
public void setLifo(boolean lifo) {
this.lifo = lifo;
@@ -737,18 +724,16 @@ public class GenericObjectPool<T> extend
// -- ObjectPool methods ------------------------------------------
/**
- * <p>
- * Borrows an object from the pool.
- * </p>
- * <p>
- * If there is an idle instance available in the pool, then either the
- * most-recently returned (if {@link #getLifo() lifo} == true) or "oldest"
- * (lifo == false) instance sitting idle in the pool will be activated and
- * returned. If activation fails, or {@link #getTestOnBorrow() testOnBorrow}
- * is set to 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>Borrows an object from the pool.</p>
+ *
+ * <p>If there is one or more idle instance available in the pool, then an
+ * idle instance will be selected based on the value of {@link #getLifo()},
+ * activated and returned. If activation fails, or {@link #getTestOnBorrow()
+ * testOnBorrow} is set to <code>true</code> 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 pool, behavior depends on
* the {@link #getMaxTotal() maxTotal} and (if applicable)
@@ -1726,7 +1711,7 @@ public class GenericObjectPool<T> extend
private volatile long softMinEvictableIdleTimeMillis =
GenericObjectPoolConfig.DEFAULT_SOFT_MIN_EVICTABLE_IDLE_TIME_MILLIS;
- /** Whether or not the pool behaves as a LIFO queue (last in first out) */
+ /** Whether or not the pool behaves as a LIFO queue. */
private volatile boolean lifo = GenericObjectPoolConfig.DEFAULT_LIFO;
/** My {@link PoolableObjectFactory}. */
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=1329709&r1=1329708&r2=1329709&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 Tue Apr 24 13:33:22 2012
@@ -16,9 +16,15 @@
*/
package org.apache.commons.pool2.impl;
+/**
+ * Defines the methods that will be made available via JMX.
+ */
public interface GenericObjectPoolMBean {
- // Expose standard attributes via JMX
+ // Getters for configuration settings
boolean getBlockWhenExhausted();
+ /**
+ * See {@link GenericObjectPool#getLifo()}
+ */
boolean getLifo();
int getMaxIdle();
int getMaxTotal();
@@ -33,7 +39,7 @@ public interface GenericObjectPoolMBean
boolean getTestWhileIdle();
long getTimeBetweenEvictionRunsMillis();
boolean isClosed();
- // JMX specific attributes
+ // Getters for monitoring attributes
long getBorrowedCount();
long getReturnedCount();
long getCreatedCount();
Re: svn commit: r1329709 - in /commons/proper/pool/trunk/src/main/java/org/apache/commons/pool2/impl:
BaseObjectPoolConfig.java GenericKeyedObjectPool.java GenericKeyedObjectPoolMBean.java
GenericObjectPool.java GenericObjectPoolMBean.java
Posted by Mark Thomas <ma...@apache.org>.
On 24/04/2012 14:33, markt@apache.org wrote:
> Author: markt
> Date: Tue Apr 24 13:33:22 2012
> New Revision: 1329709
>
> URL: http://svn.apache.org/viewvc?rev=1329709&view=rev
> Log:
> Javadoc for LIFO
> - reduce duplication
> - use @link / @see rather than copy/paste
My aim is to go through all of the Pool2 Javadoc making changes along
these lines. Broadly, I am trying to:
- ensure things are defined once and once only (no copy/paste although
there are some exceptions where there are slight differences between
GOP and GKOP)
- use @link / @see rather than copy/paste
- ensure GOP and GKOP are consistent where one would expect them to be
consistent
- ensure all public elements have Javadoc even if it just links to a
definition elsewhere
This is going to be a long/slow process so I'd appreciate any objections
at this point rather than towards the conclusion of the work.
Mark
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org