KeyedPooledObjectFactory (Apache Commons Pool 2.4 API)

+
+
Type Parameters:
+
K - The type of keys managed by this factory.
+
V - Type of element managed by this factory.
+
+
+
All Known Implementing Classes:
+
BaseKeyedPooledObjectFactory
+
+
+
+
```
public interface KeyedPooledObjectFactory<K,V>
```
+
An interface defining life-cycle methods for + instances to be served by a KeyedObjectPool. +
+ By contract, when an KeyedObjectPool + delegates to a KeyedPooledObjectFactory, +
1. + makeObject(K) is called whenever a new instance is needed. +
2. + activateObject(K, org.apache.commons.pool2.PooledObject<V>) is invoked on every instance that has been + passivated before it is + borrowed from the pool. +
3. + validateObject(K, org.apache.commons.pool2.PooledObject<V>) may be invoked on activated + instances to make sure they can be + borrowed from the pool. + validateObject may also be used to test an + instance being returned to the pool + before it is passivated. It will only be invoked + on an activated instance. +
4. + passivateObject + is invoked on every instance when it is returned to the pool. +
5. + destroyObject + is invoked on every instance when it is being "dropped" from the + pool (whether due to the response from validateObject, + or for reasons specific to the pool implementation.) There is no + guarantee that the instance being destroyed will + be considered active, passive or in a generally consistent state. +
+ KeyedPooledObjectFactory must be thread-safe. The only promise + an KeyedObjectPool makes is that the same instance of an object will + not be passed to more than one method of a + KeyedPoolableObjectFactory at a time. +
+ While clients of a KeyedObjectPool borrow and return instances of + the underlying value type V, the factory methods act on instances of + PooledObject<V>. These are the object wrappers that + pools use to track and maintain state informations about the objects that + they manage.
+
+
Since:
+
2.0
+
Version:
+
$Revision: 1333925 $
+
See Also:
+
KeyedObjectPool, +BaseKeyedPooledObjectFactory
+
+

+ +

Method Summary

+ + + + + + + + + + + + + + + + + + + + + + + + + + +

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`void`	`activateObject(K key, + PooledObject<V> p)` + Reinitialize an instance to be returned by the pool. +
`void`	`destroyObject(K key, + PooledObject<V> p)` + Destroy an instance no longer needed by the pool. +
`PooledObject<V>`	`makeObject(K key)` + Create an instance that can be served by the pool and + wrap it in a `PooledObject` to be managed by the pool. +
`void`	`passivateObject(K key, + PooledObject<V> p)` + Uninitialize an instance to be returned to the idle object pool. +
`boolean`	`validateObject(K key, + PooledObject<V> p)` + Ensures that the instance is safe to be returned by the pool. +

+ +
- + + +
  Method Detail
  + + + + + +
  - +
    makeObject
    +
```
PooledObject<V> makeObject(K key)
+                    throws Exception
```
    +
    Create an instance that can be served by the pool and + wrap it in a PooledObject to be managed by the pool.
    +
    +
    Parameters:
    +
    key - the key used when constructing the object
    +
    Returns:
    +
    a PooledObject wrapping an instance that can + be served by the pool.
    +
    Throws:
    +
    Exception - if there is a problem creating a new instance, + this will be propagated to the code requesting an object.
    +
    +
  + + + + + +
  - +
    destroyObject
    +
```
void destroyObject(K key,
+                   PooledObject<V> p)
+            throws Exception
```
    +
    Destroy an instance no longer needed by the pool. +
    + It is important for implementations of this method to be aware that there + is no guarantee about what state obj will be in and the + implementation should be prepared to handle unexpected errors. +
    + Also, an implementation must take in to consideration that instances lost + to the garbage collector may never be destroyed.
    +
    +
    Parameters:
    +
    key - the key used when selecting the instance
    +
    p - a PooledObject wrapping the instance to be destroyed
    +
    Throws:
    +
    Exception - should be avoided as it may be swallowed by + the pool implementation.
    +
    See Also:
    +
    validateObject(K, org.apache.commons.pool2.PooledObject<V>), +KeyedObjectPool.invalidateObject(K, V)
    +
    +
  + + + + + +
  - +
    validateObject
    +
