net.csdn.modules.thrift.pool
Interface ObjectPool<K,V>

All Known Implementing Classes:

BaseObjectPool

public interface ObjectPool<K,V>

Keyed object pooling interface ObjectPool interface mainly defines borrowObject, returnObject and removeObject. Example of use: Object obj = null; try { obj = pool.borrowObject(key, timeout); try { //...use the object... } catch(Exception e) { // invalidate the object try { pool.removeObject(key, obj); } catch(Exception ignore) { } // do not return the object to the pool twice obj = null; } finally { // make sure the object is returned to the pool if(obj != null) { try { pool.returnObject(key, obj); } catch(Exception ignore) { } } } } catch(Exception e) { // failed to borrow an object(pool exhausted, no valid object, interrupted or etc...) }

Author:

Bongjae Chang

Method Summary

V	borrowObject(K key, long timeoutInMillis) Obtains an instance from this pool Instances returned from this method will have been either newly created with createObject or will be a previously idle object and then validated with validateObject.
void	createAllMinObjects(K key) Create objects using the factory until pool's minimum size, and then place them in the idle object pool createAllMinObjects is useful for "pre-loading" a pool with idle objects.
void	destroy() Destroy this pool, and free any resources associated with it Calling other methods such as createAllMinObjects or borrowObject, returnObject or removeObject or removeAllObjects after invoking this method on a pool will cause them to throw an IllegalStateException.
int	getActiveCount(K key) Returns the number of instances currently borrowed from but not yet returned to the pool
int	getIdleCount(K key) Returns the number of instances currently idle in this pool
int	getPeakCount(K key) Returns the total peak number of instances
int	getPoolSize(K key) Returns the total number of instances
void	removeAllObjects(K key) Clears the specified pool, removing all pooled instances corresponding to the given key
void	removeObject(K key, V value) Removes(invalidates) an object from the pool By contract, value should have been obtained using borrowObject using a key that is equivalent to the one used to borrow the instance in the first place.
void	returnObject(K key, V value) Return an instance to the pool By contract, value should have been obtained using borrowObject using a key that is equivalent to the one used to borrow the instance in the first place.

Method Detail

createAllMinObjects

void createAllMinObjects(K key)
                         throws Exception

Create objects using the factory until pool's minimum size, and then place them in the idle object pool

createAllMinObjects is useful for "pre-loading" a pool with idle objects.

Parameters:

key - the key new instances should be added to

Throws:

Exception - if an unexpected exception occurred

borrowObject

V borrowObject(K key,
               long timeoutInMillis)
               throws PoolExhaustedException,
                      NoValidObjectException,
                      InterruptedException

Obtains an instance from this pool

Instances returned from this method will have been either newly created with createObject or will be a previously idle object and then validated with validateObject.

By contract, clients should return the borrowed instance using returnObject, removeObject

When the pool has been exhausted, a PoolExhaustedException will be thrown.

Parameters:

key - the key used to obtain the object

timeoutInMillis - the max time(milli-second) for borrowing the object. If the pool cannot return an instance in given time, PoolExhaustedException will be thrown.

Returns:

an instance from this pool

Throws:

PoolExhaustedException - when the pool is exhausted

NoValidObjectException - when the pool cannot or will not return another instance

InterruptedException - when the pool is interrupted

returnObject

void returnObject(K key,
                  V value)
                  throws Exception

Return an instance to the pool

By contract, value should have been obtained using borrowObject using a key that is equivalent to the one used to borrow the instance in the first place.

Parameters:

key - the key used to obtain the object

value - a borrowed instance to be returned

Throws:

Exception - if an unexpected exception occurred

removeObject

void removeObject(K key,
                  V value)
                  throws Exception

Removes(invalidates) an object from the pool

By contract, value should have been obtained using borrowObject using a key that is equivalent to the one used to borrow the instance in the first place.

This method should be used when an object that has been borrowed is determined (due to an exception or other problem) to be invalid.

Parameters:

key - the key used to obtain the object

value - a borrowed instance to be removed

Throws:

Exception - if an unexpected exception occurred

removeAllObjects

void removeAllObjects(K key)
                      throws Exception

Clears the specified pool, removing all pooled instances corresponding to the given key

Parameters:

key - the key to clear

Throws:

Exception - if an unexpected exception occurred

destroy

void destroy()

Destroy this pool, and free any resources associated with it

Calling other methods such as createAllMinObjects or borrowObject, returnObject or removeObject or removeAllObjects after invoking this method on a pool will cause them to throw an IllegalStateException.

getPoolSize

int getPoolSize(K key)

Returns the total number of instances

Parameters:

key - the key to query

Returns:

the total number of instances corresponding to the given key currently idle and active in this pool or a negative value if unsupported

getPeakCount

int getPeakCount(K key)

Returns the total peak number of instances

Parameters:

key - the key to query

Returns:

the peak number of instances corresponding to the given key or a negative value if unsupported

getActiveCount

int getActiveCount(K key)

Returns the number of instances currently borrowed from but not yet returned to the pool

Parameters:

key - the key to query

Returns:

the number of instances corresponding to the given key currently borrowed in this pool or a negative value if unsupported

getIdleCount

int getIdleCount(K key)

Returns the number of instances currently idle in this pool

Parameters:

key - the key to query

Returns:

the number of instances corresponding to the given key currently idle in this pool or a negative value if unsupported