org.jboss.minerva.pools
Class ObjectPool

java.lang.Object
  |
  +--org.jboss.minerva.pools.ObjectPool
All Implemented Interfaces:
PoolEventListener

public class ObjectPool
extends java.lang.Object
implements PoolEventListener

A generic object pool. You must provide a PoolObjectFactory (or the class of a Java Bean) so the pool knows what kind of objects to create. It has many configurable parameters, such as the minimum and maximum size of the pool, whether to enable idle timeouts, etc. If the pooled objects implement PooledObject, they will automatically be returned to the pool at the appropriate times.

In general, the appropriate way to use a pool is:

  1. Create it
  2. Configure it (set factory, name, parameters, etc.)
  3. Initialize it (once done, further configuration is not allowed)
  4. Use it
  5. Shut it down

Version:
$Revision: 1.15 $
Author:
Aaron Mulder (ammulder@alumni.princeton.edu)
See Also:
PooledObject

Constructor Summary
ObjectPool()
          Creates a new pool.
ObjectPool(java.lang.Class javaBeanClass, java.lang.String poolName)
          Creates a new pool with the specified parameters.
ObjectPool(PoolObjectFactory factory, java.lang.String poolName)
          Creates a new pool with the specified parameters.
 
Method Summary
 long getGCInterval()
          Gets the length of time between garbage collection and idle timeout runs.
 long getGCMinIdleTime()
          Gets the minimum idle time to make an object eligible for garbage collection.
 long getIdleTimeout()
          Gets the minimum idle time to release an unused object from the pool.
 java.io.PrintWriter getLogWriter()
          Gets a log writer used to record pool events.
 float getMaxIdleTimeoutPercent()
          Gets the idle timeout percent as a fraction between 0 and 1.
 int getMaxSize()
          Gets the maximum size of the pool.
 int getMinSize()
          Gets the minimum size of the pool.
 java.lang.String getName()
          Gets the name of the pool.
 java.lang.Object getObject()
          Gets an object from the pool.
 void initialize()
          Prepares the pool for use.
 boolean isBlocking()
          Gets whether a request for an object will block if the pool size is maxed out and no objects are available.
 boolean isGCEnabled()
          Gets whether garbage collection is enabled.
 boolean isIdleTimeoutEnabled()
          Gets whether the pool releases instances that have not been used recently.
 boolean isInvalidateOnError()
          Gets whether objects are removed from the pool in case of errors.
 boolean isTimestampUsed()
          Gets whether object clients can update the last used time.
 void markObjectAsInvalid(java.lang.Object object)
          Indicates that an object is no longer valid, and should be removed from the pool entirely.
 void objectClosed(PoolEvent evt)
          If the object has been closed, release it.
 void objectError(PoolEvent evt)
          If the object had an error, we assume this will propogate and preclude it from being closed, so we will close it.
 void objectUsed(PoolEvent evt)
          If we're tracking the last used times, update the last used time for the specified object.
 void releaseObject(java.lang.Object object)
          Returns an object to the pool.
 void setBlocking(boolean blocking)
          Sets whether a request for an object will block if the pool size is maxed out and no objects are available.
 void setGCEnabled(boolean enabled)
          Sets whether garbage collection is enabled.
 void setGCInterval(long millis)
          Sets the length of time between garbage collection and idle timeout runs.
 void setGCMinIdleTime(long millis)
          Sets the minimum idle time to make an object eligible for garbage collection.
 void setIdleTimeout(long millis)
          Sets the minimum idle time to release an unused object from the pool.
 void setIdleTimeoutEnabled(boolean enableTimeout)
          Sets whether the pool should release instances that have not been used recently.
 void setInvalidateOnError(boolean invalidate)
          Sets the response for object errors.
 void setLastUsed(java.lang.Object object)
          Sets the last used time for an object in the pool that is currently in use.
 void setLogWriter(java.io.PrintWriter writer)
          Sets a log writer used to record pool events.
 void setMaxIdleTimeoutPercent(float percent)
          Sets the idle timeout percent as a fraction between 0 and 1.
 void setMaxSize(int size)
          Sets the maximum size of the pool.
 void setMinSize(int size)
          Sets the minimum size of the pool.
 void setName(java.lang.String name)
          Sets the name of the pool.
 void setObjectFactory(java.lang.Class javaBeanClass)
          Sets the object factory as a new factory for Java Beans.
 void setObjectFactory(PoolObjectFactory factory)
          Sets the object factory for the pool.
 void setTimestampUsed(boolean timestamp)
          Sets whether object clients can update the last used time.
 void shutDown()
          Shuts down the pool.
 java.lang.String toString()
          Returns the pool name and status.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

