org.apache.commons.pool2

## Interface ObjectPool<T>

- 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: 1533126 $
  See Also:
    `PooledObjectFactory`, `KeyedObjectPool`, `BaseObjectPool`

- - ### Method Summary

    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:
        `Exception`

    - #### 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`

    - #### 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`

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

Copyright © 2001–2013 The Apache Software Foundation. All rights reserved.