GenericKeyedObjectPool (Jakarta Commons Object Pooling Package)

Overview

Package

Class

Index

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.apache.commons.pool.impl
Class GenericKeyedObjectPool

java.lang.Object
  |
  +--org.apache.commons.pool.BaseKeyedObjectPool
        |
        +--org.apache.commons.pool.impl.GenericKeyedObjectPool

All Implemented Interfaces:: KeyedObjectPool

public class GenericKeyedObjectPool
extends BaseKeyedObjectPool
implements KeyedObjectPool

A configurable KeyedObjectPool implementation.

When coupled with the appropriate KeyedPoolableObjectFactory, GenericKeyedObjectPool provides robust pooling functionality for arbitrary objects.

A GenericKeyedObjectPool provides a number of configurable parameters:

maxActive controls the maximum number of objects (per key) that can be borrowed from the pool at one time. When non-positive, there is no limit to the number of objects that may be active at one time. When maxActive is exceeded, the pool is said to be exhausted.
maxIdle controls the maximum number of objects that can sit idle in the pool (per key) at any time. When non-positive, there is no limit to the number of objects that may be idle at one time.
whenExhaustedAction specifies the behaviour of the borrowObject(java.lang.Object) method when the pool is exhausted:
- When whenExhaustedAction is WHEN_EXHAUSTED_FAIL, borrowObject(java.lang.Object) will throw a NoSuchElementException
- When whenExhaustedAction is WHEN_EXHAUSTED_GROW, borrowObject(java.lang.Object) will create a new object and return it(essentially making maxActive meaningless.)
- When whenExhaustedAction is WHEN_EXHAUSTED_BLOCK, borrowObject(java.lang.Object) will block (invoke Object.wait(long) until a new or idle object is available. If a positive maxWait value is supplied, the borrowObject(java.lang.Object) will block for at most that many milliseconds, after which a NoSuchElementException will be thrown. If maxWait is non-positive, the borrowObject(java.lang.Object) method will block indefinitely.
When testOnBorrow is set, the pool will attempt to validate each object before it is returned from the borrowObject(java.lang.Object) method. (Using the provided factory's PoolableObjectFactory.validateObject(java.lang.Object) method.) Objects that fail to validate will be dropped from the pool, and a different object will be borrowed.
When testOnReturn is set, the pool will attempt to validate each object before it is returned to the pool in the returnObject(java.lang.Object, java.lang.Object) method. (Using the provided factory's PoolableObjectFactory.validateObject(java.lang.Object) method.) Objects that fail to validate will be dropped from the pool.

Optionally, one may configure the pool to examine and possibly evict objects as they sit idle in the pool. This is performed by an "idle object eviction" thread, which runs asychronously. The idle object eviction thread may be configured using the following attributes:

timeBetweenEvictionRunsMillis indicates how long the eviction thread should sleep before "runs" of examining idle objects. When non-positive, no eviction thread will be launched.
minEvictableIdleTimeMillis specifies the minimum amount of time that an object may sit idle in the pool before it is eligable for eviction due to idle time. When non-positive, no object will be dropped from the pool due to idle time alone.
testWhileIdle indicates whether or not idle objects should be validated using the factory's PoolableObjectFactory.validateObject(java.lang.Object) method. Objects that fail to validate will be dropped from the pool.

Version:: $Id: GenericKeyedObjectPool.java,v 1.6 2002/08/10 21:13:26 rwaldhoff Exp $
Author:: Rodney Waldhoff
See Also:: GenericObjectPool

Nested Class Summary

static class GenericKeyedObjectPool.Config
          A simple "struct" encapsulating the configuration information for a GenericKeyedObjectPool.

Field Summary

static int DEFAULT_MAX_ACTIVE
          The default cap on the total number of active instances from the pool (per key).

static int DEFAULT_MAX_IDLE
          The default cap on the number of idle instances in the pool (per key).

static long DEFAULT_MAX_WAIT
          The default maximum amount of time (in millis) the borrowObject(java.lang.Object) method should block before throwing an exception when the pool is exhausted and the "when exhausted" action is WHEN_EXHAUSTED_BLOCK.

static long DEFAULT_MIN_EVICTABLE_IDLE_TIME_MILLIS
          The default value for getMinEvictableIdleTimeMillis().

static int DEFAULT_NUM_TESTS_PER_EVICTION_RUN
          The default number of objects to examine per run in the idle object evictor.

static boolean DEFAULT_TEST_ON_BORROW
          The default "test on borrow" value.

static boolean DEFAULT_TEST_ON_RETURN
          The default "test on return" value.

static boolean DEFAULT_TEST_WHILE_IDLE
          The default "test while idle" value.

static long DEFAULT_TIME_BETWEEN_EVICTION_RUNS_MILLIS
          The default "time between eviction runs" value.

static byte DEFAULT_WHEN_EXHAUSTED_ACTION
          The default "when exhausted action" for the pool.

static byte WHEN_EXHAUSTED_BLOCK
          A "when exhausted action" type indicating that when the pool is exhausted (i.e., the maximum number of active objects has been reached), the borrowObject(java.lang.Object) method should block until a new object is available, or the maximum wait time has been reached.

static byte WHEN_EXHAUSTED_FAIL
          A "when exhausted action" type indicating that when the pool is exhausted (i.e., the maximum number of active objects has been reached), the borrowObject(java.lang.Object) method should fail, throwing a NoSuchElementException.

static byte WHEN_EXHAUSTED_GROW
          A "when exhausted action" type indicating that when the pool is exhausted (i.e., the maximum number of active objects has been reached), the borrowObject(java.lang.Object) method should simply create a new object anyway.

Constructor Summary

GenericKeyedObjectPool(KeyedPoolableObjectFactory factory)
          Create a new GenericKeyedObjectPool using the specified values.

GenericKeyedObjectPool(KeyedPoolableObjectFactory factory, GenericKeyedObjectPool.Config config)
          Create a new GenericKeyedObjectPool using the specified values.

GenericKeyedObjectPool(KeyedPoolableObjectFactory factory, int maxActive)
          Create a new GenericKeyedObjectPool using the specified values.

GenericKeyedObjectPool(KeyedPoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait)
          Create a new GenericKeyedObjectPool using the specified values.

GenericKeyedObjectPool(KeyedPoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait, boolean testOnBorrow, boolean testOnReturn)
          Create a new GenericKeyedObjectPool using the specified values.

GenericKeyedObjectPool(KeyedPoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait, int maxIdle)
          Create a new GenericKeyedObjectPool using the specified values.

GenericKeyedObjectPool(KeyedPoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait, int maxIdle, boolean testOnBorrow, boolean testOnReturn)
          Create a new GenericKeyedObjectPool using the specified values.

GenericKeyedObjectPool(KeyedPoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait, int maxIdle, boolean testOnBorrow, boolean testOnReturn, long timeBetweenEvictionRunsMillis, int numTestsPerEvictionRun, long minEvictableIdleTimeMillis, boolean testWhileIdle)
          Create a new GenericKeyedObjectPool using the specified values.

Method Summary

Object borrowObject(Object key)
          Obtain an instance from my pool for the specified key.

void clear()
          Clears my pool, removing all pooled instances (optional operation).

void clear(Object key)
          Clears the specified pool, removing all pooled instances corresponding to the given key (optional operation).

void close()
          Close this pool, and free any resources associated with it.

int getMaxActive()
          Returns the cap on the total number of active instances from my pool.

int getMaxIdle()
          Returns the cap on the number of "idle" instances in the pool.

long getMaxWait()
          Returns the maximum amount of time (in milliseconds) the borrowObject(java.lang.Object) method should block before throwing an exception when the pool is exhausted and the "when exhausted" action is WHEN_EXHAUSTED_BLOCK.

long getMinEvictableIdleTimeMillis()
          Returns the minimum amount of time an object may sit idle in the pool before it is eligable for eviction by the idle object evictor (if any).

int getNumActive()
          Returns the total number of instances current borrowed from my pool but not yet returned (optional operation).

int getNumActive(Object key)
          Returns the number of instances currently borrowed from but not yet returned to my pool corresponding to the given key (optional operation).

int getNumIdle()
          Returns the total number of instances currently idle in my pool (optional operation).

int getNumIdle(Object key)
          Returns the number of instances corresponding to the given key currently idle in my pool (optional operation).

int getNumTestsPerEvictionRun()
          Returns the number of objects to examine during each run of the idle object evictor thread (if any).

boolean getTestOnBorrow()
          When true, objects will be validated before being returned by the borrowObject(java.lang.Object) method.

boolean getTestOnReturn()
          When true, objects will be validated before being returned to the pool within the returnObject(java.lang.Object, java.lang.Object).

boolean getTestWhileIdle()
          When true, objects will be validated by the idle object evictor (if any).

long getTimeBetweenEvictionRunsMillis()
          Returns the number of milliseconds to sleep between runs of the idle object evictor thread.

byte getWhenExhaustedAction()
          Returns the action to take when the borrowObject(java.lang.Object) method is invoked when the pool is exhausted (the maximum number of "active" objects has been reached).

void returnObject(Object key, Object obj)
          Return an instance to my pool.

void setConfig(GenericKeyedObjectPool.Config conf)
          Sets my configuration.

void setFactory(KeyedPoolableObjectFactory factory)
          Sets the factory I use to create new instances (optional operation).

void setMaxActive(int maxActive)
          Sets the cap on the total number of active instances from my pool.

void setMaxIdle(int maxIdle)
          Sets the cap on the number of "idle" instances in the pool.

void setMaxWait(long maxWait)
          Sets the maximum amount of time (in milliseconds) the borrowObject(java.lang.Object) method should block before throwing an exception when the pool is exhausted and the "when exhausted" action is WHEN_EXHAUSTED_BLOCK.

void setMinEvictableIdleTimeMillis(long minEvictableIdleTimeMillis)
          Sets the minimum amount of time an object may sit idle in the pool before it is eligable for eviction by the idle object evictor (if any).

void setNumTestsPerEvictionRun(int numTestsPerEvictionRun)
          Sets the number of objects to examine during each run of the idle object evictor thread (if any).

void setTestOnBorrow(boolean testOnBorrow)
          When true, objects will be validated before being returned by the borrowObject(java.lang.Object) method.

void setTestOnReturn(boolean testOnReturn)
          When true, objects will be validated before being returned to the pool within the returnObject(java.lang.Object, java.lang.Object).

void setTestWhileIdle(boolean testWhileIdle)
          When true, objects will be validated by the idle object evictor (if any).

void setTimeBetweenEvictionRunsMillis(long timeBetweenEvictionRunsMillis)
          Sets the number of milliseconds to sleep between runs of the idle object evictor thread.

void setWhenExhaustedAction(byte whenExhaustedAction)
          Sets the action to take when the borrowObject(java.lang.Object) method is invoked when the pool is exhausted (the maximum number of "active" objects has been reached).

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_MAX_ACTIVE

public static final int DEFAULT_MAX_ACTIVE

The default cap on the total number of active instances from the pool (per key).

See Also:: getMaxActive(), setMaxActive(int), Constant Field Values

DEFAULT_MAX_IDLE

public static final int DEFAULT_MAX_IDLE

The default cap on the number of idle instances in the pool (per key).

See Also:: getMaxIdle(), setMaxIdle(int), Constant Field Values

DEFAULT_MAX_WAIT

public static final long DEFAULT_MAX_WAIT

The default maximum amount of time (in millis) the borrowObject(java.lang.Object) method should block before throwing an exception when the pool is exhausted and the "when exhausted" action is WHEN_EXHAUSTED_BLOCK.

See Also:: getMaxWait(), setMaxWait(long), Constant Field Values

DEFAULT_MIN_EVICTABLE_IDLE_TIME_MILLIS

public static final long DEFAULT_MIN_EVICTABLE_IDLE_TIME_MILLIS

The default value for getMinEvictableIdleTimeMillis().

See Also:: getMinEvictableIdleTimeMillis(), setMinEvictableIdleTimeMillis(long), Constant Field Values

DEFAULT_NUM_TESTS_PER_EVICTION_RUN

public static final int DEFAULT_NUM_TESTS_PER_EVICTION_RUN

The default number of objects to examine per run in the idle object evictor.

See Also:: getNumTestsPerEvictionRun(), setNumTestsPerEvictionRun(int), getTimeBetweenEvictionRunsMillis(), setTimeBetweenEvictionRunsMillis(long), Constant Field Values

DEFAULT_TEST_ON_BORROW

public static final boolean DEFAULT_TEST_ON_BORROW

The default "test on borrow" value.

See Also:: getTestOnBorrow(), setTestOnBorrow(boolean), Constant Field Values

DEFAULT_TEST_ON_RETURN

public static final boolean DEFAULT_TEST_ON_RETURN

The default "test on return" value.

See Also:: getTestOnReturn(), setTestOnReturn(boolean), Constant Field Values

DEFAULT_TEST_WHILE_IDLE

public static final boolean DEFAULT_TEST_WHILE_IDLE

The default "test while idle" value.

See Also:: getTestWhileIdle(), setTestWhileIdle(boolean), getTimeBetweenEvictionRunsMillis(), setTimeBetweenEvictionRunsMillis(long), Constant Field Values

DEFAULT_TIME_BETWEEN_EVICTION_RUNS_MILLIS

public static final long DEFAULT_TIME_BETWEEN_EVICTION_RUNS_MILLIS

The default "time between eviction runs" value.

See Also:: getTimeBetweenEvictionRunsMillis(), setTimeBetweenEvictionRunsMillis(long), Constant Field Values

DEFAULT_WHEN_EXHAUSTED_ACTION

public static final byte DEFAULT_WHEN_EXHAUSTED_ACTION

The default "when exhausted action" for the pool.

See Also:: WHEN_EXHAUSTED_BLOCK, WHEN_EXHAUSTED_FAIL, WHEN_EXHAUSTED_GROW, setWhenExhaustedAction(byte), Constant Field Values

WHEN_EXHAUSTED_BLOCK

public static final byte WHEN_EXHAUSTED_BLOCK

A "when exhausted action" type indicating that when the pool is exhausted (i.e., the maximum number of active objects has been reached), the borrowObject(java.lang.Object) method should block until a new object is available, or the maximum wait time has been reached.

See Also:: WHEN_EXHAUSTED_FAIL, WHEN_EXHAUSTED_GROW, setMaxWait(long), getMaxWait(), setWhenExhaustedAction(byte), Constant Field Values

WHEN_EXHAUSTED_FAIL

public static final byte WHEN_EXHAUSTED_FAIL

See Also:: WHEN_EXHAUSTED_BLOCK, WHEN_EXHAUSTED_GROW, setWhenExhaustedAction(byte), Constant Field Values

WHEN_EXHAUSTED_GROW

public static final byte WHEN_EXHAUSTED_GROW

See Also:: WHEN_EXHAUSTED_FAIL, WHEN_EXHAUSTED_GROW, setWhenExhaustedAction(byte), Constant Field Values

Constructor Detail

GenericKeyedObjectPool

public GenericKeyedObjectPool(KeyedPoolableObjectFactory factory)

Create a new GenericKeyedObjectPool using the specified values.
Parameters:: factory - the (possibly null)KeyedPoolableObjectFactory to use to create, validate and destroy objects

GenericKeyedObjectPool

public GenericKeyedObjectPool(KeyedPoolableObjectFactory factory,
                              GenericKeyedObjectPool.Config config)

Create a new GenericKeyedObjectPool using the specified values.
Parameters:: factory - the (possibly null)KeyedPoolableObjectFactory to use to create, validate and destroy objects; config - a non-null GenericKeyedObjectPool.Config describing my configuration

GenericKeyedObjectPool

public GenericKeyedObjectPool(KeyedPoolableObjectFactory factory,
                              int maxActive)

Create a new GenericKeyedObjectPool using the specified values.
Parameters:: factory - the (possibly null)KeyedPoolableObjectFactory to use to create, validate and destroy objects; maxActive - the maximum number of objects that can be borrowed from me at one time (per key) (see setMaxActive(int))

GenericKeyedObjectPool

public GenericKeyedObjectPool(KeyedPoolableObjectFactory factory,
                              int maxActive,
                              byte whenExhaustedAction,
                              long maxWait)

Create a new GenericKeyedObjectPool using the specified values.
Parameters:: factory - the (possibly null)KeyedPoolableObjectFactory to use to create, validate and destroy objects; maxActive - the maximum number of objects that can be borrowed from me at one time (per key) (see setMaxActive(int)); whenExhaustedAction - the action to take when the pool is exhausted (see setWhenExhaustedAction(byte)); maxWait - the maximum amount of time to wait for an idle object when the pool is exhausted an and whenExhaustedAction is WHEN_EXHAUSTED_BLOCK (otherwise ignored) (see setMaxWait(long))

GenericKeyedObjectPool

public GenericKeyedObjectPool(KeyedPoolableObjectFactory factory,
                              int maxActive,
                              byte whenExhaustedAction,
                              long maxWait,
                              boolean testOnBorrow,
                              boolean testOnReturn)

Create a new GenericKeyedObjectPool using the specified values.
Parameters:: factory - the (possibly null)KeyedPoolableObjectFactory to use to create, validate and destroy objects; maxActive - the maximum number of objects that can be borrowed from me at one time (per key) (see setMaxActive(int)); maxWait - the maximum amount of time to wait for an idle object when the pool is exhausted an and whenExhaustedAction is WHEN_EXHAUSTED_BLOCK (otherwise ignored) (see setMaxWait(long)); whenExhaustedAction - the action to take when the pool is exhausted (see setWhenExhaustedAction(byte)); testOnBorrow - whether or not to validate objects before they are returned by the borrowObject(java.lang.Object) method (see setTestOnBorrow(boolean)); testOnReturn - whether or not to validate objects after they are returned to the returnObject(java.lang.Object, java.lang.Object) method (see setTestOnReturn(boolean))

GenericKeyedObjectPool

public GenericKeyedObjectPool(KeyedPoolableObjectFactory factory,
                              int maxActive,
                              byte whenExhaustedAction,
                              long maxWait,
                              int maxIdle)

Create a new GenericKeyedObjectPool using the specified values.
Parameters:: factory - the (possibly null)KeyedPoolableObjectFactory to use to create, validate and destroy objects; maxActive - the maximum number of objects that can be borrowed from me at one time (per key) (see setMaxActive(int)); whenExhaustedAction - the action to take when the pool is exhausted (see setWhenExhaustedAction(byte)); maxWait - the maximum amount of time to wait for an idle object when the pool is exhausted an and whenExhaustedAction is WHEN_EXHAUSTED_BLOCK (otherwise ignored) (see setMaxWait(long)); maxIdle - the maximum number of idle objects in my pool (per key) (see setMaxIdle(int))

GenericKeyedObjectPool

public GenericKeyedObjectPool(KeyedPoolableObjectFactory factory,
                              int maxActive,
                              byte whenExhaustedAction,
                              long maxWait,
                              int maxIdle,
                              boolean testOnBorrow,
                              boolean testOnReturn)

Create a new GenericKeyedObjectPool using the specified values.
Parameters:: factory - the (possibly null)KeyedPoolableObjectFactory to use to create, validate and destroy objects; maxActive - the maximum number of objects that can be borrowed from me at one time (per key) (see setMaxActive(int)); whenExhaustedAction - the action to take when the pool is exhausted (see setWhenExhaustedAction(byte)); maxWait - the maximum amount of time to wait for an idle object when the pool is exhausted an and whenExhaustedAction is WHEN_EXHAUSTED_BLOCK (otherwise ignored) (see getMaxWait()); maxIdle - the maximum number of idle objects in my pool (see setMaxIdle(int)); testOnBorrow - whether or not to validate objects before they are returned by the borrowObject(java.lang.Object) method (see setTestOnBorrow(boolean)); testOnReturn - whether or not to validate objects after they are returned to the returnObject(java.lang.Object, java.lang.Object) method (see setTestOnReturn(boolean))

GenericKeyedObjectPool

public GenericKeyedObjectPool(KeyedPoolableObjectFactory factory,
                              int maxActive,
                              byte whenExhaustedAction,
                              long maxWait,
                              int maxIdle,
                              boolean testOnBorrow,
                              boolean testOnReturn,
                              long timeBetweenEvictionRunsMillis,
                              int numTestsPerEvictionRun,
                              long minEvictableIdleTimeMillis,
                              boolean testWhileIdle)

Create a new GenericKeyedObjectPool using the specified values.
Parameters:: factory - the (possibly null)PoolableObjectFactory to use to create, validate and destroy objects; maxActive - the maximum number of objects that can be borrowed from me at one time (per key) (see setMaxActive(int)); whenExhaustedAction - the action to take when the pool is exhausted (see setWhenExhaustedAction(byte)); maxWait - the maximum amount of time to wait for an idle object when the pool is exhausted an and whenExhaustedAction is WHEN_EXHAUSTED_BLOCK (otherwise ignored) (see setMaxWait(long)); maxIdle - the maximum number of idle objects in my pool (see setMaxIdle(int)); testOnBorrow - whether or not to validate objects before they are returned by the borrowObject(java.lang.Object) method (see setTestOnBorrow(boolean)); testOnReturn - whether or not to validate objects after they are returned to the returnObject(java.lang.Object, java.lang.Object) method (see setTestOnReturn(boolean)); timeBetweenEvictionRunsMillis - the amount of time (in milliseconds) to sleep between examining idle objects for eviction (see setTimeBetweenEvictionRunsMillis(long)); numTestsPerEvictionRun - the number of idle objects to examine per run within the idle object eviction thread (if any) (see setNumTestsPerEvictionRun(int)); minEvictableIdleTimeMillis - the minimum number of milliseconds an object can sit idle in the pool before it is eligable for evcition (see setMinEvictableIdleTimeMillis(long)); testWhileIdle - whether or not to validate objects in the idle object eviction thread, if any (see setTestWhileIdle(boolean))

Method Detail

borrowObject

public Object borrowObject(Object key)
                    throws Exception

Description copied from interface: KeyedObjectPool

Obtain an instance from my pool for the specified key. By contract, clients MUST return the borrowed object using returnObject, or a related method as defined in an implementation or sub-interface, using a key that is equivalent to the one used to borrow the instance in the first place.

Specified by:: borrowObject in interface KeyedObjectPool
Specified by:: borrowObject in class BaseKeyedObjectPool

Parameters:: key - the key used to obtain the object
Returns:: an instance from my pool.; Exception

clear

public void clear()

Description copied from interface: KeyedObjectPool

Clears my pool, removing all pooled instances (optional operation). Throws UnsupportedOperationException if the pool cannot be cleared.

Specified by:: clear in interface KeyedObjectPool
Overrides:: clear in class BaseKeyedObjectPool

clear

public void clear(Object key)

Description copied from interface: KeyedObjectPool

Clears the specified pool, removing all pooled instances corresponding to the given key (optional operation). Throws UnsupportedOperationException if the pool cannot be cleared.

Specified by:: clear in interface KeyedObjectPool
Overrides:: clear in class BaseKeyedObjectPool

Parameters:: key - the key to clear

close

public void close()
           throws Exception

Description copied from interface: KeyedObjectPool

Close this pool, and free any resources associated with it.

Specified by:: close in interface KeyedObjectPool
Overrides:: close in class BaseKeyedObjectPool

Exception

getMaxActive

public int getMaxActive()

Returns the cap on the total number of active instances from my pool.

Returns:: the cap on the total number of active instances from my pool.
See Also:: setMaxActive(int)

getMaxIdle

public int getMaxIdle()

Returns the cap on the number of "idle" instances in the pool.

Returns:: the cap on the number of "idle" instances in the pool.
See Also:: setMaxIdle(int)

getMaxWait

public long getMaxWait()

Returns the maximum amount of time (in milliseconds) the borrowObject(java.lang.Object) method should block before throwing an exception when the pool is exhausted and the "when exhausted" action is WHEN_EXHAUSTED_BLOCK. When less than 0, the borrowObject(java.lang.Object) method may block indefinitely.

See Also:: setMaxWait(long), setWhenExhaustedAction(byte), WHEN_EXHAUSTED_BLOCK

getMinEvictableIdleTimeMillis

public long getMinEvictableIdleTimeMillis()

Returns the minimum amount of time an object may sit idle in the pool before it is eligable for eviction by the idle object evictor (if any).

See Also:: setMinEvictableIdleTimeMillis(long), setTimeBetweenEvictionRunsMillis(long)

getNumActive

public int getNumActive()

Description copied from interface: KeyedObjectPool

Returns the total number of instances current borrowed from my pool but not yet returned (optional operation). Throws UnsupportedOperationException if this information is not available.

Specified by:: getNumActive in interface KeyedObjectPool
Overrides:: getNumActive in class BaseKeyedObjectPool

Returns:: the total number of instances currently borrowed from my pool

getNumActive

public int getNumActive(Object key)

Description copied from interface: KeyedObjectPool

Returns the number of instances currently borrowed from but not yet returned to my pool corresponding to the given key (optional operation). Throws UnsupportedOperationException if this information is not available.

Specified by:: getNumActive in interface KeyedObjectPool
Overrides:: getNumActive in class BaseKeyedObjectPool

Parameters:: key - the key
Returns:: the number of instances corresponding to the given key currently borrowed in my pool

getNumIdle

public int getNumIdle()

Description copied from interface: KeyedObjectPool

Returns the total number of instances currently idle in my pool (optional operation). Throws UnsupportedOperationException if this information is not available.

Specified by:: getNumIdle in interface KeyedObjectPool
Overrides:: getNumIdle in class BaseKeyedObjectPool

Returns:: the total number of instances currently idle in my pool

getNumIdle

public int getNumIdle(Object key)

Description copied from interface: KeyedObjectPool

Returns the number of instances corresponding to the given key currently idle in my pool (optional operation). Throws UnsupportedOperationException if this information is not available.

Specified by:: getNumIdle in interface KeyedObjectPool
Overrides:: getNumIdle in class BaseKeyedObjectPool

Parameters:: key - the key
Returns:: the number of instances corresponding to the given key currently idle in my pool

getNumTestsPerEvictionRun

public int getNumTestsPerEvictionRun()

Returns the number of objects to examine during each run of the idle object evictor thread (if any).

See Also:: setNumTestsPerEvictionRun(int), setTimeBetweenEvictionRunsMillis(long)

getTestOnBorrow

public boolean getTestOnBorrow()

When true, objects will be validated before being returned by the borrowObject(java.lang.Object) method. If the object fails to validate, it will be dropped from the pool, and we will attempt to borrow another.

See Also:: setTestOnBorrow(boolean)

getTestOnReturn

public boolean getTestOnReturn()

When true, objects will be validated before being returned to the pool within the returnObject(java.lang.Object, java.lang.Object).

See Also:: setTestOnReturn(boolean)

getTestWhileIdle

public boolean getTestWhileIdle()

When true, objects will be validated by the idle object evictor (if any). If an object fails to validate, it will be dropped from the pool.

See Also:: setTestWhileIdle(boolean), setTimeBetweenEvictionRunsMillis(long)

getTimeBetweenEvictionRunsMillis

public long getTimeBetweenEvictionRunsMillis()

Returns the number of milliseconds to sleep between runs of the idle object evictor thread. When non-positive, no idle object evictor thread will be run.

See Also:: setTimeBetweenEvictionRunsMillis(long)

getWhenExhaustedAction

public byte getWhenExhaustedAction()

Returns the action to take when the borrowObject(java.lang.Object) method is invoked when the pool is exhausted (the maximum number of "active" objects has been reached).

Returns:: one of WHEN_EXHAUSTED_BLOCK, WHEN_EXHAUSTED_FAIL or WHEN_EXHAUSTED_GROW
See Also:: setWhenExhaustedAction(byte)

returnObject

public void returnObject(Object key,
                         Object obj)
                  throws Exception

Description copied from interface: KeyedObjectPool

Return an instance to my pool. By contract, obj MUST have been obtained using borrowObject or a related method as defined in an implementation or sub-interface, using a key that is equivalent to the one used to borrow the Object in the first place.

Specified by:: returnObject in interface KeyedObjectPool
Specified by:: returnObject in class BaseKeyedObjectPool

Parameters:: key - the key used to obtain the object; obj - a borrowed instance to be returned.; Exception

setConfig

public void setConfig(GenericKeyedObjectPool.Config conf)

Sets my configuration.

See Also:: GenericKeyedObjectPool.Config

setFactory

public void setFactory(KeyedPoolableObjectFactory factory)
                throws IllegalStateException

Description copied from interface: KeyedObjectPool

Sets the factory I use to create new instances (optional operation).

Specified by:: setFactory in interface KeyedObjectPool
Overrides:: setFactory in class BaseKeyedObjectPool

Parameters:: factory - the KeyedPoolableObjectFactory I use to create new instances.
Throws:: IllegalStateException - when the factory cannot be set at this time

setMaxActive

public void setMaxActive(int maxActive)

Sets the cap on the total number of active instances from my pool.

Parameters:: maxActive - The cap on the total number of active instances from my pool. Use a negative value for an infinite number of instances.
See Also:: getMaxActive()

setMaxIdle

public void setMaxIdle(int maxIdle)

Sets the cap on the number of "idle" instances in the pool.

Parameters:: maxIdle - The cap on the number of "idle" instances in the pool. Use a negative value to indicate an unlimited number of idle instances.
See Also:: getMaxIdle()

setMaxWait

public void setMaxWait(long maxWait)

Sets the maximum amount of time (in milliseconds) the borrowObject(java.lang.Object) method should block before throwing an exception when the pool is exhausted and the "when exhausted" action is WHEN_EXHAUSTED_BLOCK. When less than 0, the borrowObject(java.lang.Object) method may block indefinitely.

See Also:: getMaxWait(), setWhenExhaustedAction(byte), WHEN_EXHAUSTED_BLOCK

setMinEvictableIdleTimeMillis

public void setMinEvictableIdleTimeMillis(long minEvictableIdleTimeMillis)

Sets the minimum amount of time an object may sit idle in the pool before it is eligable for eviction by the idle object evictor (if any). When non-positive, no objects will be evicted from the pool due to idle time alone.

See Also:: getMinEvictableIdleTimeMillis(), setTimeBetweenEvictionRunsMillis(long)

setNumTestsPerEvictionRun

public void setNumTestsPerEvictionRun(int numTestsPerEvictionRun)

Sets the number of objects to examine during each run of the idle object evictor thread (if any).

When a negative value is supplied, ceil(BaseKeyedObjectPool.numIdle(java.lang.Object))/abs(getNumTestsPerEvictionRun()) tests will be run. I.e., when the value is -n, roughly one nth of the idle objects will be tested per run.

See Also:: getNumTestsPerEvictionRun(), setTimeBetweenEvictionRunsMillis(long)

setTestOnBorrow

public void setTestOnBorrow(boolean testOnBorrow)

See Also:: getTestOnBorrow()

setTestOnReturn

public void setTestOnReturn(boolean testOnReturn)

When true, objects will be validated before being returned to the pool within the returnObject(java.lang.Object, java.lang.Object).

See Also:: getTestOnReturn()

setTestWhileIdle

public void setTestWhileIdle(boolean testWhileIdle)

When true, objects will be validated by the idle object evictor (if any). If an object fails to validate, it will be dropped from the pool.

See Also:: getTestWhileIdle(), setTimeBetweenEvictionRunsMillis(long)

setTimeBetweenEvictionRunsMillis

public void setTimeBetweenEvictionRunsMillis(long timeBetweenEvictionRunsMillis)

Sets the number of milliseconds to sleep between runs of the idle object evictor thread. When non-positive, no idle object evictor thread will be run.

See Also:: getTimeBetweenEvictionRunsMillis()

setWhenExhaustedAction

public void setWhenExhaustedAction(byte whenExhaustedAction)

Sets the action to take when the borrowObject(java.lang.Object) method is invoked when the pool is exhausted (the maximum number of "active" objects has been reached).

Parameters:: whenExhaustedAction - the action code, which must be one of WHEN_EXHAUSTED_BLOCK, WHEN_EXHAUSTED_FAIL, or WHEN_EXHAUSTED_GROW
See Also:: getWhenExhaustedAction()

Overview

Package

Class

Index

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

Nested Class Summary
`static class`	`GenericKeyedObjectPool.Config` A simple "struct" encapsulating the configuration information for a `GenericKeyedObjectPool`.

Field Summary
`static int`	`DEFAULT_MAX_ACTIVE` The default cap on the total number of active instances from the pool (per key).
`static int`	`DEFAULT_MAX_IDLE` The default cap on the number of idle instances in the pool (per key).
`static long`	`DEFAULT_MAX_WAIT` The default maximum amount of time (in millis) the `borrowObject(java.lang.Object)` method should block before throwing an exception when the pool is exhausted and the `"when exhausted" action` is `WHEN_EXHAUSTED_BLOCK`.
`static long`	`DEFAULT_MIN_EVICTABLE_IDLE_TIME_MILLIS` The default value for `getMinEvictableIdleTimeMillis()`.
`static int`	`DEFAULT_NUM_TESTS_PER_EVICTION_RUN` The default number of objects to examine per run in the idle object evictor.
`static boolean`	`DEFAULT_TEST_ON_BORROW` The default "test on borrow" value.
`static boolean`	`DEFAULT_TEST_ON_RETURN` The default "test on return" value.
`static boolean`	`DEFAULT_TEST_WHILE_IDLE` The default "test while idle" value.
`static long`	`DEFAULT_TIME_BETWEEN_EVICTION_RUNS_MILLIS` The default "time between eviction runs" value.
`static byte`	`DEFAULT_WHEN_EXHAUSTED_ACTION` The default "when exhausted action" for the pool.
`static byte`	`WHEN_EXHAUSTED_BLOCK` A "when exhausted action" type indicating that when the pool is exhausted (i.e., the maximum number of active objects has been reached), the `borrowObject(java.lang.Object)` method should block until a new object is available, or the `maximum wait time` has been reached.
`static byte`	`WHEN_EXHAUSTED_FAIL` A "when exhausted action" type indicating that when the pool is exhausted (i.e., the maximum number of active objects has been reached), the `borrowObject(java.lang.Object)` method should fail, throwing a `NoSuchElementException`.
`static byte`	`WHEN_EXHAUSTED_GROW` A "when exhausted action" type indicating that when the pool is exhausted (i.e., the maximum number of active objects has been reached), the `borrowObject(java.lang.Object)` method should simply create a new object anyway.

Constructor Summary
`GenericKeyedObjectPool(KeyedPoolableObjectFactory factory)` Create a new `GenericKeyedObjectPool` using the specified values.
`GenericKeyedObjectPool(KeyedPoolableObjectFactory factory, GenericKeyedObjectPool.Config config)` Create a new `GenericKeyedObjectPool` using the specified values.
`GenericKeyedObjectPool(KeyedPoolableObjectFactory factory, int maxActive)` Create a new `GenericKeyedObjectPool` using the specified values.
`GenericKeyedObjectPool(KeyedPoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait)` Create a new `GenericKeyedObjectPool` using the specified values.
`GenericKeyedObjectPool(KeyedPoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait, boolean testOnBorrow, boolean testOnReturn)` Create a new `GenericKeyedObjectPool` using the specified values.
`GenericKeyedObjectPool(KeyedPoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait, int maxIdle)` Create a new `GenericKeyedObjectPool` using the specified values.
`GenericKeyedObjectPool(KeyedPoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait, int maxIdle, boolean testOnBorrow, boolean testOnReturn)` Create a new `GenericKeyedObjectPool` using the specified values.
`GenericKeyedObjectPool(KeyedPoolableObjectFactory factory, int maxActive, byte whenExhaustedAction, long maxWait, int maxIdle, boolean testOnBorrow, boolean testOnReturn, long timeBetweenEvictionRunsMillis, int numTestsPerEvictionRun, long minEvictableIdleTimeMillis, boolean testWhileIdle)` Create a new `GenericKeyedObjectPool` using the specified values.

Method Summary
`Object`	`borrowObject(Object key)` Obtain an instance from my pool for the specified key.
`void`	`clear()` Clears my pool, removing all pooled instances (optional operation).
`void`	`clear(Object key)` Clears the specified pool, removing all pooled instances corresponding to the given key (optional operation).
`void`	`close()` Close this pool, and free any resources associated with it.
`int`	`getMaxActive()` Returns the cap on the total number of active instances from my pool.
`int`	`getMaxIdle()` Returns the cap on the number of "idle" instances in the pool.
`long`	`getMaxWait()` Returns the maximum amount of time (in milliseconds) the `borrowObject(java.lang.Object)` method should block before throwing an exception when the pool is exhausted and the `"when exhausted" action` is `WHEN_EXHAUSTED_BLOCK`.
`long`	`getMinEvictableIdleTimeMillis()` Returns the minimum amount of time an object may sit idle in the pool before it is eligable for eviction by the idle object evictor (if any).
`int`	`getNumActive()` Returns the total number of instances current borrowed from my pool but not yet returned (optional operation).
`int`	`getNumActive(Object key)` Returns the number of instances currently borrowed from but not yet returned to my pool corresponding to the given key (optional operation).
`int`	`getNumIdle()` Returns the total number of instances currently idle in my pool (optional operation).
`int`	`getNumIdle(Object key)` Returns the number of instances corresponding to the given key currently idle in my pool (optional operation).
`int`	`getNumTestsPerEvictionRun()` Returns the number of objects to examine during each run of the idle object evictor thread (if any).
`boolean`	`getTestOnBorrow()` When `true`, objects will be `validated` before being returned by the `borrowObject(java.lang.Object)` method.
`boolean`	`getTestOnReturn()` When `true`, objects will be `validated` before being returned to the pool within the `returnObject(java.lang.Object, java.lang.Object)`.
`boolean`	`getTestWhileIdle()` When `true`, objects will be `validated` by the idle object evictor (if any).
`long`	`getTimeBetweenEvictionRunsMillis()` Returns the number of milliseconds to sleep between runs of the idle object evictor thread.
`byte`	`getWhenExhaustedAction()` Returns the action to take when the `borrowObject(java.lang.Object)` method is invoked when the pool is exhausted (the maximum number of "active" objects has been reached).
`void`	`returnObject(Object key, Object obj)` Return an instance to my pool.
`void`	`setConfig(GenericKeyedObjectPool.Config conf)` Sets my configuration.
`void`	`setFactory(KeyedPoolableObjectFactory factory)` Sets the `factory` I use to create new instances (optional operation).
`void`	`setMaxActive(int maxActive)` Sets the cap on the total number of active instances from my pool.
`void`	`setMaxIdle(int maxIdle)` Sets the cap on the number of "idle" instances in the pool.
`void`	`setMaxWait(long maxWait)` Sets the maximum amount of time (in milliseconds) the `borrowObject(java.lang.Object)` method should block before throwing an exception when the pool is exhausted and the `"when exhausted" action` is `WHEN_EXHAUSTED_BLOCK`.
`void`	`setMinEvictableIdleTimeMillis(long minEvictableIdleTimeMillis)` Sets the minimum amount of time an object may sit idle in the pool before it is eligable for eviction by the idle object evictor (if any).
`void`	`setNumTestsPerEvictionRun(int numTestsPerEvictionRun)` Sets the number of objects to examine during each run of the idle object evictor thread (if any).
`void`	`setTestOnBorrow(boolean testOnBorrow)` When `true`, objects will be `validated` before being returned by the `borrowObject(java.lang.Object)` method.
`void`	`setTestOnReturn(boolean testOnReturn)` When `true`, objects will be `validated` before being returned to the pool within the `returnObject(java.lang.Object, java.lang.Object)`.
`void`	`setTestWhileIdle(boolean testWhileIdle)` When `true`, objects will be `validated` by the idle object evictor (if any).
`void`	`setTimeBetweenEvictionRunsMillis(long timeBetweenEvictionRunsMillis)` Sets the number of milliseconds to sleep between runs of the idle object evictor thread.
`void`	`setWhenExhaustedAction(byte whenExhaustedAction)` Sets the action to take when the `borrowObject(java.lang.Object)` method is invoked when the pool is exhausted (the maximum number of "active" objects has been reached).

org.apache.commons.pool.impl Class GenericKeyedObjectPool

DEFAULT_MAX_ACTIVE

DEFAULT_MAX_IDLE

DEFAULT_MAX_WAIT

DEFAULT_MIN_EVICTABLE_IDLE_TIME_MILLIS

DEFAULT_NUM_TESTS_PER_EVICTION_RUN

DEFAULT_TEST_ON_BORROW

DEFAULT_TEST_ON_RETURN

DEFAULT_TEST_WHILE_IDLE

DEFAULT_TIME_BETWEEN_EVICTION_RUNS_MILLIS

DEFAULT_WHEN_EXHAUSTED_ACTION

WHEN_EXHAUSTED_BLOCK

WHEN_EXHAUSTED_FAIL

WHEN_EXHAUSTED_GROW

GenericKeyedObjectPool

GenericKeyedObjectPool

GenericKeyedObjectPool

GenericKeyedObjectPool

GenericKeyedObjectPool

GenericKeyedObjectPool

GenericKeyedObjectPool

GenericKeyedObjectPool

borrowObject

clear

clear

close

getMaxActive

getMaxIdle

getMaxWait

getMinEvictableIdleTimeMillis

getNumActive

getNumActive

getNumIdle

getNumIdle

getNumTestsPerEvictionRun

getTestOnBorrow

getTestOnReturn

getTestWhileIdle

getTimeBetweenEvictionRunsMillis

getWhenExhaustedAction

returnObject

setConfig

setFactory

setMaxActive

setMaxIdle

setMaxWait

setMinEvictableIdleTimeMillis

setNumTestsPerEvictionRun

setTestOnBorrow

setTestOnReturn

setTestWhileIdle

setTimeBetweenEvictionRunsMillis

setWhenExhaustedAction

org.apache.commons.pool.impl
Class GenericKeyedObjectPool