ObjectPool

public ObjectPool()
Creates a new pool. It cannot be used until you specify a name and object factory or bean class, and initialize it.
See Also:
setName(java.lang.String), setObjectFactory(org.jboss.minerva.pools.PoolObjectFactory), initialize()

ObjectPool

public ObjectPool(PoolObjectFactory factory,
                  java.lang.String poolName)
Creates a new pool with the specified parameters. It cannot be used until you initialize it.
Parameters:
factory - The object factory that will create the objects to go in the pool.
poolName - The name of the pool. This does not have to be unique across all pools, but it is strongly recommended (and it may be a requirement for certain uses of the pool).
See Also:
initialize()

ObjectPool

public ObjectPool(java.lang.Class javaBeanClass,
                  java.lang.String poolName)
Creates a new pool with the specified parameters. It cannot be used until you initialize it.
Parameters:
javeBeanClass - The Class of a Java Bean. New instances for the pool will be created with the no-argument constructor, and no particular initialization or cleanup will be performed on the instances. Use a PoolObjectFactory if you want more control over the instances.
poolName - The name of the pool. This does not have to be unique across all pools, but it is strongly recommended (and it may be a requirement for certain uses of the pool).
See Also:
initialize()
Method Detail

setObjectFactory

public void setObjectFactory(PoolObjectFactory factory)
Sets the object factory for the pool. The object factory controls the instances created for the pool, and can initialize instances given out by the pool and cleanup instances returned to the pool.
Throws:
java.lang.IllegalStateException - Occurs when you try to set the object factory after the pool has been initialized.

setObjectFactory

public void setObjectFactory(java.lang.Class javaBeanClass)
Sets the object factory as a new factory for Java Beans. New instances for the pool will be created with the no-argument constructor, and no particular initialization or cleanup will be performed on the instances.
Throws:
java.lang.IllegalStateException - Occurs when you try to set the object factory after the pool has been initialized.

setName

public void setName(java.lang.String name)
Sets the name of the pool. This is not required to be unique across all pools, but is strongly recommended. Certain uses of the pool (such as a JNDI object factory) may require it. This must be set exactly once for each pool (it may be set in the constructor).
Throws:
java.lang.IllegalStateException - Occurs when you try to set the name of the pool more than once.

getName

public java.lang.String getName()
Gets the name of the pool.

getLogWriter

public java.io.PrintWriter getLogWriter()
                                 throws java.sql.SQLException
Gets a log writer used to record pool events.

setLogWriter

public void setLogWriter(java.io.PrintWriter writer)
                  throws java.sql.SQLException
Sets a log writer used to record pool events.
Throws:
java.lang.IllegalStateException - Occurs when you try to set the log writer after the pool has been initialized.

setMinSize

public void setMinSize(int size)
Sets the minimum size of the pool. The pool will create this many instances at startup, and once running, it will never shrink below this size. The default is zero.
Throws:
java.lang.IllegalStateException - Occurs when you try to set the minimum size after the pool has been initialized.

getMinSize

public int getMinSize()
Gets the minimum size of the pool.
See Also:
setMinSize(int)

setMaxSize

public void setMaxSize(int size)
Sets the maximum size of the pool. Once the pool has grown to hold this number of instances, it will not add any more instances. If one of the pooled instances is available when a request comes in, it will be returned. If none of the pooled instances are available, the pool will either block until an instance is available, or return null. The default is no maximum size.
Parameters:
size - The maximum size of the pool, or 0 if the pool should grow indefinitely (not recommended).
Throws:
java.lang.IllegalStateException - Occurs when you try to set the maximum size after the pool has been initialized.
See Also:
setBlocking(boolean)

getMaxSize

public int getMaxSize()
Gets the maximum size of the pool.
See Also:
setMaxSize(int)

setIdleTimeoutEnabled

public void setIdleTimeoutEnabled(boolean enableTimeout)
Sets whether the pool should release instances that have not been used recently. This is intended to reclaim resources (memory, database connections, file handles, etc) during periods of inactivity. This runs as often as garbage collection (even if garbage collection is disabled, this uses the same timing parameter), but the required period of inactivity is different. All objects that have been unused for more than the idle timeout are closed, but if you set the MaxIdleShrinkPercent parameter, the pool may recreate some objects so the total number of pooled instances doesn't shrink as rapidly. Also, under no circumstances will the number of pooled instances fall below the minimum size.

The default is disabled.

