Apache Commons Pool 2.12.0 · org.apache.commons.pool2.ObjectPool

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.

Method Summary

Modifier and Type	Method and Description
public void	addObject() Creates an object using the `factory` or other implementation dependent mechanism, passivate it, and then place it in the idle object pool.
public default void	addObjects(final int the number of idle objects to add. count) Calls `ObjectPool#addObject()` `count` number of times.
public T	Returns: an instance from this pool. borrowObject() Borrows an instance from this pool.
public void	clear() Clears any objects sitting idle in the pool, releasing any associated resources (optional operation).
public void	close() Redeclares java.io.Closeable.close. Closes this pool, and free any resources associated with it.
public int	Returns: the number of instances currently borrowed from this pool. getNumActive() Gets the number of instances currently borrowed from this pool.
public int	Returns: the number of instances currently idle in this pool. getNumIdle() Gets the number of instances currently idle in this pool.
public void	invalidateObject(T a `borrowed` instance to be disposed. obj) Invalidates an object from the pool.
public default void	invalidateObject(final T a `borrowed` instance to be disposed. obj, final DestroyMode destroy activation context provided to the factory destroyMode) Invalidates an object from the pool, using the provided `DestroyMode` By contract, `obj` must have been obtained using `borrowObject` or a related method as defined in an implementation or sub-interface.
public void	returnObject(T a `borrowed` instance to be returned. obj) Returns an instance to the pool.

Method Detail

addObject back to summary

addObject	back to summary
public void addObject() throws Exception Creates 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). Exceptions Exception: when `PooledObjectFactory#makeObject` fails. IllegalStateException: after `close` has been called on this pool. UnsupportedOperationException: when this pool cannot add new idle objects.

public void addObject() throws Exception

Creates 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).

Exceptions

Exception:: when PooledObjectFactory#makeObject fails.
IllegalStateException:: after close has been called on this pool.
UnsupportedOperationException:: when this pool cannot add new idle objects.

addObjects back to summary

addObjects	back to summary
public default void addObjects(final int count) throws Exception Calls `ObjectPool#addObject()` `count` number of times. Parameters count:int the number of idle objects to add. Exceptions Exception: See `ObjectPool#addObject()`. Since 2.8.0

public default void addObjects(final int count) throws Exception

Calls ObjectPool#addObject() count number of times.

Parameters

count:int: the number of idle objects to add.

Exceptions

Exception:: See ObjectPool#addObject().

Since

2.8.0

borrowObject back to summary

borrowObject	back to summary
public T borrowObject() throws Exception Borrows 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` and then validated with `PooledObjectFactory#validateObject`. By contract, clients must return the borrowed instance using `returnObject`, `invalidateObject`, or a related method as defined in an implementation or sub-interface. The behavior of this method when the pool has been exhausted is not strictly specified (although it may be specified by implementations). Returns:T an instance from this pool. Exceptions Exception: when `PooledObjectFactory#makeObject` throws an exception. IllegalStateException: after `close` has been called on this pool. NoSuchElementException: when the pool is exhausted and cannot or will not return another instance.

public T borrowObject() throws Exception

Borrows 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 and then validated with PooledObjectFactory#validateObject.

By contract, clients must return the borrowed instance using returnObject, invalidateObject, or a related method as defined in an implementation or sub-interface.

The behavior of this method when the pool has been exhausted is not strictly specified (although it may be specified by implementations).

Returns:T

an instance from this pool.

Exceptions

Exception:: when PooledObjectFactory#makeObject throws an exception.
IllegalStateException:: after close has been called on this pool.
NoSuchElementException:: when the pool is exhausted and cannot or will not return another instance.

clear back to summary

clear	back to summary
public void clear() throws Exception Clears any objects sitting idle in the pool, releasing any associated resources (optional operation). Idle objects cleared must be `PooledObjectFactory#destroyObject(PooledObject)`. Exceptions Exception: if the pool cannot be cleared UnsupportedOperationException: if this implementation does not support the operation

public void clear() throws Exception

Clears any objects sitting idle in the pool, releasing any associated resources (optional operation). Idle objects cleared must be PooledObjectFactory#destroyObject(PooledObject).

Exceptions

Exception:: if the pool cannot be cleared
UnsupportedOperationException:: if this implementation does not support the operation

close back to summary

close	back to summary
public void close() Redeclares java.io.Closeable.close. Closes 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. Annotations @Override

public void close()

Redeclares java.io.Closeable.close.

Closes 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.

Annotations

@Override

getNumActive	back to summary
public int getNumActive() Gets the number of instances currently borrowed from this pool. Returns a negative value if this information is not available. Returns:int the number of instances currently borrowed from this pool.

getNumActive

back to summary

public int getNumActive()

Gets the number of instances currently borrowed from this pool. Returns a negative value if this information is not available.

Returns:int: the number of instances currently borrowed from this pool.

getNumIdle back to summary

getNumIdle	back to summary
public int getNumIdle() Gets 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:int the number of instances currently idle in this pool.

public int getNumIdle()

Gets 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:int: the number of instances currently idle in this pool.

invalidateObject back to summary

invalidateObject	back to summary
public 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:T a `borrowed` instance to be disposed. Exceptions Exception: if the instance cannot be invalidated

public 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:T: a borrowed instance to be disposed.

Exceptions

Exception:: if the instance cannot be invalidated

invalidateObject back to summary

invalidateObject	back to summary
public default void invalidateObject(final T obj, final DestroyMode destroyMode) throws Exception Invalidates an object from the pool, using the provided `DestroyMode` 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:T a `borrowed` instance to be disposed. destroyMode:DestroyMode destroy activation context provided to the factory Exceptions Exception: if the instance cannot be invalidated Since 2.9.0

public default void invalidateObject(final T obj, final DestroyMode destroyMode) throws Exception

Invalidates an object from the pool, using the provided DestroyMode

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:T: a borrowed instance to be disposed.
destroyMode:DestroyMode: destroy activation context provided to the factory

Exceptions

Exception:: if the instance cannot be invalidated

Since

2.9.0

returnObject back to summary

returnObject	back to summary
public void returnObject(T obj) throws Exception Returns 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:T a `borrowed` instance to be returned. Exceptions Exception: if an instance cannot be returned to the pool 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.

public void returnObject(T obj) throws Exception

Returns 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:T: a borrowed instance to be returned.

Exceptions

Exception:: if an instance cannot be returned to the pool
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.

public Interface ObjectPool<T>

Method Summary

Method Detail