| java.lang.Object
 snaq.util.LogUtil
snaq.util.ObjectPool
All known Subclasses: snaq.db.ConnectionPool,
| ObjectPool | | abstract public class ObjectPool extends LogUtil (Code) | | Base class for a pool system implementation.
This class provides all the base functionality required and can be easily
extended to provide pooling support for many different types of object.
New objects are retrieved on demand according to specified limits,
and the pool can also ensure an object's validity before returning it.
The limits which can be set for a pool include the number of items to be
held in the pool, and the maximum number to ever be created.
The pool will try to maintain poolSize items open and ready
for use (unless that number has not yet been created), but if expiry is
enabled this number will reduce if the items are not used frequently.
If maxSize is specified then the pool will never create more
than this number of items, and another can only be obtained from the pool
if it is handed back by another client.
ObjectPool should be sub-classed to override
the following methods:
protected Reusable create() throws Exception
protected boolean isValid(final Reusable o)
protected void destroy(final Reusable o)
It is recommended that the sub-class implements methods for obtaining
and returning items within the pool, casting the objects returned by this
class as required to the appropriate class type.
ObjectPool also support asynchronous destruction of items, which can be
useful in circumstances where destruction of items held can take a long
time which would delay the checkIn method. This also applies
to the release of the pool after it's final use, which should always be
done using either release or releaseAsync.
author:
Giles Winstanley |
| Inner Class :final class Cleaner extends Thread | |
| Constructor Summary | |
| protected | ObjectPool(String name, int poolSize, int maxSize, long expiryTime)
Creates new object pool. | | protected | ObjectPool(String name, int poolSize, int maxSize, int expiryTime)
Creates new object pool. |
| Method Summary | |
| final public void | addObjectPoolListener(ObjectPoolListener x)
Adds an ObjectPoolListener to the event notification list. | | final protected void | checkIn(Reusable o)
Checks an object into the pool, and notify other
threads that may be waiting for one. | | final protected synchronized Reusable | checkOut()
Checks out an item from the pool. | | final protected synchronized Reusable | checkOut(long timeout)
Checks out an item from the pool. | | abstract protected Reusable | create()
Object creation method. | | abstract protected void | destroy(Reusable o)
Object destruction method. | | public void | finalize()
Shuts down the object pool. | | final public void | flush()
Flushes the pool of all currently available items, emptying the pool. | | final public synchronized int | getCheckedOut()
Returns the number of items that are currently checked-out. | | final public long | getExpiryTime()
Returns the expiry time for unused items in the pool. | | final public synchronized int | getFreeCount()
Returns the number of items held in the pool that are free to be checked-out. | | final public float | getHitRate()
Returns hit rate of the pool as a percentage. | | final public int | getMaxSize()
Returns the maximum number of items that can be created. | | final public String | getName()
Returns the pool name. | | protected Class | getPoolClass()
Returns the class to use for the pool collection. | | final public int | getPoolSize()
Returns the maximum size of the pool. | | final public synchronized int | getSize()
Returns the total number of objects held (available and checked-out). | | final public void | init(int num)
Initializes the given number of items in the pool. | | final public boolean | isAsyncDestroy()
Returns whether asynchronous object destruction is enabled. | | abstract protected boolean | isValid(Reusable o)
Object validation method. | | public void | log(String logEntry)
Writes a message to the log. | | public void | log(Throwable e, String logEntry)
Writes a message with an Exception to the log file. | | final synchronized boolean | purge()
Purges expired objects from the pool. | | final public void | release()
Releases all items from the pool, and shuts the pool down. | | final public synchronized void | releaseAsync()
Releases all items from the pool, and shuts the pool down. | | final public void | releaseForcibly()
Forcibly releases all items from the pool, and shuts the pool down. | | final public void | removeObjectPoolListener(ObjectPoolListener x)
Removes an ObjectPoolListener from the event notification list. | | final protected void | resetHitCounter()
Resets the counter for determining the pool's hit rate. | | final protected void | setAccessFIFO()
Sets the pool access method to FIFO (first-in, first-out: a queue). | | final protected void | setAccessLIFO()
Sets the pool access method to LIFO (last-in, first-out: a stack). | | final protected void | setAccessRandom()
Sets the pool access method to random (a random connection is selected for check-out). | | final public void | setAsyncDestroy(boolean b)
Determines whether to perform asynchronous object destruction. | | final public void | setParameters(int poolSize, int maxSize, long expiryTime)
Sets the pooling parameters. |
| ObjectPool | | protected ObjectPool(String name, int poolSize, int maxSize, long expiryTime)(Code) | | Creates new object pool.
Parameters:
name - pool name
Parameters:
poolSize - maximum number of pooled objects, or 0 for no limit
Parameters:
maxSize - maximum number of possible objects, or 0 for no limit
Parameters:
expiryTime - expiry time (milliseconds) for pooled object, or 0 for no expiry |
| ObjectPool | | protected ObjectPool(String name, int poolSize, int maxSize, int expiryTime)(Code) | | Creates new object pool.
Parameters:
name - pool name
Parameters:
poolSize - maximum number of pooled objects, or 0 for no limit
Parameters:
maxSize - maximum number of possible objects, or 0 for no limit
Parameters:
expiryTime - expiry time (milliseconds) for pooled object, or 0 for no expiry |
| addObjectPoolListener | | final public void addObjectPoolListener(ObjectPoolListener x)(Code) | | Adds an ObjectPoolListener to the event notification list.
|
| checkIn | | final protected void checkIn(Reusable o)(Code) | | Checks an object into the pool, and notify other
threads that may be waiting for one.
Parameters:
o - object to check in |
| checkOut | | final protected synchronized Reusable checkOut() throws Exception(Code) | | Checks out an item from the pool. If no free item
is available, a new item is created unless the maximum
number of items has been reached. If a free item
is not valid it is removed from the pool and another
is retrieved.
item from the pool, or null if nothing available
exception:
Exception - if there is an error creating a new object |
| checkOut | | final protected synchronized Reusable checkOut(long timeout) throws Exception(Code) | | Checks out an item from the pool.
If there is no pooled item available and the maximum number
possible has not been reached, another is created.
If a free item is detected as being invalid it is removed
from the pool and the another is retrieved.
If an item is not available and the maximum number possible
has been reached, the method waits for the timeout period
for one to become available by being checked in.
Parameters:
timeout - timeout value in milliseconds item from the pool, or null if nothing available within timeout period
exception:
Exception - if there is an error creating a new object |
| create | | abstract protected Reusable create() throws Exception(Code) | | Object creation method.
This method is called when a new item needs to be created following a call
to one of the check-out methods.
exception:
Exception - if unable to create the item |
| destroy | | abstract protected void destroy(Reusable o)(Code) | | Object destruction method.
This method is called when an object needs to be destroyed due to pool
pruning/cleaning, or final release of the pool.
|
| finalize | | public void finalize()(Code) | | Shuts down the object pool.
If overridden the sub-class should make sure super.finalize() is called.
|
| flush | | final public void flush()(Code) | | Flushes the pool of all currently available items, emptying the pool.
|
| getCheckedOut | | final public synchronized int getCheckedOut()(Code) | | Returns the number of items that are currently checked-out.
|
| getExpiryTime | | final public long getExpiryTime()(Code) | | Returns the expiry time for unused items in the pool.
|
| getFreeCount | | final public synchronized int getFreeCount()(Code) | | Returns the number of items held in the pool that are free to be checked-out.
|
| getHitRate | | final public float getHitRate()(Code) | | Returns hit rate of the pool as a percentage.
The hit rate is the proportion of requests for a connection which result
in the return of a connection which is in the pool, rather than which
results in the creation of a new connection.
|
| getMaxSize | | final public int getMaxSize()(Code) | | Returns the maximum number of items that can be created.
|
| getName | | final public String getName()(Code) | | Returns the pool name.
|
| getPoolClass | | protected Class getPoolClass()(Code) | | Returns the class to use for the pool collection.
This can be over-ridden by a sub-class to provide a different List
type for the pool, which may give performance benefits in certain situations.
Only instances of List collections should be used.
(Default: java.util.ArrayList.class)
For those wanting to override this method, pool items are checked-out from
the front of the List - remove(0) - and replaced at the end of
the List when checked-in again - add(Object).
|
| getPoolSize | | final public int getPoolSize()(Code) | | Returns the maximum size of the pool.
|
| getSize | | final public synchronized int getSize()(Code) | | Returns the total number of objects held (available and checked-out).
|
| init | | final public void init(int num)(Code) | | Initializes the given number of items in the pool.
This spawns a new thread to create them in the background.
|
| isAsyncDestroy | | final public boolean isAsyncDestroy()(Code) | | Returns whether asynchronous object destruction is enabled.
(Default: false)
|
| isValid | | abstract protected boolean isValid(Reusable o)(Code) | | Object validation method.
This method is called when checking-out an item to see if it is valid for use.
When overridden by the sub-class it is recommended that this method perform
suitable checks to ensure the object can be used without problems.
|
| log | | public void log(String logEntry)(Code) | | Writes a message to the log.
|
| log | | public void log(Throwable e, String logEntry)(Code) | | Writes a message with an Exception to the log file.
|
| purge | | final synchronized boolean purge()(Code) | | Purges expired objects from the pool.
This method is called by the cleaner thread to purge expired items.
false if pool is empty after purging (no further purge required until items added), true otherwise |
| release | | final public void release()(Code) | | Releases all items from the pool, and shuts the pool down.
If any items are still checked-out, this method waits until all items have
been checked-in before returning.
|
| releaseAsync | | final public synchronized void releaseAsync()(Code) | | Releases all items from the pool, and shuts the pool down.
This method returns immediately; a background thread is created to perform the release.
|
| releaseForcibly | | final public void releaseForcibly()(Code) | | Forcibly releases all items from the pool, and shuts the pool down.
If any items are still checked-out, this method forcibly destroys them
and then returns.
|
| removeObjectPoolListener | | final public void removeObjectPoolListener(ObjectPoolListener x)(Code) | | Removes an ObjectPoolListener from the event notification list.
|
| resetHitCounter | | final protected void resetHitCounter()(Code) | | Resets the counter for determining the pool's hit rate.
|
| setAccessFIFO | | final protected void setAccessFIFO()(Code) | | Sets the pool access method to FIFO (first-in, first-out: a queue).
|
| setAccessLIFO | | final protected void setAccessLIFO()(Code) | | Sets the pool access method to LIFO (last-in, first-out: a stack).
|
| setAccessRandom | | final protected void setAccessRandom()(Code) | | Sets the pool access method to random (a random connection is selected for check-out).
|
| setAsyncDestroy | | final public void setAsyncDestroy(boolean b)(Code) | | Determines whether to perform asynchronous object destruction.
If set to true then each time an object is destroyed (invalid object
during pool operation, or when the pool is finally released) the operation
is done in a separate thread, allowing the method to return immediately.
This can be useful when calling the destroy method on an object takes a
long time to complete.
|
| setParameters | | final public void setParameters(int poolSize, int maxSize, long expiryTime)(Code) | | Sets the pooling parameters.
Any items currently in the pool will remain, subject to the new parameters.
(The hit rate counters are reset when this method is called.)
Parameters:
poolSize - number of items to be keep in pool
Parameters:
maxSize - maximum number of items to be created
Parameters:
expiryTime - expiry time for unused items (milliseconds) (0 = no expiry) |
|
|