rwaldhoff 02/04/29 05:11:30
Modified: pool/src/java/org/apache/commons/pool ObjectPool.java
pool/src/java/org/apache/commons/pool/impl
GenericObjectPool.java SoftReferenceObjectPool.java
StackObjectPool.java
pool/xdocs index.xml
Added: pool/src/java/org/apache/commons/pool BaseObjectPool.java
Log:
add BaseObjectPool
use it in the various impls
add some docs
Revision Changes Path
1.5 +8 -7
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.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- ObjectPool.java 28 Apr 2002 21:52:43 -0000 1.4
+++ ObjectPool.java 29 Apr 2002 12:11:30 -0000 1.5
@@ -1,7 +1,7 @@
/*
- * $Header:
/home/cvs/jakarta-commons/pool/src/java/org/apache/commons/pool/ObjectPool.java,v 1.4
2002/04/28 21:52:43 rwaldhoff Exp $
- * $Revision: 1.4 $
- * $Date: 2002/04/28 21:52:43 $
+ * $Header:
/home/cvs/jakarta-commons/pool/src/java/org/apache/commons/pool/ObjectPool.java,v 1.5
2002/04/29 12:11:30 rwaldhoff Exp $
+ * $Revision: 1.5 $
+ * $Date: 2002/04/29 12:11:30 $
*
* ====================================================================
*
@@ -64,6 +64,9 @@
/**
* A pooling interface.
* <p>
+ * <code>ObjectPool</code> defines a trivially simple pooling interface. The only
+ * required methods are {@link #borrowObject borrowObject} and {@link #returnObject
returnObject}.
+ * <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>;
@@ -79,13 +82,11 @@
* pool.returnObject(obj);
* }
* }</pre></td></tr></table>
+ * See {@link org.apache.commons.pool.impl.BaseObjectPool BaseObjectPool} for a
simple base implementation.
*
* @author Rodney Waldhoff
- * @version $Revision: 1.4 $ $Date: 2002/04/28 21:52:43 $
+ * @version $Revision: 1.5 $ $Date: 2002/04/29 12:11:30 $
*
- * @see KeyedObjectPool
- * @see ObjectPoolFactory
- * @see PoolableObjectFactory
*/
public interface ObjectPool {
/**
1.1
jakarta-commons/pool/src/java/org/apache/commons/pool/BaseObjectPool.java
Index: BaseObjectPool.java
===================================================================
/*
* $Header:
/home/cvs/jakarta-commons/pool/src/java/org/apache/commons/pool/BaseObjectPool.java,v
1.1 2002/04/29 12:11:30 rwaldhoff Exp $
* $Revision: 1.1 $
* $Date: 2002/04/29 12:11:30 $
*
* ====================================================================
*
* The Apache Software License, Version 1.1
*
* Copyright (c) 1999-2001 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
*
* 3. The end-user documentation included with the redistribution, if
* any, must include the following acknowlegement:
* "This product includes software developed by the
* Apache Software Foundation (http://www.apache.org/)."
* Alternately, this acknowlegement may appear in the software itself,
* if and wherever such third-party acknowlegements normally appear.
*
* 4. The names "The Jakarta Project", "Commons", and "Apache Software
* Foundation" must not be used to endorse or promote products derived
* from this software without prior written permission. For written
* permission, please contact [EMAIL PROTECTED]
*
* 5. Products derived from this software may not be called "Apache"
* nor may "Apache" appear in their names without prior written
* permission of the Apache Group.
*
* THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
* USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
* ====================================================================
*
* This software consists of voluntary contributions made by many
* individuals on behalf of the Apache Software Foundation. For more
* information on the Apache Software Foundation, please see
* <http://www.apache.org/>.
*
*/
package org.apache.commons.pool;
/**
* A simple base impementation of {@link ObjectPool}.
* All optional operations are implemented as throwing
* {@link UnsupportedOperationException}.
*
* @author Rodney Waldhoff
* @version $Revision: 1.1 $ $Date: 2002/04/29 12:11:30 $
*/
public abstract class BaseObjectPool implements ObjectPool {
public abstract Object borrowObject() throws Exception;
public abstract void returnObject(Object obj) throws Exception;
/**
* Not supported in this base implementation.
*/
public int numIdle() throws UnsupportedOperationException {
throw new UnsupportedOperationException();
}
/**
* Not supported in this base implementation.
*/
public int numActive() throws UnsupportedOperationException {
throw new UnsupportedOperationException();
}
/**
* Not supported in this base implementation.
*/
public void clear() throws Exception, UnsupportedOperationException {
throw new UnsupportedOperationException();
}
/**
* Not supported in this base implementation.
*/
public void close() throws Exception {
}
/**
* Not supported in this base implementation.
*/
public void setFactory(PoolableObjectFactory factory) throws
IllegalStateException, UnsupportedOperationException {
throw new UnsupportedOperationException();
}
}
1.4 +6 -6
jakarta-commons/pool/src/java/org/apache/commons/pool/impl/GenericObjectPool.java
Index: GenericObjectPool.java
===================================================================
RCS file:
/home/cvs/jakarta-commons/pool/src/java/org/apache/commons/pool/impl/GenericObjectPool.java,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- GenericObjectPool.java 22 Apr 2002 23:43:18 -0000 1.3
+++ GenericObjectPool.java 29 Apr 2002 12:11:30 -0000 1.4
@@ -1,13 +1,13 @@
/*
- * $Header:
/home/cvs/jakarta-commons/pool/src/java/org/apache/commons/pool/impl/GenericObjectPool.java,v
1.3 2002/04/22 23:43:18 rwaldhoff Exp $
- * $Revision: 1.3 $
- * $Date: 2002/04/22 23:43:18 $
+ * $Header:
/home/cvs/jakarta-commons/pool/src/java/org/apache/commons/pool/impl/GenericObjectPool.java,v
1.4 2002/04/29 12:11:30 rwaldhoff Exp $
+ * $Revision: 1.4 $
+ * $Date: 2002/04/29 12:11:30 $
*
* ====================================================================
*
* The Apache Software License, Version 1.1
*
- * Copyright (c) 1999-2001 The Apache Software Foundation. All rights
+ * Copyright (c) 1999-2002 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
@@ -159,9 +159,9 @@
* </ul>
* @see GenericKeyedObjectPool
* @author Rodney Waldhoff
- * @version $Id: GenericObjectPool.java,v 1.3 2002/04/22 23:43:18 rwaldhoff Exp $
+ * @version $Revision: 1.4 $ $Date: 2002/04/29 12:11:30 $
*/
-public class GenericObjectPool implements ObjectPool {
+public class GenericObjectPool extends BaseObjectPool implements ObjectPool {
//--- public constants -------------------------------------------
1.4 +6 -5
jakarta-commons/pool/src/java/org/apache/commons/pool/impl/SoftReferenceObjectPool.java
Index: SoftReferenceObjectPool.java
===================================================================
RCS file:
/home/cvs/jakarta-commons/pool/src/java/org/apache/commons/pool/impl/SoftReferenceObjectPool.java,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- SoftReferenceObjectPool.java 22 Apr 2002 23:43:18 -0000 1.3
+++ SoftReferenceObjectPool.java 29 Apr 2002 12:11:30 -0000 1.4
@@ -1,7 +1,7 @@
/*
- * $Header:
/home/cvs/jakarta-commons/pool/src/java/org/apache/commons/pool/impl/SoftReferenceObjectPool.java,v
1.3 2002/04/22 23:43:18 rwaldhoff Exp $
- * $Revision: 1.3 $
- * $Date: 2002/04/22 23:43:18 $
+ * $Header:
/home/cvs/jakarta-commons/pool/src/java/org/apache/commons/pool/impl/SoftReferenceObjectPool.java,v
1.4 2002/04/29 12:11:30 rwaldhoff Exp $
+ * $Revision: 1.4 $
+ * $Date: 2002/04/29 12:11:30 $
*
* ====================================================================
*
@@ -62,6 +62,7 @@
package org.apache.commons.pool.impl;
import org.apache.commons.pool.ObjectPool;
+import org.apache.commons.pool.BaseObjectPool;
import org.apache.commons.pool.PoolableObjectFactory;
import java.util.List;
import java.util.ArrayList;
@@ -74,9 +75,9 @@
* {@link ObjectPool}.
*
* @author Rodney Waldhoff
- * @version $Revision: 1.3 $ $Date: 2002/04/22 23:43:18 $
+ * @version $Revision: 1.4 $ $Date: 2002/04/29 12:11:30 $
*/
-public class SoftReferenceObjectPool implements ObjectPool {
+public class SoftReferenceObjectPool extends BaseObjectPool implements ObjectPool {
public SoftReferenceObjectPool() {
_pool = new ArrayList();
_factory = null;
1.4 +6 -6
jakarta-commons/pool/src/java/org/apache/commons/pool/impl/StackObjectPool.java
Index: StackObjectPool.java
===================================================================
RCS file:
/home/cvs/jakarta-commons/pool/src/java/org/apache/commons/pool/impl/StackObjectPool.java,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- StackObjectPool.java 22 Apr 2002 23:43:18 -0000 1.3
+++ StackObjectPool.java 29 Apr 2002 12:11:30 -0000 1.4
@@ -1,13 +1,13 @@
/*
- * $Header:
/home/cvs/jakarta-commons/pool/src/java/org/apache/commons/pool/impl/StackObjectPool.java,v
1.3 2002/04/22 23:43:18 rwaldhoff Exp $
- * $Revision: 1.3 $
- * $Date: 2002/04/22 23:43:18 $
+ * $Header:
/home/cvs/jakarta-commons/pool/src/java/org/apache/commons/pool/impl/StackObjectPool.java,v
1.4 2002/04/29 12:11:30 rwaldhoff Exp $
+ * $Revision: 1.4 $
+ * $Date: 2002/04/29 12:11:30 $
*
* ====================================================================
*
* The Apache Software License, Version 1.1
*
- * Copyright (c) 1999-2001 The Apache Software Foundation. All rights
+ * Copyright (c) 1999-2002 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
@@ -79,9 +79,9 @@
* artificial limits.
*
* @author Rodney Waldhoff
- * @version $Id: StackObjectPool.java,v 1.3 2002/04/22 23:43:18 rwaldhoff Exp $
+ * @version $Revision: 1.4 $ $Date: 2002/04/29 12:11:30 $
*/
-public class StackObjectPool implements ObjectPool {
+public class StackObjectPool extends BaseObjectPool implements ObjectPool {
/**
* Create a new pool using
* no factory. Clients must first populate the pool
1.3 +122 -2 jakarta-commons/pool/xdocs/index.xml
Index: index.xml
===================================================================
RCS file: /home/cvs/jakarta-commons/pool/xdocs/index.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- index.xml 23 Apr 2002 00:08:53 -0000 1.2
+++ index.xml 29 Apr 2002 12:11:30 -0000 1.3
@@ -4,7 +4,7 @@
<title>Home</title>
<author email="[EMAIL PROTECTED]">Commons Documentation
Team</author>
<author email="[EMAIL PROTECTED]">Rodney Waldhoff</author>
- <revision>$Id: index.xml,v 1.2 2002/04/23 00:08:53 rwaldhoff Exp $</revision>
+ <revision>$Id: index.xml,v 1.3 2002/04/29 12:11:30 rwaldhoff Exp $</revision>
</properties>
<body>
@@ -18,5 +18,125 @@
See the <a href="downloads.html">downloads</a> page for information on
obtaining releases.
</p>
</section>
+ <section name="Features">
+ <p>
+ The
+ <a
href="http://nagoya.apache.org/gump/javadoc/jakarta-commons/pool/dist/docs/api/org/apache/commons/pool/package-summary.html";>org.apache.commons.pool</a>
+ package defines a handful of pooling interfaces and some base classes
+ that may be useful when creating new pool implementations.
+ </p>
+ <subsection name="ObjectPool">
+ <p>
+ <a
href="http://nagoya.apache.org/gump/javadoc/jakarta-commons/pool/dist/docs/api/org/apache/commons/pool/ObjectPool.html";><code>ObjectPool</code></a>
+ defines a trivially simple pooling interface:
+ </p>
+ <pre>
+ public interface ObjectPool {
+ Object borrowObject();
+ void returnObject(Object borrowed);
+ }
+ </pre>
+ <p>
+ Some client classes won't integrate with <i>Pool</i> any more than this.
+ Clients written to this interface can use arbitrary
<code>ObjectPool</code>
+ implementations interchangeably.
+ </p>
+ <p>
+ <a
href="http://nagoya.apache.org/gump/javadoc/jakarta-commons/pool/dist/docs/api/org/apache/commons/pool/BaseObjectPool.html";><code>BaseObjectPool</code></a>
+ provides an abstract base implementation of <code>ObjectPool</code>.
Clients are
+ encouraged but not required to extend <code>BaseObjectPool</code> for
new
+ <code>ObjectPool</code> implementations.
+ </p>
+ <p>
+ <a
href="http://nagoya.apache.org/gump/javadoc/jakarta-commons/pool/dist/docs/api/org/apache/commons/pool/KeyedObjectPool.html";><code>KeyedObjectPool</code></a>
+ defines a similiar interface for pools composed of heterogenous
objects:
+ </p>
+ <pre>
+ public interface KeyedObjectPool {
+ Object borrowObject(Object key);
+ void returnObject(Object key, Object borrowed);
+ }
+ </pre>
+ </subsection>
+ <subsection name="PoolableObjectFactory">
+ <p>
+ The <i>Pool</i> package makes it possible separate the way in which
instances
+ are pooled from the way in which instances are created and destroyed.
+ <a
href="http://nagoya.apache.org/gump/javadoc/jakarta-commons/pool/dist/docs/api/org/apache/commons/pool/PoolableObjectFactory.html";><code>PoolableObjectFactory</code></a>
+ supports this by providing a generic inteface for the lifecycle of a
pooled object:
+ </p>
+ <pre>
+ public interface PoolableObjectFactory {
+ Object makeObject();
+ void activateObject(Object obj);
+ void passivateObject(Object obj);
+ boolean validateObject(Object obj);
+ void destroyObject(Object obj);
+ }
+ </pre>
+ <p>
+ <code>ObjectPool</code> implementations may be written to accept
arbitrary
+ <code>PoolableObjectFactory</code>s.
+ This makes is possible for clients to select pooling-behavior distinct
+ from the kinds of objects that are pooled.
+ </p>
+ <p>
+ <a
href="http://nagoya.apache.org/gump/javadoc/jakarta-commons/pool/dist/docs/api/org/apache/commons/pool/BasePoolableObjectFactory.html";><code>BasePoolableObjectFactory</code></a>
+ provides an abstract base implementation of
<code>PoolableObjectFactory</code> that
+ makes implementations a snap.
+ </p>
+ <p>
+ <a
href="http://nagoya.apache.org/gump/javadoc/jakarta-commons/pool/dist/docs/api/org/apache/commons/pool/KeyedPoolableObjectFactory.html";><code>KeyedPoolableObjectFactory</code></a>
+ defines a similiar interface for <code>KeyedObjectPool</code>s:
+ </p>
+ <pre>
+ public interface KeyedPoolableObjectFactory {
+ Object makeObject(Object key);
+ void activateObject(Object key, Object obj);
+ void passivateObject(Object key, Object obj);
+ boolean validateObject(Object key, Object obj);
+ void destroyObject(Object key, Object obj);
+ }
+ </pre>
+ <p>
+ <a
href="http://nagoya.apache.org/gump/javadoc/jakarta-commons/pool/dist/docs/api/org/apache/commons/pool/BaseKeyedPoolableObjectFactory.html";><code>BaseKeyedPoolableObjectFactory</code></a>
+ provides an abstract base implementation of
<code>KeyedPoolableObjectFactory</code> that
+ makes implementations a snap.
+ </p>
+ </subsection>
+ <p>
+ The
+ <a
href="http://nagoya.apache.org/gump/javadoc/jakarta-commons/pool/dist/docs/api/org/apache/commons/pool/impl/package-summary.html";>org.apache.commons.pool.impl</a>
+ package provides some <i>Pool</i> implementations.
+ </p>
+ <subsection name="StackObjectPool">
+ <p>
+ <a
href="http://nagoya.apache.org/gump/javadoc/jakarta-commons/pool/dist/docs/api/org/apache/commons/pool/impl/StackObjectPool.html";><code>StackObjectPool</code></a>
+ will pool a finite number of "idle" instances, but will create new
instances a needed in
+ order to support high demand.
+ </p>
+ <p>
+ <a
href="http://nagoya.apache.org/gump/javadoc/jakarta-commons/pool/dist/docs/api/org/apache/commons/pool/impl/StackKeyedObjectPool.html";><code>StackKeyedObjectPool</code></a>
+ offers the same behavior for keyed pools.
+ </p>
+ </subsection>
+ <subsection name="GenericObjectPool">
+ <p>
+ <a
href="http://nagoya.apache.org/gump/javadoc/jakarta-commons/pool/dist/docs/api/org/apache/commons/pool/impl/GenericObjectPool.html";><code>GenericObjectPool</code></a>
+ provides a wide variety of configuration options, including the ablity
to cap the number of idle or
+ active instances, to evict instances as they sit idle in the pool, etc.
+ </p>
+ <p>
+ <a
href="http://nagoya.apache.org/gump/javadoc/jakarta-commons/pool/dist/docs/api/org/apache/commons/pool/impl/GenericKeyedObjectPool.html";><code>GenericKeyedObjectPool</code></a>
+ offers the same behavior for keyed pools.
+ </p>
+ </subsection>
+ <subsection name="SoftReferenceObjectPool">
+ <p>
+ <a
href="http://nagoya.apache.org/gump/javadoc/jakarta-commons/pool/dist/docs/api/org/apache/commons/pool/impl/SoftReferenceObjectPool.html";><code>SoftReferenceObjectPool</code></a>
+ can grow as needed, but allows the garbage collector to evict idle
instances from the pool as needed.
+ </p>
+ </subsection>
+ </section>
</body>
-</document>
+</document>
\ No newline at end of file
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
