com.boylesoftware.cb2.util.pool
Class AdaptiveObjectPool

java.lang.Object
  com.boylesoftware.cb2.util.pool.AdaptiveObjectPool

public class AdaptiveObjectPool

extends java.lang.Object

A general purpose object pool. This implementation allows dynamic growing of the internal storage of idle objects, but it never shrinks.

This implementation is thread-safe and can be used by a number of concurrent threads.

Version:

$Id: AdaptiveObjectPool.java,v 1.5 2004/04/08 18:32:23 levahim Exp $

Author:

Lev Himmelfarb

Constructor Summary

AdaptiveObjectPool(java.lang.Class objectClass)
Constructs a pool with initial capacity of 10 instances, 0 minimum objects limit and no idle timeout.

AdaptiveObjectPool(java.lang.Class objectClass, int poolSize, int minObjects, long maxIdleTime)
Constructs a pool with the specified intial capacity.

AdaptiveObjectPool(PooledObjectFactory objectFactory)
Constructs a pool with initial capacity of 10 instances, 0 minimum objects limit and no idle timeout.

AdaptiveObjectPool(PooledObjectFactory objectFactory, int poolSize, int minObjects, long maxIdleTime)
Constructs a pool with the specified initial capacity and all other passible parameters.

Method Summary

void	discard() Destroys the pool.
java.lang.Object	get() Returns an object from the pool.
int	getHitRate() The hit rate (the relation of the number of new object allocations to the total number of pooled object requests) in 0.01%.
int	getNIdles() Returns the number of idle objects in the pool.
int	getNIncrements() Returns the number of times the pool's internal storage of idle objects had to be increased because it could not hold the required number of idle objects.
int	getNUsed() Returns the number of objects currently being assigned through the get method.
int	getPoolSize() Returns number of idle objects this pool can hold without reallocating the pool's internal storage of idle objects.
void	returnObject(java.lang.Object obj) Returns a borrowed object back to the pool.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AdaptiveObjectPool

public AdaptiveObjectPool(PooledObjectFactory objectFactory,
                          int poolSize,
                          int minObjects,
                          long maxIdleTime)

Constructs a pool with the specified initial capacity and all other passible parameters. This is the main contructor internally called from all others.

Note, that if you specify maxIdleTime parameter, you should call discrad method if you want to destroy the pool, abandoning the reference to the pool used in you application is not sufficient to free the instance's memory and kill the cleaner thread.

Parameters:

objectFactory - the factory to be used for new instances creation.

poolSize - initial capacity of the pool's internal storage. The pool can hold this many idle objects without the internal storage being reallocated, which is a relatively expensive operation.

minObjects - minimum number of instances the pool should maintain. This includes both idling and allocated instances. When the pool initializes it creates this number of instances and prepopulates itself with them.

maxIdleTime - maximum allowed time in seconds for instances to be idle. If an instance was not allocated for this amount of time it is removed from the pool, thus the pool shrinks. If this parameters is 0 there is no limit and the pool never shrinks.

AdaptiveObjectPool

public AdaptiveObjectPool(PooledObjectFactory objectFactory)

Constructs a pool with initial capacity of 10 instances, 0 minimum objects limit and no idle timeout.

Parameters:

objectFactory - the factory to be used for new instances creation.

AdaptiveObjectPool

public AdaptiveObjectPool(java.lang.Class objectClass,
                          int poolSize,
                          int minObjects,
                          long maxIdleTime)

Constructs a pool with the specified intial capacity.

Parameters:

objectClass - class of pooled objects.

poolSize - the maximum number of pooled, idle objects.

minObjects - minimum number of objects in the pool.

maxIdleTime - idle timeout in seconds.

AdaptiveObjectPool

public AdaptiveObjectPool(java.lang.Class objectClass)

Constructs a pool with initial capacity of 10 instances, 0 minimum objects limit and no idle timeout.

Parameters:

objectClass - class of pooled objects.

Method Detail

get

public java.lang.Object get()

Returns an object from the pool. The object must be returned back to the pool by calling the returnObject method.

Returns:

reference to the object instance.

returnObject

public void returnObject(java.lang.Object obj)

Returns a borrowed object back to the pool.

Parameters:

obj - reference to the object to return.

Throws:

java.lang.IllegalArgumentException - if obj parameter is null.

discard

public void discard()

Destroys the pool. If you use maxIdleTime pool parameter the system creates a special daemon thread, which periodically checks the pool and shrinks it if needed. The thread is not terminated automatically after you abandon the pool instance in your application, because it has an internal reference to the pool instance. Therefore, if you want to destroy a pool in your application you should explitiately call this discard method and then the instance will be freed and the cleaner thread killed.

There is no need to call this method if you don't use the maxIdleTime parameter (that is it is zero).

getNIdles

public int getNIdles()

Returns the number of idle objects in the pool.

Returns:

the number of idle objects.

getNUsed

public int getNUsed()

Returns the number of objects currently being assigned through the get method.

Returns:

the number of used objects.

getPoolSize

public int getPoolSize()

Returns number of idle objects this pool can hold without reallocating the pool's internal storage of idle objects.

Returns:

the pool's internal storage size.

getHitRate

public int getHitRate()

The hit rate (the relation of the number of new object allocations to the total number of pooled object requests) in 0.01%.

Returns:

the pool's hit rate.

getNIncrements

public int getNIncrements()

Returns the number of times the pool's internal storage of idle objects had to be increased because it could not hold the required number of idle objects.

Returns:

the number of pool internal storage increments.