Throws:
java.lang.IllegalStateException - Occurs when you try to set the idle timeout state after the pool has been initialized.
See Also:
setGCInterval(long), setIdleTimeout(long), setMaxIdleTimeoutPercent(float), setMinSize(int)

isIdleTimeoutEnabled

public boolean isIdleTimeoutEnabled()
Gets whether the pool releases instances that have not been used recently. This is different than garbage collection, which returns instances to the pool if a client checked an instance out but has not used it and not returned it to the pool.
See Also:
setIdleTimeoutEnabled(boolean)

setGCEnabled

public void setGCEnabled(boolean enabled)
Sets whether garbage collection is enabled. This is the process of returning objects to the pool if they have been checked out of the pool but have not been used in a long periond of time. This is meant to reclaim resources, generally caused by unexpected failures on the part of the pool client (which forestalled returning an object to the pool). This runs on the same schedule as the idle timeout (if enabled), but objects that were just garbage collected will not be eligible for the idle timeout immediately (after all, they presumably represented "active" clients). Objects that are garbage collected will be checked out again immediately if a client is blocking waiting for an object. The default value is disabled.
Throws:
java.lang.IllegalStateException - Occurs when you try to set the garbage collection state after the pool has been initialized.
See Also:
setGCMinIdleTime(long), setGCInterval(long)

isGCEnabled

public boolean isGCEnabled()
Gets whether garbage collection is enabled.
See Also:
setGCEnabled(boolean)

setMaxIdleTimeoutPercent

public void setMaxIdleTimeoutPercent(float percent)
Sets the idle timeout percent as a fraction between 0 and 1. If a number of objects are determined to be idle, they will all be closed and removed from the pool. However, if the ratio of objects released to objects in the pool is greater than this fraction, some new objects will be created to replace the closed objects. This prevents the pool size from decreasing too rapidly. Set to 0 to decrease the pool size by a maximum of 1 object per test, or 1 to never replace objects that have exceeded the idle timeout. The pool will always replace enough closed connections to stay at the minimum size.
Throws:
java.lang.IllegalStateException - Occurs when you try to set the idle timeout percent after the pool has been initialized.
java.lang.IllegalArgumentException - Occurs when the percent parameter is not between 0 and 1.
See Also:
setIdleTimeoutEnabled(boolean)

getMaxIdleTimeoutPercent

public float getMaxIdleTimeoutPercent()
Gets the idle timeout percent as a fraction between 0 and 1.
See Also:
setMaxIdleTimeoutPercent(float)

setIdleTimeout

public void setIdleTimeout(long millis)
Sets the minimum idle time to release an unused object from the pool. If the object is not in use and has not been used for this amount of time, it will be released from the pool. If timestamps are enabled, the client may update the last used time. Otherwise, the last used time is only updated when an object is acquired or released. The default value is 30 minutes.
Parameters:
millis - The idle time, in milliseconds.
Throws:
java.lang.IllegalStateException - Occurs when you try to set the idle timeout after the pool has been initialized.
See Also:
setIdleTimeoutEnabled(boolean)

getIdleTimeout

public long getIdleTimeout()
Gets the minimum idle time to release an unused object from the pool.
See Also:
setIdleTimeout(long)

setGCMinIdleTime

public void setGCMinIdleTime(long millis)
Sets the minimum idle time to make an object eligible for garbage collection. If the object is in use and has not been used for this amount of time, it may be returned to the pool. If timestamps are enabled, the client may update the last used time (this is generally recommended if garbage collection is enabled). Otherwise, the last used time is only updated when an object is acquired or released. The default value is 20 minutes.
Parameters:
millis - The idle time, in milliseconds.
Throws:
java.lang.IllegalStateException - Occurs when you try to set the garbage collection idle time after the pool has been initialized.
See Also:
setGCEnabled(boolean)

getGCMinIdleTime

public long getGCMinIdleTime()
Gets the minimum idle time to make an object eligible for garbage collection.
See Also:
setGCMinIdleTime(long)

setGCInterval

public void setGCInterval(long millis)
Sets the length of time between garbage collection and idle timeout runs. This is inexact - if there are many pools with garbage collection and/or the idle timeout enabled, there will not be a thread for each one, and several nearby actions may be combined. Likewise if the collection process is lengthy for certain types of pooled objects (not recommended), other actions may be delayed. This is to prevend an unnecessary proliferation of threads. Note that this parameter controls both garbage collection and the idle timeout - and they will be performed together if both are enabled. The deafult value is 2 minutes.
Throws:
java.lang.IllegalStateException - Occurs when you try to set the garbage collection interval after the pool has been initialized.

