BasePooledObjectFactory (Apache Commons Pool 2.5.0 API)

java.lang.Object
+
- org.apache.commons.pool2.BaseObject
- +
  - org.apache.commons.pool2.BasePooledObjectFactory<T>
  +
+

+
Type Parameters:
T - Type of element managed in this factory.
+
+
All Implemented Interfaces:
+
PooledObjectFactory<T>
+
+
+
+
```
public abstract class BasePooledObjectFactory<T>
+extends BaseObject
+implements PooledObjectFactory<T>
```
+
A base implementation of PoolableObjectFactory. +
+ All operations defined here are essentially no-op's. +
+ This class is immutable, and therefore thread-safe
+
Since:
+
2.0
+
See Also:
PooledObjectFactory, +BaseKeyedPooledObjectFactory
+

+ +

+ + +
Constructor Summary
+ + + + + + + + +
Constructors
Constructor and Description
BasePooledObjectFactory()
+

Constructors
Constructor and Description
`BasePooledObjectFactory()`

+ +

Method Summary

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

Methods
Modifier and Type	Method and Description
`void`	`activateObject(PooledObject<T> p)` + No-op. +
`abstract T`	`create()` + Creates an object instance, to be wrapped in a `PooledObject`. +
`void`	`destroyObject(PooledObject<T> p)` + No-op. +
`PooledObject<T>`	`makeObject()` + Create an instance that can be served by the pool and wrap it in a + `PooledObject` to be managed by the pool. +
`void`	`passivateObject(PooledObject<T> p)` + No-op. +
`boolean`	`validateObject(PooledObject<T> p)` + This implementation always returns `true`. +
`abstract PooledObject<T>`	`wrap(T obj)` + Wrap the provided instance with an implementation of + `PooledObject`. +

+ + +
Methods inherited from class org.apache.commons.pool2.BaseObject
+toString, toStringAppendFields

+ + +
Methods inherited from class java.lang.Object
+clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

+ +
- + + +
  Constructor Detail
  + + + +
  - +
    BasePooledObjectFactory
    +
```
public BasePooledObjectFactory()
```
    +
  +
+ +
- + + +
  Method Detail
  + + + +
  - +
    create
    +
```
public abstract T create()
+                  throws Exception
```
    +
    Creates an object instance, to be wrapped in a PooledObject. +
    This method must support concurrent, multi-threaded + activation.
    +
    Returns:
    an instance to 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.
    +
  + + + + + +
  - +
    wrap
    +
```
public abstract PooledObject<T> wrap(T obj)
```
    +
    Wrap the provided instance with an implementation of + PooledObject.
    +
    Parameters:
    obj - the instance to wrap
    +
    Returns:
    The provided instance, wrapped by a PooledObject
    +
  + + + +
  - +
    makeObject
    +
```
public PooledObject<T> makeObject()
+                           throws Exception
```
    +
    Description copied from interface: PooledObjectFactory
    +
    Create an instance that can be served by the pool and wrap it in a + PooledObject to be managed by the pool.
    +
    +
    Specified by:
    +
    makeObject in interface PooledObjectFactory<T>
    +
    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
    +
```
public void destroyObject(PooledObject<T> p)
+                   throws Exception
```
    +
    No-op.
    +
    +
    Specified by:
    +
    destroyObject in interface PooledObjectFactory<T>
    +
    Parameters:
    p - ignored
    +
    Throws:
    +
    Exception - should be avoided as it may be swallowed by + the pool implementation.
    See Also:
    PooledObjectFactory.validateObject(org.apache.commons.pool2.PooledObject<T>), +ObjectPool.invalidateObject(T)
    +
  + + + +
  - +
    validateObject
    +
```
public boolean validateObject(PooledObject<T> p)
```
    +
    This implementation always returns true.
    +
    +
    Specified by:
    +
    validateObject in interface PooledObjectFactory<T>
    +
    Parameters:
    p - ignored
    +
    Returns:
    true
    +
  + + + +
  - +
    activateObject
    +