```
boolean validateObject(K key,
+                       PooledObject<V> p)
```
    +
    Ensures that the instance is safe to be returned by the pool.
    +
    +
    Parameters:
    +
    key - the key used when selecting the object
    +
    p - a PooledObject wrapping the instance to be validated
    +
    Returns:
    +
    false if obj is not valid and should + be dropped from the pool, true otherwise.
    +
    +
  + + + + + +
  - +
    activateObject
    +
```
void activateObject(K key,
+                    PooledObject<V> p)
+             throws Exception
```
    +
    Reinitialize an instance to be returned by the pool.
    +
    +
    Parameters:
    +
    key - the key used when selecting the object
    +
    p - a PooledObject wrapping the instance to be activated
    +
    Throws:
    +
    Exception - if there is a problem activating obj, + this exception may be swallowed by the pool.
    +
    See Also:
    +
    destroyObject(K, org.apache.commons.pool2.PooledObject<V>)
    +
    +
  + + + + + +
  - +
    passivateObject
    +
```
void passivateObject(K key,
+                     PooledObject<V> p)
+              throws Exception
```
    +
    Uninitialize an instance to be returned to the idle object pool.
    +
    +
    Parameters:
    +
    key - the key used when selecting the object
    +
    p - a PooledObject wrapping the instance to be passivated
    +
    Throws:
    +
    Exception - if there is a problem passivating obj, + this exception may be swallowed by the pool.
    +
    See Also:
    +
    destroyObject(K, org.apache.commons.pool2.PooledObject<V>)
    +
    +
  +
+

Type Parameters:: T - Type of element pooled in this pool.

All Known Implementing Classes:: BaseObjectPool, GenericObjectPool, ProxiedObjectPool, SoftReferenceObjectPool

+
+

public interface ObjectPool<T>

A pooling simple interface. +

+ Example of use: +

 Object obj = null;
+
+ try {
+     obj = pool.borrowObject();
+     try {
+         //...use the object...
+     } catch(Exception e) {
+         // invalidate the object
+         pool.invalidateObject(obj);
+         // do not return the object to the pool twice
+         obj = null;
+     } finally {
+         // make sure the object is returned to the pool
+         if(null != obj) {
+             pool.returnObject(obj);
+        }
+     }
+ } catch(Exception e) {
+       // failed to borrow an object
+ }

+ See BaseObjectPool for a simple base implementation.

Since:: 2.0
Version:: $Revision: 1566605 $
See Also:: PooledObjectFactory, +KeyedObjectPool, +BaseObjectPool

+ +

+ + +

Method Summary

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`void`	`addObject()` + Create an object using the `factory` or other + implementation dependent mechanism, passivate it, and then place it in + the idle object pool. +
`T`	`borrowObject()` + Obtains an instance from this pool. +
`void`	`clear()` + Clears any objects sitting idle in the pool, releasing any associated + resources (optional operation). +
`void`	`close()` + Close this pool, and free any resources associated with it. +
`int`	`getNumActive()` + Return the number of instances currently borrowed from this pool. +
`int`	`getNumIdle()` + Return the number of instances currently idle in this pool. +
`void`	`invalidateObject(T obj)` + Invalidates an object from the pool. +
`void`	`returnObject(T obj)` + Return an instance to the pool. +

+ +
- + + +
  Method Detail
  + + + +
  - +
    borrowObject
    +
