You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by rw...@apache.org on 2002/01/15 01:07:03 UTC
cvs commit: jakarta-commons/pool/src/java/org/apache/commons/pool BaseKeyedPoolableObjectFactory.java BasePoolableObjectFactory.java KeyedObjectPool.java KeyedObjectPoolFactory.java KeyedPoolableObjectFactory.java ObjectPool.java ObjectPoolFactory.java package.html PoolableObjectFactory.java
rwaldhoff 02/01/14 16:07:03
Modified: pool/src/java/org/apache/commons/pool
BaseKeyedPoolableObjectFactory.java
BasePoolableObjectFactory.java KeyedObjectPool.java
KeyedObjectPoolFactory.java
KeyedPoolableObjectFactory.java ObjectPool.java
ObjectPoolFactory.java package.html
PoolableObjectFactory.java
Log:
javadoc improvements
updating copyright
Revision Changes Path
1.2 +6 -13 jakarta-commons/pool/src/java/org/apache/commons/pool/BaseKeyedPoolableObjectFactory.java
Index: BaseKeyedPoolableObjectFactory.java
===================================================================
RCS file: /home/cvs/jakarta-commons/pool/src/java/org/apache/commons/pool/BaseKeyedPoolableObjectFactory.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- BaseKeyedPoolableObjectFactory.java 14 Apr 2001 16:40:38 -0000 1.1
+++ BaseKeyedPoolableObjectFactory.java 15 Jan 2002 00:07:03 -0000 1.2
@@ -1,7 +1,7 @@
/*
* The Apache Software License, Version 1.1
*
- * Copyright (c) 2001 The Apache Software Foundation. All rights
+ * Copyright (c) 2001-2002 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
@@ -56,22 +56,19 @@
package org.apache.commons.pool;
/**
- * A base implemenation of {@link KeyedPoolableObjectFactory <tt>KeyedPoolableObjectFactory</tt>}.
+ * A base implemenation of {@link KeyedPoolableObjectFactory KeyedPoolableObjectFactory}.
* <p>
* All operations defined here are essentially no-op's.
*
* @author Rodney Waldhoff
- * @version $Id: BaseKeyedPoolableObjectFactory.java,v 1.1 2001/04/14 16:40:38 rwaldhoff Exp $
+ * @version $Revision: 1.2 $ $Date: 2002/01/15 00:07:03 $
*
* @see KeyedPoolableObjectFactory
- * @see BasePoolableObjectFactory
*/
public abstract class BaseKeyedPoolableObjectFactory implements KeyedPoolableObjectFactory {
public abstract Object makeObject(Object key);
- /**
- * No-op.
- */
+ /** No-op. */
public void destroyObject(Object key, Object obj) {
}
@@ -83,15 +80,11 @@
return true;
}
- /**
- * No-op.
- */
+ /** No-op. */
public void activateObject(Object key, Object obj) {
}
- /**
- * No-op.
- */
+ /** No-op. */
public void passivateObject(Object key, Object obj) {
}
}
1.2 +7 -13 jakarta-commons/pool/src/java/org/apache/commons/pool/BasePoolableObjectFactory.java
Index: BasePoolableObjectFactory.java
===================================================================
RCS file: /home/cvs/jakarta-commons/pool/src/java/org/apache/commons/pool/BasePoolableObjectFactory.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- BasePoolableObjectFactory.java 14 Apr 2001 16:40:40 -0000 1.1
+++ BasePoolableObjectFactory.java 15 Jan 2002 00:07:03 -0000 1.2
@@ -1,13 +1,13 @@
/*
- * $Header: /home/cvs/jakarta-commons/pool/src/java/org/apache/commons/pool/BasePoolableObjectFactory.java,v 1.1 2001/04/14 16:40:40 rwaldhoff Exp $
- * $Revision: 1.1 $
- * $Date: 2001/04/14 16:40:40 $
+ * $Header: /home/cvs/jakarta-commons/pool/src/java/org/apache/commons/pool/BasePoolableObjectFactory.java,v 1.2 2002/01/15 00:07:03 rwaldhoff Exp $
+ * $Revision: 1.2 $
+ * $Date: 2002/01/15 00:07:03 $
*
* ====================================================================
*
* The Apache Software License, Version 1.1
*
- * Copyright (c) 1999-2001 The Apache Software Foundation. All rights
+ * Copyright (c) 2001-2002 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
@@ -67,7 +67,7 @@
* All operations defined here are essentially no-op's.
*
* @author Rodney Waldhoff
- * @version $Id: BasePoolableObjectFactory.java,v 1.1 2001/04/14 16:40:40 rwaldhoff Exp $
+ * @version $Revision: 1.2 $ $Date: 2002/01/15 00:07:03 $
*
* @see PoolableObjectFactory
* @see BaseKeyedPoolableObjectFactory
@@ -75,9 +75,7 @@
public abstract class BasePoolableObjectFactory implements PoolableObjectFactory {
public abstract Object makeObject();
- /**
- * No-op.
- */
+ /** No-op. */
public void destroyObject(Object obj) {
}
@@ -89,15 +87,11 @@
return true;
}
- /**
- * No-op.
- */
+ /** No-op. */
public void activateObject(Object obj) {
}
- /**
- * No-op.
- */
+ /** No-op. */
public void passivateObject(Object obj) {
}
}
1.2 +50 -38 jakarta-commons/pool/src/java/org/apache/commons/pool/KeyedObjectPool.java
Index: KeyedObjectPool.java
===================================================================
RCS file: /home/cvs/jakarta-commons/pool/src/java/org/apache/commons/pool/KeyedObjectPool.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- KeyedObjectPool.java 14 Apr 2001 16:40:43 -0000 1.1
+++ KeyedObjectPool.java 15 Jan 2002 00:07:03 -0000 1.2
@@ -1,13 +1,13 @@
/*
- * $Header: /home/cvs/jakarta-commons/pool/src/java/org/apache/commons/pool/KeyedObjectPool.java,v 1.1 2001/04/14 16:40:43 rwaldhoff Exp $
- * $Revision: 1.1 $
- * $Date: 2001/04/14 16:40:43 $
+ * $Header: /home/cvs/jakarta-commons/pool/src/java/org/apache/commons/pool/KeyedObjectPool.java,v 1.2 2002/01/15 00:07:03 rwaldhoff Exp $
+ * $Revision: 1.2 $
+ * $Date: 2002/01/15 00:07:03 $
*
* ====================================================================
*
* The Apache Software License, Version 1.1
*
- * Copyright (c) 1999-2001 The Apache Software Foundation. All rights
+ * Copyright (c) 2001-2002 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
@@ -62,34 +62,37 @@
package org.apache.commons.pool;
/**
- * A simple "keyed" {@link Object} pooling interface.
+ * A "keyed" pooling interface.
* <p>
- * A keyed pool caches mutiple named instances of {@link Object}s.
+ * A keyed pool pools instances of multiple types. Each
+ * type may be accessed using an arbitrary key.
* <p>
* Example of use:
* <table border="1" cellspacing="0" cellpadding="3" align="center" bgcolor="#FFFFFF"><tr><td><pre>
* Object obj = <font color="#0000CC">null</font>;
* Object key = <font color="#CC0000">"Key"</font>;
+ *
* <font color="#0000CC">try</font> {
- * obj = keyedPool.borrowObject(key);
+ * obj = pool.borrowObject(key);
* <font color="#00CC00">//...use the object...</font>
* } <font color="#0000CC">catch</font>(Exception e) {
* <font color="#00CC00">//...handle any exceptions...</font>
* } <font color="#0000CC">finally</font> {
* <font color="#00CC00">// make sure the object is returned to the pool</font>
* <font color="#0000CC">if</font>(<font color="#0000CC">null</font> != obj) {
- * keyedPool.returnObject(key,obj);
+ * pool.returnObject(key,obj);
* }
* }</pre></td></tr></table>
*
* <p>
* {@link KeyedObjectPool} implementations <i>may</i> choose to store at most
* one instance per key value, or may choose to maintain a pool of instances
- * for each key (essentially creating a Map of Pools).
+ * for each key (essentially creating a {@link java.util.Map Map} of
+ * {@link ObjectPool pools}).
* </p>
*
* @author Rodney Waldhoff
- * @version $Id: KeyedObjectPool.java,v 1.1 2001/04/14 16:40:43 rwaldhoff Exp $
+ * @version $Revision: 1.2 $ $Date: 2002/01/15 00:07:03 $
*
* @see KeyedPoolableObjectFactory
* @see KeyedObjectPoolFactory
@@ -97,23 +100,23 @@
*/
public interface KeyedObjectPool {
/**
- * Obtain an <tt>Object</tt> from my pool
- * using the specified <i>key</i>.
+ * Obtain an instance from my pool
+ * for the specified <i>key</i>.
* By contract, clients MUST return
* the borrowed object using
* {@link #returnObject(java.lang.Object,java.lang.Object) <tt>returnObject</tt>},
* or a related method as defined in an implementation
* or sub-interface,
* using a <i>key</i> that is equivalent to the one used to
- * borrow the <tt>Object</tt> in the first place.
+ * borrow the instance in the first place.
*
* @param key the key used to obtain the object
- * @return an <tt>Object</tt> from my pool.
+ * @return an instance from my pool.
*/
public abstract Object borrowObject(Object key);
/**
- * Return an <tt>Object</tt> to my pool.
+ * Return an instance to my pool.
* By contract, <i>obj</i> MUST have been obtained
* using {@link #borrowObject(java.lang.Object) <tt>borrowObject</tt>}
* or a related method as defined in an implementation
@@ -122,68 +125,75 @@
* borrow the <tt>Object</tt> in the first place.
*
* @param key the key used to obtain the object
- * @param obj a {@link #borrowObject(java.lang.Object) borrowed} <tt>Object</tt> to be returned.
+ * @param obj a {@link #borrowObject(java.lang.Object) borrowed} instance to be returned.
*/
public abstract void returnObject(Object key, Object obj);
/**
- * Return the number of <tt>Object</tt>s
+ * Returns the number of instances
* corresponding to the given <i>key</i>
- * currently idle in my pool, or
- * throws {@link UnsupportedOperationException}
+ * currently idle in my pool.
+ * Throws {@link UnsupportedOperationException}
* if this information is not available.
*
* @param key the key
- * @return the number of <tt>Object</tt>s corresponding to the given <i>key</i> currently idle in my pool
- * @throws UnsupportedOperationException
+ * @return the number of instances corresponding to the given <i>key</i> currently idle in my pool
+ * @throws UnsupportedOperationException when this implementation doesn't support the operation
*/
public abstract int numIdle(Object key) throws UnsupportedOperationException;
/**
- * Return the number of <tt>Object</tt>s
- * currently borrowed from my pool corresponding to the
- * given <i>key</i>, or
- * throws {@link UnsupportedOperationException}
+ * Returns the number of instances
+ * currently borrowed from but not yet returned
+ * to my pool corresponding to the
+ * given <i>key</i>.
+ * Throws {@link UnsupportedOperationException}
* if this information is not available.
*
* @param key the key
- * @return the number of <tt>Object</tt>s corresponding to the given <i>key</i> currently borrowed in my pool
- * @throws UnsupportedOperationException
+ * @return the number of instances corresponding to the given <i>key</i> currently borrowed in my pool
+ * @throws UnsupportedOperationException when this implementation doesn't support the operation
*/
public abstract int numActive(Object key) throws UnsupportedOperationException;
/**
- * Return the total number of <tt>Object</tt>s
- * currently idle in my pool, or
- * throws {@link UnsupportedOperationException}
+ * Returns the total number of instances
+ * currently idle in my pool.
+ * Throws {@link UnsupportedOperationException}
* if this information is not available.
*
- * @return the total number of <tt>Object</tt>s currently idle in my pool
- * @throws UnsupportedOperationException
+ * @return the total number of instances currently idle in my pool
+ * @throws UnsupportedOperationException when this implementation doesn't support the operation
*/
public abstract int numIdle() throws UnsupportedOperationException;
/**
- * Return the total number of <tt>Object</tt>s
- * current borrowed from my pool, or
- * throws {@link UnsupportedOperationException}
+ * Returns the total number of instances
+ * current borrowed from my pool but not
+ * yet returned.
+ * Throws {@link UnsupportedOperationException}
* if this information is not available.
*
- * @return the total number of <tt>Object</tt>s currently borrowed in my pool
- * @throws UnsupportedOperationException
+ * @return the total number of instances currently borrowed from my pool
+ * @throws UnsupportedOperationException when this implementation doesn't support the operation
*/
public abstract int numActive() throws UnsupportedOperationException;
/**
- * Clears my pool, or throws {@link UnsupportedOperationException}
+ * Clears my pool, removing all pooled instances.
+ * Throws {@link UnsupportedOperationException}
* if the pool cannot be cleared.
+ * @throws UnsupportedOperationException when this implementation doesn't support the operation
*/
public abstract void clear() throws UnsupportedOperationException;
/**
- * Clears the specified pool, or throws {@link UnsupportedOperationException}
+ * Clears the specified pool, removing all pooled instances
+ * corresponding to the given <i>key</i>.
+ * Throws {@link UnsupportedOperationException}
* if the pool cannot be cleared.
* @param key the key to clear
+ * @throws UnsupportedOperationException when this implementation doesn't support the operation
*/
public abstract void clear(Object key) throws UnsupportedOperationException;
@@ -196,6 +206,8 @@
* Sets the {@link KeyedPoolableObjectFactory factory} I use
* to create new instances.
* @param factory the {@link KeyedPoolableObjectFactory} I use to create new instances.
+ * @throws IllegalStateException when the factory cannot be set at this time
+ * @throws UnsupportedOperationException when this implementation doesn't support the operation
*/
public abstract void setFactory(KeyedPoolableObjectFactory factory) throws IllegalStateException, UnsupportedOperationException;
}
1.2 +7 -7 jakarta-commons/pool/src/java/org/apache/commons/pool/KeyedObjectPoolFactory.java
Index: KeyedObjectPoolFactory.java
===================================================================
RCS file: /home/cvs/jakarta-commons/pool/src/java/org/apache/commons/pool/KeyedObjectPoolFactory.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- KeyedObjectPoolFactory.java 14 Apr 2001 16:40:45 -0000 1.1
+++ KeyedObjectPoolFactory.java 15 Jan 2002 00:07:03 -0000 1.2
@@ -1,13 +1,13 @@
/*
- * $Header: /home/cvs/jakarta-commons/pool/src/java/org/apache/commons/pool/KeyedObjectPoolFactory.java,v 1.1 2001/04/14 16:40:45 rwaldhoff Exp $
- * $Revision: 1.1 $
- * $Date: 2001/04/14 16:40:45 $
+ * $Header: /home/cvs/jakarta-commons/pool/src/java/org/apache/commons/pool/KeyedObjectPoolFactory.java,v 1.2 2002/01/15 00:07:03 rwaldhoff Exp $
+ * $Revision: 1.2 $
+ * $Date: 2002/01/15 00:07:03 $
*
* ====================================================================
*
* The Apache Software License, Version 1.1
*
- * Copyright (c) 1999-2001 The Apache Software Foundation. All rights
+ * Copyright (c) 2001-2002 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
@@ -62,17 +62,17 @@
package org.apache.commons.pool;
/**
- * A simple factory interface for creating {@link KeyedObjectPool}s.
+ * A factory for creating {@link KeyedObjectPool}s.
*
* @author Rodney Waldhoff
- * @version $Id: KeyedObjectPoolFactory.java,v 1.1 2001/04/14 16:40:45 rwaldhoff Exp $
+ * @version $Revision: 1.2 $ $Date: 2002/01/15 00:07:03 $
*
* @see KeyedObjectPool
*/
public interface KeyedObjectPoolFactory {
/**
- * Create and return a new {@link KeyedObjectPool}.
- * @return a new, empty {@link KeyedObjectPool}
+ * Create a new {@link KeyedObjectPool}.
+ * @return a new {@link KeyedObjectPool}
*/
public abstract KeyedObjectPool createPool();
}
1.2 +38 -38 jakarta-commons/pool/src/java/org/apache/commons/pool/KeyedPoolableObjectFactory.java
Index: KeyedPoolableObjectFactory.java
===================================================================
RCS file: /home/cvs/jakarta-commons/pool/src/java/org/apache/commons/pool/KeyedPoolableObjectFactory.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- KeyedPoolableObjectFactory.java 14 Apr 2001 16:40:47 -0000 1.1
+++ KeyedPoolableObjectFactory.java 15 Jan 2002 00:07:03 -0000 1.2
@@ -1,13 +1,13 @@
/*
- * $Header: /home/cvs/jakarta-commons/pool/src/java/org/apache/commons/pool/KeyedPoolableObjectFactory.java,v 1.1 2001/04/14 16:40:47 rwaldhoff Exp $
- * $Revision: 1.1 $
- * $Date: 2001/04/14 16:40:47 $
+ * $Header: /home/cvs/jakarta-commons/pool/src/java/org/apache/commons/pool/KeyedPoolableObjectFactory.java,v 1.2 2002/01/15 00:07:03 rwaldhoff Exp $
+ * $Revision: 1.2 $
+ * $Date: 2002/01/15 00:07:03 $
*
* ====================================================================
*
* The Apache Software License, Version 1.1
*
- * Copyright (c) 1999-2001 The Apache Software Foundation. All rights
+ * Copyright (c) 2001-2002 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
@@ -62,84 +62,84 @@
package org.apache.commons.pool;
/**
- * A simple interface defining life-cycle methods for
- * <tt>Object</tt>s to be used in a
- * {@link KeyedObjectPool <tt>KeyedObjectPool</tt>}.
+ * An interface defining life-cycle methods for
+ * instances to be served by a
+ * {@link KeyedObjectPool KeyedObjectPool}.
* <p>
- * By contract, when an {@link KeyedObjectPool <tt>KeyedObjectPool</tt>}
+ * By contract, when an {@link KeyedObjectPool KeyedObjectPool}
* delegates to a <tt>KeyedPoolableObjectFactory</tt>,
* <ol>
* <li>
- * {@link #makeObject(java.lang.Object) <tt>makeObject</tt>} is called whenever a new <tt>Object</tt>
- * is needed.
+ * {@link #makeObject makeObject}
+ * is called whenever a new instance is needed.
* </li>
* <li>
- * {@link #activateObject(java.lang.Object,java.lang.Object) <tt>activateObject</tt>} is invoked
- * on every <tt>Object</tt> before it is returned from the
- * {@link KeyedObjectPool <tt>KeyedObjectPool</tt>}.
+ * {@link #activateObject activateObject}
+ * is invoked on every instance before it is returned from the
+ * pool.
* </li>
* <li>
- * {@link #passivateObject(java.lang.Object,java.lang.Object) <tt>passivateObject</tt>} is invoked
- * on every <tt>Object</tt> when it is returned to the
- * {@link KeyedObjectPool <tt>KeyedObjectPool</tt>}.
+ * {@link #passivateObject passivateObject}
+ * is invoked on every instance when it is returned to the
+ * pool.
* </li>
* <li>
- * {@link #destroyObject(java.lang.Object,java.lang.Object) <tt>destroyObject</tt>} is invoked
- * on every <tt>Object</tt> when it is being "dropped" from the
- * {@link KeyedObjectPool <tt>KeyedObjectPool</tt>} (whether due to the response from
- * {@link #validateObject(java.lang.Object,java.lang.Object) <tt>validateObject</tt>}, or
- * for reasons specific to the {@link KeyedObjectPool <tt>KeyedObjectPool</tt>} implementation.)
+ * {@link #destroyObject destroyObject}
+ * is invoked on every instance when it is being "dropped" from the
+ * pool (whether due to the response from
+ * {@link #validateObject validateObject}, or
+ * for reasons specific to the pool implementation.)
* </li>
* <li>
- * {@link #validateObject(java.lang.Object,java.lang.Object) <tt>validateObject</tt>} is invoked
- * in an implementation-specific fashion to determine if an <tt>Object</tt>
- * is still valid to be returned by the{@link KeyedObjectPool <tt>KeyedObjectPool</tt>}.
- * It will only be invoked on an {@link #activateObject(java.lang.Object,java.lang.Object) "activated"}
- * <tt>Object</tt>.
+ * {@link #validateObject validateObject}
+ * is invoked in an implementation-specific fashion to determine if an instance
+ * is still valid to be returned by the pool.
+ * It will only be invoked on an {@link #activateObject "activated"}
+ * instance.
* </li>
* </ol>
*
* @author Rodney Waldhoff
- * @version $Id: KeyedPoolableObjectFactory.java,v 1.1 2001/04/14 16:40:47 rwaldhoff Exp $
+ * @version $Revision: 1.2 $ $Date: 2002/01/15 00:07:03 $
*
* @see KeyedObjectPool
*/
public interface KeyedPoolableObjectFactory {
/**
- * Create an Object that can be returned by the pool.
+ * Create an instance that can be served by the pool.
* @param key the key used when constructing the object
- * @return an Object that can be returned by the pool.
+ * @return an instance that can be served by the pool.
*/
public abstract Object makeObject(Object key);
/**
- * Destroy an Object no longer needed by the pool.
- * @param key the key used when selecting the object
- * @param obj the Object to be destroyed
+ * Destroy an instance no longer needed by the pool.
+ * @param key the key used when selecting the instance
+ * @param obj the instance to be destroyed
*/
public abstract void destroyObject(Object key, Object obj);
/**
- * Ensures that the Object is safe to be returned by the pool.
- * Returns <tt>false</tt> if this object should be destroyed.
+ * Ensures that the instance is safe to be returned by the pool.
+ * Returns <tt>false</tt> if this instance should be destroyed.
* @param key the key used when selecting the object
- * @param obj the <tt>Object</tt> to be validated
+ * @param obj the instance to be validated
* @return <tt>false</tt> if this <i>obj</i> is not valid and should
* be dropped from the pool, <tt>true</tt> otherwise.
*/
public abstract boolean validateObject(Object key, Object obj);
/**
- * Reinitialize an Object to be returned by the pool.
+ * Reinitialize an instance to be returned by the pool.
* @param key the key used when selecting the object
- * @param obj the <tt>Object</tt> to be activated
+ * @param obj the instance to be activated
*/
public abstract void activateObject(Object key, Object obj);
/**
- * Uninitialize an Object to be returned to the pool.
+ * Uninitialize an instance to be returned to the pool.
* @param key the key used when selecting the object
- * @param obj the <tt>Object</tt> to be passivated
+ * @param obj the instance to be passivated
*/
public abstract void passivateObject(Object key, Object obj);
}
1.2 +24 -21 jakarta-commons/pool/src/java/org/apache/commons/pool/ObjectPool.java
Index: ObjectPool.java
===================================================================
RCS file: /home/cvs/jakarta-commons/pool/src/java/org/apache/commons/pool/ObjectPool.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- ObjectPool.java 14 Apr 2001 16:40:49 -0000 1.1
+++ ObjectPool.java 15 Jan 2002 00:07:03 -0000 1.2
@@ -1,13 +1,13 @@
/*
- * $Header: /home/cvs/jakarta-commons/pool/src/java/org/apache/commons/pool/ObjectPool.java,v 1.1 2001/04/14 16:40:49 rwaldhoff Exp $
- * $Revision: 1.1 $
- * $Date: 2001/04/14 16:40:49 $
+ * $Header: /home/cvs/jakarta-commons/pool/src/java/org/apache/commons/pool/ObjectPool.java,v 1.2 2002/01/15 00:07:03 rwaldhoff Exp $
+ * $Revision: 1.2 $
+ * $Date: 2002/01/15 00:07:03 $
*
* ====================================================================
*
* The Apache Software License, Version 1.1
*
- * Copyright (c) 1999-2001 The Apache Software Foundation. All rights
+ * Copyright (c) 2001-2002 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
@@ -62,11 +62,12 @@
package org.apache.commons.pool;
/**
- * A simple {@link Object} pooling interface.
+ * A pooling interface.
* <p>
* Example of use:
* <table border="1" cellspacing="0" cellpadding="3" align="center" bgcolor="#FFFFFF"><tr><td><pre>
* Object obj = <font color="#0000CC">null</font>;
+ *
* <font color="#0000CC">try</font> {
* obj = pool.borrowObject();
* <font color="#00CC00">//...use the object...</font>
@@ -80,7 +81,7 @@
* }</pre></td></tr></table>
*
* @author Rodney Waldhoff
- * @version $Id: ObjectPool.java,v 1.1 2001/04/14 16:40:49 rwaldhoff Exp $
+ * @version $Revision: 1.2 $ $Date: 2002/01/15 00:07:03 $
*
* @see KeyedObjectPool
* @see ObjectPoolFactory
@@ -88,50 +89,50 @@
*/
public interface ObjectPool {
/**
- * Obtain an <tt>Object</tt> from my pool.
+ * Obtain an instance from my pool.
* By contract, clients MUST return
- * the borrowed object using
- * {@link #returnObject(java.lang.Object) <tt>returnObject</tt>}
+ * the borrowed instance using
+ * {@link #returnObject(java.lang.Object) returnObject}
* or a related method as defined in an implementation
* or sub-interface.
* <p>
* The behaviour of this method when the pool has been exhausted
* is not specified (although it may be specified by implementations).
*
- * @return an <tt>Object</tt> from my pool.
+ * @return an instance from my pool.
*/
public abstract Object borrowObject();
/**
- * Return an <tt>Object</tt> to my pool.
+ * Return an instance to my pool.
* By contract, <i>obj</i> MUST have been obtained
- * using {@link #borrowObject() <tt>borrowObject</tt>}
+ * using {@link #borrowObject() borrowObject}
* or a related method as defined in an implementation
* or sub-interface.
*
- * @param obj a {@link #borrowObject() borrowed} <tt>Object</tt> to be returned.
+ * @param obj a {@link #borrowObject() borrowed} instance to be returned.
*/
public abstract void returnObject(Object obj);
/**
- * Return the number of <tt>Object</tt>s
- * currently idle in my pool, or
- * throws {@link UnsupportedOperationException}
+ * Return the number of instances
+ * currently idle in my pool.
+ * Throws {@link UnsupportedOperationException}
* if this information is not available.
*
- * @return the number of <tt>Object</tt>s currently idle in my pool
- * @throws UnsupportedOperationException
+ * @return the number of instances currently idle in my pool
+ * @throws UnsupportedOperationException if this implementation does not support the operation
*/
public abstract int numIdle() throws UnsupportedOperationException;
/**
- * Return the number of <tt>Object</tt>s
+ * Return the number of instances
* currently borrowed from my pool, or
* throws {@link UnsupportedOperationException}
* if this information is not available.
*
- * @return the number of <tt>Object</tt>s currently borrowed in my pool
- * @throws UnsupportedOperationException
+ * @return the number of instances currently borrowed in my pool
+ * @throws UnsupportedOperationException if this implementation does not support the operation
*/
public abstract int numActive() throws UnsupportedOperationException;
@@ -140,7 +141,7 @@
* associated resources, or throws {@link UnsupportedOperationException}
* if the pool cannot be cleared.
*
- * @throws UnsupportedOperationException
+ * @throws UnsupportedOperationException if this implementation does not support the operation
*/
public abstract void clear() throws UnsupportedOperationException;
@@ -153,6 +154,8 @@
* Sets the {@link PoolableObjectFactory factory} I use
* to create new instances.
* @param factory the {@link PoolableObjectFactory} I use to create new instances.
+ * @throws IllegalStateException when the factory cannot be set at this time
+ * @throws UnsupportedOperationException if this implementation does not support the operation
*/
public abstract void setFactory(PoolableObjectFactory factory) throws IllegalStateException, UnsupportedOperationException;
}
1.2 +6 -6 jakarta-commons/pool/src/java/org/apache/commons/pool/ObjectPoolFactory.java
Index: ObjectPoolFactory.java
===================================================================
RCS file: /home/cvs/jakarta-commons/pool/src/java/org/apache/commons/pool/ObjectPoolFactory.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- ObjectPoolFactory.java 14 Apr 2001 16:40:50 -0000 1.1
+++ ObjectPoolFactory.java 15 Jan 2002 00:07:03 -0000 1.2
@@ -1,13 +1,13 @@
/*
- * $Header: /home/cvs/jakarta-commons/pool/src/java/org/apache/commons/pool/ObjectPoolFactory.java,v 1.1 2001/04/14 16:40:50 rwaldhoff Exp $
- * $Revision: 1.1 $
- * $Date: 2001/04/14 16:40:50 $
+ * $Header: /home/cvs/jakarta-commons/pool/src/java/org/apache/commons/pool/ObjectPoolFactory.java,v 1.2 2002/01/15 00:07:03 rwaldhoff Exp $
+ * $Revision: 1.2 $
+ * $Date: 2002/01/15 00:07:03 $
*
* ====================================================================
*
* The Apache Software License, Version 1.1
*
- * Copyright (c) 1999-2001 The Apache Software Foundation. All rights
+ * Copyright (c) 2001-2002 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
@@ -62,17 +62,17 @@
package org.apache.commons.pool;
/**
- * A simple factory interface for creating {@link ObjectPool}s.
+ * A factory interface for creating {@link ObjectPool}s.
*
* @author Rodney Waldhoff
- * @version $Id: ObjectPoolFactory.java,v 1.1 2001/04/14 16:40:50 rwaldhoff Exp $
+ * @version $Revision: 1.2 $ $Date: 2002/01/15 00:07:03 $
*
* @see ObjectPool
*/
public interface ObjectPoolFactory {
/**
* Create and return a new {@link ObjectPool}.
- * @return a new, empty {@link ObjectPool}
+ * @return a new {@link ObjectPool}
*/
public abstract ObjectPool createPool();
}
1.2 +36 -23 jakarta-commons/pool/src/java/org/apache/commons/pool/package.html
Index: package.html
===================================================================
RCS file: /home/cvs/jakarta-commons/pool/src/java/org/apache/commons/pool/package.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- package.html 14 Apr 2001 16:40:54 -0000 1.1
+++ package.html 15 Jan 2002 00:07:03 -0000 1.2
@@ -1,40 +1,53 @@
-<!-- $Id: package.html,v 1.1 2001/04/14 16:40:54 rwaldhoff Exp $ -->
+<!-- $Id: package.html,v 1.2 2002/01/15 00:07:03 rwaldhoff Exp $ -->
<html>
<head>
<title>Package Documentation for org.apache.commons.pool</title>
</head>
<body>
<p>
- Generic object pooling API.
+ Object pooling API.
</p>
<p>
- The pool package seperates the way in which objects are pooled
- from the way in which they are created. To use the pooling API, simply
- associate a
- {@link org.apache.commons.pool.PoolableObjectFactory PoolableObjectFactory}
- ({@link org.apache.commons.pool.KeyedPoolableObjectFactory KeyedPoolableObjectFactory})
- implementation with an
- {@link org.apache.commons.pool.ObjectPool ObjectPool}
- ({@link org.apache.commons.pool.KeyedObjectPool KeyedObjectPool})
- implementation.
+ The <code>org.apache.commons.pool</code> package defines a simple
+ interface for a pool of object instances, and a handful of base
+ classes that may be useful when creating pool implementations.
</p>
<p>
- {@link org.apache.commons.pool.ObjectPool ObjectPool} defines a simple
- object pooling interface.
- {@link org.apache.commons.pool.KeyedObjectPool KeyedObjectPool} defines a
- similiar interface for pooling "typed" or "keyed" objects.
+ The <code>pool</code> package itself doesn't define a specific object
+ pooling implementation, but rather a contract that implementations may
+ support in order to be fully interchangeable.
</p>
<p>
- The {@link org.apache.commons.pool.PoolableObjectFactory PoolableObjectFactory}
- interface defines lifecycle methods for instances to be returned from an
- {@link org.apache.commons.pool.ObjectPool ObjectPool}.
- The {@link org.apache.commons.pool.KeyedPoolableObjectFactory KeyedPoolableObjectFactory}
- interface defines similiar methods for instances to be returned from a
- {@link org.apache.commons.pool.KeyedObjectPool KeyedObjectPool}.
+ The <code>pool</code> package separates the way in which instances are
+ pooled from the way in which they are created, resulting in a pair of
+ interfaces:
</p>
+ <dl>
+ <dt>{@link org.apache.commons.pool.ObjectPool ObjectPool}</dt>
+ <dd>
+ defines a simple object pooling interface, with methods for
+ borrowing instances from and returning them to the pool.
+ </dd>
+ <dt>{@link org.apache.commons.pool.PoolableObjectFactory PoolableObjectFactory}</dt>
+ <dd>
+ defines lifecycle methods for object instances contained within a pool.
+ By associating a factory with a pool, the pool can create new object
+ instances as needed.
+ </dd>
+ </dl>
<p>
- The {@link org.apache.commons.pool.impl} package contains several simple
- pool implementations.
+ {@link org.apache.commons.pool.ObjectPoolFactory ObjectPoolFactory}
+ defines a simple factory for <code>ObjectPool</code>s, which may be
+ useful for some applications.
+ </p>
+ <p>
+ The <code>pool</code> package also provides a keyed pool interface,
+ which pools instances of multiple types, accessed according to an
+ arbitrary key. See
+ {@link org.apache.commons.pool.KeyedObjectPool KeyedObjectPool},
+ {@link org.apache.commons.pool.KeyedPoolableObjectFactory KeyedPoolableObjectFactory},
+ and
+ {@link org.apache.commons.pool.KeyedObjectPoolFactory KeyedObjectPoolFactory}.
</p>
</body>
</html>
1.2 +36 -37 jakarta-commons/pool/src/java/org/apache/commons/pool/PoolableObjectFactory.java
Index: PoolableObjectFactory.java
===================================================================
RCS file: /home/cvs/jakarta-commons/pool/src/java/org/apache/commons/pool/PoolableObjectFactory.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- PoolableObjectFactory.java 14 Apr 2001 16:40:53 -0000 1.1
+++ PoolableObjectFactory.java 15 Jan 2002 00:07:03 -0000 1.2
@@ -1,13 +1,13 @@
/*
- * $Header: /home/cvs/jakarta-commons/pool/src/java/org/apache/commons/pool/PoolableObjectFactory.java,v 1.1 2001/04/14 16:40:53 rwaldhoff Exp $
- * $Revision: 1.1 $
- * $Date: 2001/04/14 16:40:53 $
+ * $Header: /home/cvs/jakarta-commons/pool/src/java/org/apache/commons/pool/PoolableObjectFactory.java,v 1.2 2002/01/15 00:07:03 rwaldhoff Exp $
+ * $Revision: 1.2 $
+ * $Date: 2002/01/15 00:07:03 $
*
* ====================================================================
*
* The Apache Software License, Version 1.1
*
- * Copyright (c) 1999-2001 The Apache Software Foundation. All rights
+ * Copyright (c) 2001-2002 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
@@ -62,80 +62,79 @@
package org.apache.commons.pool;
/**
- * A simple interface defining life-cycle methods for
- * <tt>Object</tt>s to be used in an
- * {@link ObjectPool <tt>ObjectPool</tt>}.
+ * An interface defining life-cycle methods for
+ * instances to be used in an
+ * {@link ObjectPool ObjectPool}.
* <p>
- * By contract, when an {@link ObjectPool <tt>ObjectPool</tt>}
+ * By contract, when an {@link ObjectPool ObjectPool}
* delegates to a <tt>PoolableObjectFactory</tt>,
* <ol>
* <li>
- * {@link #makeObject <tt>makeObject</tt>} is called whenever a new <tt>Object</tt>
- * is needed.
+ * {@link #makeObject makeObject}
+ * is called whenever a new instance is needed.
* </li>
* <li>
- * {@link #activateObject(java.lang.Object) <tt>activateObject</tt>} is invoked
- * on every <tt>Object</tt> before it is returned from the
- * {@link ObjectPool}, and before it is {@link #validateObject validated}.
+ * {@link #activateObject activateObject}
+ * is invoked on every instance before it is returned from the
+ * pool.
* </li>
* <li>
- * {@link #passivateObject(java.lang.Object) <tt>passivateObject</tt>} is invoked
- * on every <tt>Object</tt> when it is returned to the
- * {@link ObjectPool <tt>ObjectPool</tt>}.
+ * {@link #passivateObject passivateObject}
+ * is invoked on every instance when it is returned to the
+ * pool.
* </li>
* <li>
- * {@link #destroyObject(java.lang.Object) <tt>destroyObject</tt>} is invoked
- * on every <tt>Object</tt> when it is being "dropped" from the
- * {@link ObjectPool <tt>ObjectPool</tt>} (whether due to the response from
- * {@link #validateObject(java.lang.Object) <tt>validateObject</tt>}, or
- * for reasons specific to the {@link ObjectPool <tt>ObjectPool</tt>} implementation.)
+ * {@link #destroyObject destroyObject}
+ * is invoked on every instance when it is being "dropped" from the
+ * pool (whether due to the response from
+ * {@link #validateObject validateObject}, or
+ * for reasons specific to the pool implementation.)
* </li>
* <li>
- * {@link #validateObject(java.lang.Object) <tt>validateObject</tt>} is invoked
- * in an implementation-specific fashion to determine if an <tt>Object</tt>
- * is still valid to be returned by the {@link ObjectPool <tt>ObjectPool</tt>}.
- * It will only be invoked on an {@link #activateObject(java.lang.Object) "activated"}
- * <tt>Object</tt>.
+ * {@link #validateObject validateObject}
+ * is invoked in an implementation-specific fashion to determine if an instance
+ * is still valid to be returned by the pool.
+ * It will only be invoked on an {@link #activateObject "activated"}
+ * instance.
* </li>
* </ol>
*
- *
* @author Rodney Waldhoff
- * @version $Id: PoolableObjectFactory.java,v 1.1 2001/04/14 16:40:53 rwaldhoff Exp $
+ * @version $Revision: 1.2 $ $Date: 2002/01/15 00:07:03 $
*
* @see ObjectPool
*/
public interface PoolableObjectFactory {
/**
- * Creates an Object that can be returned by the pool.
- * @return an Object that can be returned by the pool.
+ * Creates an instance that can be returned by the pool.
+ * @return an instance that can be returned by the pool.
*/
public abstract Object makeObject();
/**
- * Destroys an Object no longer needed by the pool.
- * @param obj the <tt>Object</tt> to be destroyed
+ * Destroys an instance no longer needed by the pool.
+ * @param obj the instance to be destroyed
*/
public abstract void destroyObject(Object obj);
/**
- * Ensures that the Object is safe to be returned by the pool.
+ * Ensures that the instance is safe to be returned by the pool.
* Returns <tt>false</tt> if this object should be destroyed.
- * @param obj the <tt>Object</tt> to be validated
+ * @param obj the instance to be validated
* @return <tt>false</tt> if this <i>obj</i> is not valid and should
* be dropped from the pool, <tt>true</tt> otherwise.
*/
public abstract boolean validateObject(Object obj);
/**
- * Reinitialize an Object to be returned by the pool.
- * @param obj the <tt>Object</tt> to be activated
+ * Reinitialize an instance to be returned by the pool.
+ * @param obj the instance to be activated
*/
public abstract void activateObject(Object obj);
/**
- * Uninitialize an Object to be returned to the pool.
- * @param obj the <tt>Object</tt> to be passivated
+ * Uninitialize an instance to be returned to the pool.
+ * @param obj the instance to be passivated
*/
public abstract void passivateObject(Object obj);
}
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>