```
public void activateObject(PooledObject<T> p)
+                    throws Exception
```
    +
    No-op.
    +
    +
    Specified by:
    +
    activateObject in interface PooledObjectFactory<T>
    +
    Parameters:
    p - ignored
    +
    Throws:
    +
    Exception - if there is a problem activating obj, + this exception may be swallowed by the pool.
    See Also:
    PooledObjectFactory.destroyObject(org.apache.commons.pool2.PooledObject<T>)
    +
  + + + +
  - +
    passivateObject
    +
```
public void passivateObject(PooledObject<T> p)
+                     throws Exception
```
    +
    No-op.
    +
    +
    Specified by:
    +
    passivateObject in interface PooledObjectFactory<T>
    +
    Parameters:
    p - ignored
    +
    Throws:
    +
    Exception - if there is a problem passivating obj, + this exception may be swallowed by the pool.
    See Also:
    PooledObjectFactory.destroyObject(org.apache.commons.pool2.PooledObject<T>)
    +
  +
+

+
Type Parameters:
K - The type of keys maintained by this pool.
V - Type of element pooled in this pool.
+
+
All Superinterfaces:
+
AutoCloseable, Closeable
+
+
+
All Known Implementing Classes:
+
GenericKeyedObjectPool, ProxiedKeyedObjectPool
+
+
+
+
```
public interface KeyedObjectPool<K,V>
+extends Closeable
```
+
A "keyed" pooling interface. +
+ A keyed pool maintains a pool of instances for each key value. +
+ Example of use: +
```
 Object obj = null;
+ Object key = "Key";
+
+ try {
+     obj = pool.borrowObject(key);
+     //...use the object...
+ } catch(Exception e) {
+     // invalidate the object
+     pool.invalidateObject(key, 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(key, obj);
+     }
+ }
```
+
+ KeyedObjectPool implementations may choose to store at most + one instance per key value, or may choose to maintain a pool of instances + for each key (essentially creating a Map of + pools). +
+ See GenericKeyedObjectPool for an implementation.
+
Since:
+
2.0
+
See Also:
KeyedPooledObjectFactory, +ObjectPool, +GenericKeyedObjectPool
+

+ +

+ + +

Method Summary

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

Methods
Modifier and Type	Method and Description
`void`	`addObject(K key)` + Create an object using the `factory` or + other implementation dependent mechanism, passivate it, and then place it + in the idle object pool. +
`V`	`borrowObject(K key)` + Obtains an instance from this pool for the specified `key`. +
`void`	`clear()` + Clears the pool, removing all pooled instances (optional operation). +
`void`	`clear(K 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`	`getNumActive()` + Returns the total number of instances current borrowed from this pool but + not yet returned. +
`int`	`getNumActive(K key)` + Returns the number of instances currently borrowed from but not yet + returned to the pool corresponding to the given `key`. +
`int`	`getNumIdle()` + Returns the total number of instances currently idle in this pool. +
`int`	`getNumIdle(K key)` + Returns the number of instances corresponding to the given + `key` currently idle in this pool. +
`void`	`invalidateObject(K key, + V obj)` + Invalidates an object from the pool. +
`void`	`returnObject(K key, + V obj)` + Return an instance to the pool. +

+ +
- + + +
  Method Detail
  + + + + + +
  - +
    borrowObject
    +
```
V borrowObject(K key)
+               throws Exception,
+                      NoSuchElementException,
+                      IllegalStateException
```
    +
    Obtains an instance from this pool for the specified key. +
    + Instances returned from this method will have been either newly created + with makeObject or will be + a previously idle object and have been activated with + activateObject and then + (optionally) validated with + validateObject. +
    + By contract, clients must return the borrowed object + using returnObject, + invalidateObject, 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. +
    + The behaviour of this method when the pool has been exhausted is not + strictly specified (although it may be specified by implementations).
    +
    Parameters:
    key - the key used to obtain the object
    +
    Returns:
    an instance from this pool.
    +
    Throws:
    +
    IllegalStateException - after close has been called on this pool
    +
    Exception - when makeObject throws an exception
    +
    NoSuchElementException - when the pool is exhausted and cannot or will not return + another instance
    +
  + + + + + +
  - +
    returnObject
    +