```
T borrowObject()
+        throws Exception,
+               NoSuchElementException,
+               IllegalStateException
```
    +
    Obtains an instance from this pool. +
    + Instances returned from this method will have been either newly created + with PooledObjectFactory.makeObject() or will be a previously + idle object and have been activated with + PooledObjectFactory.activateObject(org.apache.commons.pool2.PooledObject<T>) and then validated with + PooledObjectFactory.validateObject(org.apache.commons.pool2.PooledObject<T>). +
    + By contract, clients must return the borrowed instance + using returnObject(T), invalidateObject(T), or a related + method as defined in an implementation or sub-interface. +
    + The behaviour of this method when the pool has been exhausted + is not strictly specified (although it may be specified by + implementations).
    +
    +
    Returns:
    +
    an instance from this pool.
    +
    Throws:
    +
    IllegalStateException - after close has been called on this pool.
    +
    Exception - when PooledObjectFactory.makeObject() throws an + exception.
    +
    NoSuchElementException - when the pool is exhausted and cannot or will not return + another instance.
    +
    +
  + + + + + +
  - +
    returnObject
    +
```
void returnObject(T obj)
+           throws Exception
```
    +
    Return an instance to the pool. By contract, obj + must have been obtained using borrowObject() or + a related method as defined in an implementation or sub-interface.
    +
    +
    Parameters:
    +
    obj - a borrowed instance to be returned.
    +
    Throws:
    +
    IllegalStateException - if an attempt is made to return an object to the pool that + is in any state other than allocated (i.e. borrowed). + Attempting to return an object more than once or attempting + to return an object that was never borrowed from the pool + will trigger this exception.
    +
    Exception - if an instance cannot be returned to the pool
    +
    +
  + + + + + +
  - +
    invalidateObject
    +
```
void invalidateObject(T obj)
+               throws Exception
```
    +
    Invalidates an object from the pool. +
    + By contract, obj must have been obtained + using borrowObject() or a related method as defined in an + implementation or sub-interface. +
    + 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:
    +
    obj - a borrowed instance to be disposed.
    +
    Throws:
    +
    Exception - if the instance cannot be invalidated
    +
    +
  + + + +
  - +
    addObject
    +
```
void addObject()
+        throws Exception,
+               IllegalStateException,
+               UnsupportedOperationException
```
    +
    Create an object using the factory or other + implementation dependent mechanism, passivate it, and then place it in + the idle object pool. addObject is useful for "pre-loading" + a pool with idle objects. (Optional operation).
    +
    +
    Throws:
    +
    Exception - when PooledObjectFactory.makeObject() fails.
    +
    IllegalStateException - after close() has been called on this pool.
    +
    UnsupportedOperationException - when this pool cannot add new idle objects.
    +
    +
  + + + +
  - +
    getNumIdle
    +
```
int getNumIdle()
```
    +
    Return the number of instances currently idle in this pool. This may be + considered an approximation of the number of objects that can be + borrowed without creating any new instances. + Returns a negative value if this information is not available.
    +
    +
    Returns:
    +
    the number of instances currently idle in this pool.
    +
    +
  + + + +
  - +
    getNumActive
    +
```
int getNumActive()
```
    +
    Return the number of instances currently borrowed from this pool. Returns + a negative value if this information is not available.
    +
    +
    Returns:
    +
    the number of instances currently borrowed from this pool.
    +
    +
  + + + +
  - +
    clear
    +
```
void clear()
+    throws Exception,
+           UnsupportedOperationException
```
    +
    Clears any objects sitting idle in the pool, releasing any associated + resources (optional operation). Idle objects cleared must be + PooledObjectFactory.destroyObject(PooledObject).
    +
    +
    Throws:
    +
    UnsupportedOperationException - if this implementation does not support the operation
    +
    Exception - if the pool cannot be cleared
    +
    +
  + + + +
  - +
    close
    +
```
void close()
```
    +
    Close this pool, and free any resources associated with it. +
    + Calling addObject() or borrowObject() after invoking this + method on a pool will cause them to throw an IllegalStateException. +
    + Implementations should silently fail if not all resources can be freed.
    +
  +
+

Interface KeyedPooledObjectFactory<K,V>

Method Summary

Method Detail

makeObject

destroyObject

validateObject

activateObject

passivateObject

Interface ObjectPool<T>

Method Summary

Method Detail

borrowObject

returnObject

invalidateObject

addObject

getNumIdle

getNumActive

clear

close