getGCInterval

public long getGCInterval()
Gets the length of time between garbage collection and idle timeout runs.
See Also:
setGCInterval(long)

setBlocking

public void setBlocking(boolean blocking)
Sets whether a request for an object will block if the pool size is maxed out and no objects are available. If set to block, the request will not return until an object is available. Otherwise, the request will return null immediately (and may be retried). If multiple requests block, there is no guarantee which will return first. The default is to block.
Throws:
java.lang.IllegalStateException - Occurs when you try to set the blocking parameter after the pool has been initialized.

isBlocking

public boolean isBlocking()
Gets whether a request for an object will block if the pool size is maxed out and no objects are available.
See Also:
setBlocking(boolean)

setTimestampUsed

public void setTimestampUsed(boolean timestamp)
Sets whether object clients can update the last used time. If not, the last used time will only be updated when the object is given to a client and returned to the pool. This time is important if the idle timeout or garbage collection is enabled (particularly the latter). The default is false.
Throws:
java.lang.IllegalStateException - Occurs when you try to set the timestamp parameter after the pool has been initialized.

isTimestampUsed

public boolean isTimestampUsed()
Gets whether object clients can update the last used time.

setInvalidateOnError

public void setInvalidateOnError(boolean invalidate)
Sets the response for object errors. If this flag is set and an error event occurs, the object is removed from the pool entirely. Otherwise, the object is returned to the pool of available objects. For example, a SQL error may not indicate a bad database connection (flag not set), while a TCP/IP error probably indicates a bad network connection (flag set). If this flag is not set, you can still manually invalidate objects using markObjectAsInvalid.
See Also:
markObjectAsInvalid(java.lang.Object), objectError(org.jboss.minerva.pools.PoolEvent)

isInvalidateOnError

public boolean isInvalidateOnError()
Gets whether objects are removed from the pool in case of errors.

initialize

public void initialize()
Prepares the pool for use. This must be called exactly once before getObject is even called. The pool name and object factory must be set before this call will succeed.
Throws:
java.lang.IllegalStateException - Occurs when you try to initialize the pool without setting the object factory or name, or you initialize the pool more than once.

shutDown

public void shutDown()
Shuts down the pool. All outstanding objects are closed and all objects are released from the pool. No getObject or releaseObject calls will succeed after this method is called - and they will probably fail during this method call.

getObject

public java.lang.Object getObject()
Gets an object from the pool. If all the objects in the pool are in use, creates a new object, adds it to the pool, and returns it. If all objects are in use and the pool is at maximum size, will block or return null.
See Also:
setBlocking(boolean)

setLastUsed

public void setLastUsed(java.lang.Object object)
Sets the last used time for an object in the pool that is currently in use. If the timestamp parameter is not set, this call does nothing. Otherwise, the object is marked as last used at the current time.
Throws:
java.lang.IllegalArgumentException - Occurs when the object is not recognized by the factory or not in the pool.
java.lang.IllegalStateException - Occurs when the object is not currently in use.
See Also:
setTimestampUsed(boolean)

markObjectAsInvalid

public void markObjectAsInvalid(java.lang.Object object)
Indicates that an object is no longer valid, and should be removed from the pool entirely. This should be called before the object is returned to the pool (specifically, before factory.returnObject returns), or else the object may be given out again by the time this is called! Also, you still need to actually return the object to the pool by calling releaseObject, if you aren't calling this during that process already.
Parameters:
Object - The object to invalidate, which must be the exact object returned by getObject

releaseObject

public void releaseObject(java.lang.Object object)
Returns an object to the pool. This must be the exact object that was given out by getObject, and it must be returned to the same pool that generated it. If other clients are blocked waiting on an object, the object may be re-released immediately.
Throws:
java.lang.IllegalArgumentException - Occurs when the object is not in this pool.

toString

public java.lang.String toString()
Returns the pool name and status.
Overrides:
toString in class java.lang.Object

objectClosed

public void objectClosed(PoolEvent evt)
If the object has been closed, release it.
Specified by:
objectClosed in interface PoolEventListener

objectError

public void objectError(PoolEvent evt)
If the object had an error, we assume this will propogate and preclude it from being closed, so we will close it. If the invalidateOnError flag is set, the object will be removed from the pool entirely.
Specified by:
objectError in interface PoolEventListener

objectUsed

public void objectUsed(PoolEvent evt)
If we're tracking the last used times, update the last used time for the specified object.
Specified by:
objectUsed in interface PoolEventListener


Copyright © 2000 The jBoss Organization. All Rights Reserved.