```
void returnObject(K key,
+                V 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 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
    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(K key,
+                    V 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 using a key that is + equivalent to the one used to borrow the Object 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
    obj - a borrowed instance to be returned.
    +
    Throws:
    +
    Exception - if the instance cannot be invalidated
    +
  + + + + + +
  - +
    addObject
    +
```
void addObject(K key)
+               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).
    +
    Parameters:
    key - the key a new instance should be added to
    +
    Throws:
    +
    Exception - when KeyedPooledObjectFactory.makeObject(K) fails.
    +
    IllegalStateException - after close() has been called on this pool.
    +
    UnsupportedOperationException - when this pool cannot add new idle objects.
    +
  + + + + + +
  - +
    getNumIdle
    +
```
int getNumIdle(K key)
```
    +
    Returns the number of instances corresponding to the given + key currently idle in this pool. Returns a negative value if + this information is not available.
    +
    Parameters:
    key - the key to query
    +
    Returns:
    the number of instances corresponding to the given + key currently idle in this pool.
    +
  + + + + + +
  - +
    getNumActive
    +
```
int getNumActive(K key)
```
    +
    Returns the number of instances currently borrowed from but not yet + returned to the pool corresponding to the given key. + Returns a negative value if this information is not available.
    +
    Parameters:
    key - the key to query
    +
    Returns:
    the number of instances currently borrowed from but not yet + returned to the pool corresponding to the given key. +=
    +
  + + + +
  - +
    getNumIdle
    +
```
int getNumIdle()
```
    +
    Returns the total number of instances currently idle in this pool. + Returns a negative value if this information is not available.
    +
    Returns:
    the total number of instances currently idle in this pool. + =
    +
  + + + +
  - +
    getNumActive
    +
```
int getNumActive()
```
    +
    Returns the total number of instances current borrowed from this pool but + not yet returned. Returns a negative value if this information is not + available.
    +
    Returns:
    the total number of instances current borrowed from this pool but + not yet returned.
    +
  + + + +
  - +
    clear
    +
```
void clear()
+           throws Exception,
+                  UnsupportedOperationException
```
    +
    Clears the pool, removing all pooled instances (optional operation).
    +
    Throws:
    +
    UnsupportedOperationException - when this implementation doesn't + support the operation
    +
    Exception - if the pool cannot be cleared
    +
  + + + + + +
  - +
    clear
    +
```
void clear(K key)
+           throws Exception,
+                  UnsupportedOperationException
```
    +
    Clears the specified pool, removing all pooled instances corresponding to + the given key (optional operation).
    +
    Parameters:
    key - the key to clear
    +
    Throws:
    +
    UnsupportedOperationException - when this implementation doesn't + support the operation
    +
    Exception - if the key 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.
    +
    +
    Specified by:
    +
    close in interface AutoCloseable
    +
    Specified by:
    +
    close in interface Closeable
    +
    +
  +
+

Class BasePooledObjectFactory<T>

Constructor Summary

Method Summary

Methods inherited from class org.apache.commons.pool2.BaseObject

Methods inherited from class java.lang.Object

Constructor Detail

BasePooledObjectFactory

Method Detail

create

wrap

makeObject

destroyObject

validateObject

activateObject

passivateObject

Interface KeyedObjectPool<K,V>

Method Summary

Method Detail

borrowObject

returnObject

invalidateObject

addObject

getNumIdle

getNumActive

getNumIdle

getNumActive

clear

clear

close