|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectsnaq.util.ObjectPool<T>
public abstract class ObjectPool<T extends Reusable>
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 (minimum/maximum), and the maximum number to ever be created.
Up to a maximum of maxSize
items can exist simultaneously,
but a maximum of maxPool
are ever held in the pool for quick
availability. The pool tries to maintain at least minPool
items
available for use even when the pool is not being used. As a result, if
idleTimeout is enabled the number of available pooled items may reduce from
maxPool
down towards minPool
if items are not used
frequently.
ObjectPool
should be sub-classed to override at least
the following methods:
protected T create() throws Exception protected boolean isValid(final T o) protected void destroy(final T o)
and optionally the following methods, which can be used for resource cleanup as required:
protected preRelease() protected postRelease()
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. It is also recommended
that the sub-class up-casts items to a user-defined interface when handing
them to pool clients, to prevent clients tampering with class internals.
For example, a database ConnectionPool class might sub-class ObjectPool,
but only hand over instances cast to the java.sql.Connection
interface.
Idle timeout of pooled items is handled by the idleTimeout
parameter, which by default is specified in milliseconds. Sub-classes
wanting to rescale to a different time unit should override the
getIdleTimeoutMultiplier()
method to return the appropriate value.
This class 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 its final use, which should always be
done using either release
or releaseAsync
.
Method Summary | |
---|---|
void |
addObjectPoolListener(ObjectPoolListener x)
Adds an listener to the event notification list. |
int |
compareTo(ObjectPool pool)
Compares this object with the specified object for order. |
boolean |
equals(Object o)
Indicates whether some other object is "equal to" this one. |
void |
flush()
Flushes the pool of all currently available items, emptying the pool. |
int |
getCheckedOut()
Returns the number of items that are currently checked-out. |
LogUtil |
getCustomLogger()
Returns the custom LogUtil instance being used,
or null if it doesn't exist. |
long |
getExpiryTime()
Deprecated. Replaced by getIdleTimeout() . |
int |
getFreeCount()
Returns the number of items held in the pool that are free to be checked-out. |
float |
getHitRate()
Deprecated. Replaced by getPoolHitRate() which returns a unit-scaled measure instead of a percentage. |
long |
getIdleTimeout()
Returns the idle timeout for unused items in the pool. |
int |
getMaxPool()
Returns the maximum number of items that can be pooled. |
int |
getMaxSize()
Returns the maximum number of items that can be created. |
int |
getMinPool()
Returns the minimum number of items that should be kept pooled. |
String |
getName()
Returns the pool name. |
String |
getParametersString()
Returns a summary string for this pool's parameters. |
float |
getPoolHitRate()
Returns hit rate of the pool (between 0 and 1). |
float |
getPoolMissRate()
Returns miss rate of the pool (between 0 and 1). |
long |
getRequestCount()
Returns the number of check-out requests that have been made to the pool since either its creation or the last time the resetHitCounter()
method was called. |
int |
getSize()
Returns the total number of objects held (available and checked-out). |
int |
hashCode()
Returns a hash code value for the object. |
void |
init()
Initializes the pool with the default (i.e. |
void |
init(int num)
Asynchronously initializes up to the specified number of items in the pool. |
boolean |
isAsyncDestroy()
Returns whether asynchronous object destruction is enabled. |
boolean |
isReleased()
Returns whether the pool has been released (and can no longer be used). |
void |
registerShutdownHook()
Registers a shutdown hook for this ConnectionPoolManager instance to ensure it is released if the JVM exits |
void |
release()
Releases all items from the pool, and shuts the pool down. |
void |
releaseAsync()
Releases all items from the pool, and shuts the pool down. |
void |
releaseForcibly()
Forcibly releases all items from the pool, and shuts the pool down. |
void |
removeObjectPoolListener(ObjectPoolListener x)
Removes a listener from the event notification list. |
void |
removeShutdownHook()
Deregisters a registered shutdown hook for this ConnectionPoolManager instance. |
void |
resetHitCounter()
Resets the counters for determining the pool's hit/miss rates. |
void |
setAsyncDestroy(boolean b)
Determines whether to perform asynchronous object destruction. |
void |
setLog(PrintWriter writer)
Sets the custom log stream. |
void |
setParameters(int minPool,
int maxPool,
int maxSize,
long idleTimeout)
Sets the pooling parameters. |
void |
setParameters(int maxPool,
int maxSize,
long idleTimeout)
Sets the pooling parameters (excluding minPool ). |
String |
toString()
Returns a descriptive string for this pool instance. |
Methods inherited from class java.lang.Object |
---|
getClass, notify, notifyAll, wait, wait, wait |
Method Detail |
---|
public void registerShutdownHook()
public void removeShutdownHook()
public String toString()
toString
in class Object
public String getParametersString()
public final void init()
public final void init(int num)
This method is somewhat redundant since the introduction
of the minPool
parameter, which should be used preferentially where
applicable. It can sometimes be useful to create initial pooled items
for a pool with minPool=0.
public final void release()
public final boolean isReleased()
public final void releaseAsync()
public final void releaseForcibly()
public final void setAsyncDestroy(boolean b)
public final boolean isAsyncDestroy()
public void setLog(PrintWriter writer)
PrintWriter
to receive log information.
writer
- PrintWriter
to which to write log entriespublic LogUtil getCustomLogger()
LogUtil
instance being used,
or null if it doesn't exist.
public final String getName()
public final int getMinPool()
public final int getMaxPool()
public final int getMaxSize()
public long getIdleTimeout()
getIdleTimeoutMultiplier()
method,
and may be overridden by sub-classes to provide idleTimeout scaling
(default of 1 for milliseconds, e.g. 1000 changes to seconds).
getIdleTimeoutUnadjusted()
/getIdleTimeoutMultiplier()
@Deprecated public long getExpiryTime()
getIdleTimeout()
.
getIdleTimeout()
.
public final void setParameters(int maxPool, int maxSize, long idleTimeout)
minPool
).
Any items currently in the pool will remain, subject to the new parameters.
(The hit rate counters are reset when this method is called.)
maxPool
- maximum number of items to be kept in poolmaxSize
- maximum number of items to be createdidleTimeout
- idle timeout for unused items (0 = no timeout)public final void setParameters(int minPool, int maxPool, int maxSize, long idleTimeout)
minPool
- minimum number of items to be kept in poolmaxPool
- maximum number of items to be kept in poolmaxSize
- maximum number of items to be createdidleTimeout
- idle timeout for unused items (0 = no timeout)public final int getSize()
public final int getCheckedOut()
public final int getFreeCount()
public final long getRequestCount()
resetHitCounter()
method was called.
@Deprecated public final float getHitRate()
getPoolHitRate()
which returns a unit-scaled measure instead of a percentage.
public final float getPoolHitRate()
public final float getPoolMissRate()
public final void resetHitCounter()
public final void flush()
public boolean equals(Object o)
equals
in class Object
public int hashCode()
hashCode
in class Object
public int compareTo(ObjectPool pool)
equals(Object)
, comparing the same fields.
compareTo
in interface Comparable<ObjectPool>
public final void addObjectPoolListener(ObjectPoolListener x)
public final void removeObjectPoolListener(ObjectPoolListener x)
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |