org.apache.commons.pool2.proxy

## Class ProxiedObjectPool<T>

- java.lang.Object
- - org.apache.commons.pool2.proxy.ProxiedObjectPool<T>

- Type Parameters:
    `T` - type of the pooled object
  All Implemented Interfaces:
    ObjectPool<T>

      public class ProxiedObjectPool<T>
      extends Object
      implements ObjectPool<T>

  Create a new object pool where the pooled objects are wrapped in proxies allowing better control of pooled objects and in particular the prevention of the continued use of an object by a client after that client returns the object to the pool.
  Since:
    2.0

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `ProxiedObjectPool(ObjectPool<T> pool, org.apache.commons.pool2.proxy.ProxySource<T> proxySource)` Create a new proxied object pool.

  - ### 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 proxy)` Invalidates an object from the pool.
    `void` | `returnObject(T proxy)` Return an instance to the pool.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### ProxiedObjectPool

          public ProxiedObjectPool(ObjectPool<T> pool,
                           org.apache.commons.pool2.proxy.ProxySource<T> proxySource)

      Create a new proxied object pool.
      Parameters:
        `pool` - The object pool to wrap
        `proxySource` - The source of the proxy objects

  - ### Method Detail

    - #### borrowObject

          public T borrowObject()
                         throws Exception,
                                NoSuchElementException,
                                IllegalStateException

      Description copied from interface: `ObjectPool`
      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 `ObjectPool.returnObject(T)`, `ObjectPool.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).

      Specified by:
        `borrowObject` in interface `ObjectPool<T>`
      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

          public void returnObject(T proxy)
                            throws Exception

      Description copied from interface: `ObjectPool`
      Return an instance to the pool. By contract, `obj` must have been obtained using `ObjectPool.borrowObject()` or a related method as defined in an implementation or sub-interface.
      Specified by:
        `returnObject` in interface `ObjectPool<T>`
      Parameters:
        `proxy` - a `borrowed` instance to be returned.
      Throws:
        `Exception`

    - #### invalidateObject

          public void invalidateObject(T proxy)
                                throws Exception

      Description copied from interface: `ObjectPool`
      Invalidates an object from the pool.

      By contract, `obj` must have been obtained using `ObjectPool.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.

      Specified by:
        `invalidateObject` in interface `ObjectPool<T>`
      Parameters:
        `proxy` - a `borrowed` instance to be disposed.
      Throws:
        `Exception`

    - #### addObject

          public void addObject()
                         throws Exception,
                                IllegalStateException,
                                UnsupportedOperationException

      Description copied from interface: `ObjectPool`
      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).
      Specified by:
        `addObject` in interface `ObjectPool<T>`
      Throws:
        `Exception` - when `PooledObjectFactory.makeObject()` fails.
        `IllegalStateException` - after `ObjectPool.close()` has been called on this pool.
        `UnsupportedOperationException` - when this pool cannot add new idle objects.

    - #### getNumIdle

          public int getNumIdle()

      Description copied from interface: `ObjectPool`
      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.
      Specified by:
        `getNumIdle` in interface `ObjectPool<T>`
      Returns:
        the number of instances currently idle in this pool.

    - #### getNumActive

          public int getNumActive()

      Description copied from interface: `ObjectPool`
      Return the number of instances currently borrowed from this pool. Returns a negative value if this information is not available.
      Specified by:
        `getNumActive` in interface `ObjectPool<T>`
      Returns:
        the number of instances currently borrowed from this pool.

    - #### clear

          public void clear()
                     throws Exception,
                            UnsupportedOperationException

      Description copied from interface: `ObjectPool`
      Clears any objects sitting idle in the pool, releasing any associated resources (optional operation). Idle objects cleared must be `PooledObjectFactory.destroyObject(PooledObject)`.
      Specified by:
        `clear` in interface `ObjectPool<T>`
      Throws:
        `UnsupportedOperationException` - if this implementation does not support the operation
        `Exception`

    - #### close

          public void close()

      Description copied from interface: `ObjectPool`
      Close this pool, and free any resources associated with it.

      Calling `ObjectPool.addObject()` or `ObjectPool.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 `ObjectPool<T>`

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