CommonsPoolTargetSource (Spring Framework 3.2.1.RELEASE API)
Date: 2013-01-24

org.springframework.aop.target

## Class CommonsPoolTargetSource

- java.lang.Object
- - org.springframework.aop.target.AbstractBeanFactoryBasedTargetSource
  - - org.springframework.aop.target.AbstractPrototypeBasedTargetSource
    - - org.springframework.aop.target.AbstractPoolingTargetSource
      - - org.springframework.aop.target.CommonsPoolTargetSource

- All Implemented Interfaces:
    Serializable, org.apache.commons.pool.PoolableObjectFactory, PoolingConfig, TargetClassAware, TargetSource, Aware, BeanFactoryAware, DisposableBean

      public class CommonsPoolTargetSource
      extends AbstractPoolingTargetSource
      implements org.apache.commons.pool.PoolableObjectFactory

  TargetSource implementation that holds objects in a configurable Jakarta Commons Pool.

  By default, an instance of `GenericObjectPool` is created. Subclasses may change the type of `ObjectPool` used by overriding the `createObjectPool()` method.

  Provides many configuration properties mirroring those of the Commons Pool `GenericObjectPool` class; these properties are passed to the `GenericObjectPool` during construction. If creating a subclass of this class to change the `ObjectPool` implementation type, pass in the values of configuration properties that are relevant to your chosen implementation.

  The `testOnBorrow`, `testOnReturn` and `testWhileIdle` properties are explictly not mirrored because the implementation of `PoolableObjectFactory` used by this class does not implement meaningful validation. All exposed Commons Pool properties use the corresponding Commons Pool defaults: for example,

  Author:
    Rod Johnson, Rob Harrop, Juergen Hoeller
  See Also:
    `GenericObjectPool`, `createObjectPool()`, `AbstractPoolingTargetSource.setMaxSize(int)`, `setMaxIdle(int)`, `setMinIdle(int)`, `setMaxWait(long)`, `setTimeBetweenEvictionRunsMillis(long)`, `setMinEvictableIdleTimeMillis(long)`, Serialized Form

- - ### Field Summary

    - ### Fields inherited from class org.springframework.aop.target.AbstractBeanFactoryBasedTargetSource

      `logger`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `CommonsPoolTargetSource()` Create a CommonsPoolTargetSource with default settings.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `activateObject(Object obj)`
    `protected org.apache.commons.pool.ObjectPool` | `createObjectPool()` Subclasses can override this if they want to return a specific Commons pool.
    `protected void` | `createPool()` Creates and holds an ObjectPool instance.
    `void` | `destroy()` Closes the underlying `ObjectPool` when destroying this object.
    `void` | `destroyObject(Object obj)`
    `int` | `getActiveCount()` Return the number of active objects in the pool.
    `int` | `getIdleCount()` Return the number of idle objects in the pool.
    `int` | `getMaxIdle()` Return the maximum number of idle objects in the pool.
    `long` | `getMaxWait()` Return the maximum waiting time for fetching an object from the pool.
    `long` | `getMinEvictableIdleTimeMillis()` Return the minimum time that an idle object can sit in the pool.
    `int` | `getMinIdle()` Return the minimum number of idle objects in the pool.
    `Object` | `getTarget()` Borrow an object from the `ObjectPool`.
    `long` | `getTimeBetweenEvictionRunsMillis()` Return the time between eviction runs that check idle objects.
    `byte` | `getWhenExhaustedAction()` Return the action to take when the pool is exhausted.
    `Object` | `makeObject()`
    `void` | `passivateObject(Object obj)`
    `void` | `releaseTarget(Object target)` Returns the specified object to the underlying `ObjectPool`.
    `void` | `setMaxIdle(int maxIdle)` Set the maximum number of idle objects in the pool.
    `void` | `setMaxWait(long maxWait)` Set the maximum waiting time for fetching an object from the pool.
    `void` | `setMinEvictableIdleTimeMillis(long minEvictableIdleTimeMillis)` Set the minimum time that an idle object can sit in the pool before it becomes subject to eviction.
    `void` | `setMinIdle(int minIdle)` Set the minimum number of idle objects in the pool.
    `void` | `setTimeBetweenEvictionRunsMillis(long timeBetweenEvictionRunsMillis)` Set the time between eviction runs that check idle objects whether they have been idle for too long or have become invalid.
    `void` | `setWhenExhaustedAction(byte whenExhaustedAction)` Set the action to take when the pool is exhausted.
    `void` | `setWhenExhaustedActionName(String whenExhaustedActionName)` Set the action to take when the pool is exhausted.
    `boolean` | `validateObject(Object obj)`

    - ### Methods inherited from class org.springframework.aop.target.AbstractPoolingTargetSource

      `getMaxSize, getPoolingConfigMixin, setBeanFactory, setMaxSize`

    - ### Methods inherited from class org.springframework.aop.target.AbstractPrototypeBasedTargetSource

      `destroyPrototypeInstance, newPrototypeInstance, writeReplace`

    - ### Methods inherited from class org.springframework.aop.target.AbstractBeanFactoryBasedTargetSource

      `copyFrom, equals, getBeanFactory, getTargetBeanName, getTargetClass, hashCode, isStatic, setTargetBeanName, setTargetClass, toString`

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

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### CommonsPoolTargetSource

          public CommonsPoolTargetSource()

      Create a CommonsPoolTargetSource with default settings. Default maximum size of the pool is 8.
      See Also:
        `AbstractPoolingTargetSource.setMaxSize(int)`, `GenericObjectPool.setMaxActive(int)`

  - ### Method Detail

    - #### setMaxIdle

          public void setMaxIdle(int maxIdle)

      Set the maximum number of idle objects in the pool. Default is 8.
      See Also:
        `GenericObjectPool.setMaxIdle(int)`

    - #### getMaxIdle

          public int getMaxIdle()

      Return the maximum number of idle objects in the pool.

    - #### setMinIdle

          public void setMinIdle(int minIdle)

      Set the minimum number of idle objects in the pool. Default is 0.
      See Also:
        `GenericObjectPool.setMinIdle(int)`

    - #### getMinIdle

          public int getMinIdle()

      Return the minimum number of idle objects in the pool.

    - #### setMaxWait

          public void setMaxWait(long maxWait)

      Set the maximum waiting time for fetching an object from the pool. Default is -1, waiting forever.
      See Also:
        `GenericObjectPool.setMaxWait(long)`

    - #### getMaxWait

          public long getMaxWait()

      Return the maximum waiting time for fetching an object from the pool.

    - #### setTimeBetweenEvictionRunsMillis

          public void setTimeBetweenEvictionRunsMillis(long timeBetweenEvictionRunsMillis)

      Set the time between eviction runs that check idle objects whether they have been idle for too long or have become invalid. Default is -1, not performing any eviction.
      See Also:
        `GenericObjectPool.setTimeBetweenEvictionRunsMillis(long)`

    - #### getTimeBetweenEvictionRunsMillis

          public long getTimeBetweenEvictionRunsMillis()

      Return the time between eviction runs that check idle objects.

    - #### setMinEvictableIdleTimeMillis

          public void setMinEvictableIdleTimeMillis(long minEvictableIdleTimeMillis)

      Set the minimum time that an idle object can sit in the pool before it becomes subject to eviction. Default is 1800000 (30 minutes).

      Note that eviction runs need to be performed to take this setting into effect.

      See Also:
        `setTimeBetweenEvictionRunsMillis(long)`, `GenericObjectPool.setMinEvictableIdleTimeMillis(long)`

    - #### getMinEvictableIdleTimeMillis

          public long getMinEvictableIdleTimeMillis()

      Return the minimum time that an idle object can sit in the pool.

    - #### setWhenExhaustedActionName

          public void setWhenExhaustedActionName(String whenExhaustedActionName)

      Set the action to take when the pool is exhausted. Uses the constant names defined in Commons Pool's GenericObjectPool class: "WHEN_EXHAUSTED_BLOCK", "WHEN_EXHAUSTED_FAIL", "WHEN_EXHAUSTED_GROW".
      See Also:
        `setWhenExhaustedAction(byte)`

    - #### setWhenExhaustedAction

          public void setWhenExhaustedAction(byte whenExhaustedAction)

      Set the action to take when the pool is exhausted. Uses the constant values defined in Commons Pool's GenericObjectPool class.
      See Also:
        `GenericObjectPool.setWhenExhaustedAction(byte)`, `GenericObjectPool.WHEN_EXHAUSTED_BLOCK`, `GenericObjectPool.WHEN_EXHAUSTED_FAIL`, `GenericObjectPool.WHEN_EXHAUSTED_GROW`

    - #### getWhenExhaustedAction

          public byte getWhenExhaustedAction()

      Return the action to take when the pool is exhausted.

    - #### createPool

          protected final void createPool()

      Creates and holds an ObjectPool instance.
      Specified by:
        `createPool` in class `AbstractPoolingTargetSource`
      See Also:
        `createObjectPool()`

    - #### createObjectPool

          protected org.apache.commons.pool.ObjectPool createObjectPool()

      Subclasses can override this if they want to return a specific Commons pool. They should apply any configuration properties to the pool here.

      Default is a GenericObjectPool instance with the given pool size.

      Returns:
        an empty Commons `ObjectPool`.
      See Also:
        `GenericObjectPool`, `AbstractPoolingTargetSource.setMaxSize(int)`

    - #### getTarget

          public Object getTarget()
                           throws Exception

      Borrow an object from the `ObjectPool`.
      Specified by:
        `getTarget` in interface `TargetSource`
      Specified by:
        `getTarget` in class `AbstractPoolingTargetSource`
      Returns:
        an object from the pool
      Throws:
        `Exception` - we may need to deal with checked exceptions from pool APIs, so we're forgiving with our exception signature

    - #### releaseTarget

          public void releaseTarget(Object target)
                             throws Exception

      Returns the specified object to the underlying `ObjectPool`.
      Specified by:
        `releaseTarget` in interface `TargetSource`
      Specified by:
        `releaseTarget` in class `AbstractPoolingTargetSource`
      Parameters:
        `target` - object that must have been acquired from the pool via a call to `getTarget()`
      Throws:
        `Exception` - to allow pooling APIs to throw exception
      See Also:
        `AbstractPoolingTargetSource.getTarget()`

    - #### getActiveCount

          public int getActiveCount()
                             throws UnsupportedOperationException

      Description copied from interface: `PoolingConfig`
      Return the number of active objects in the pool.
      Specified by:
        `getActiveCount` in interface `PoolingConfig`
      Throws:
        `UnsupportedOperationException` - if not supported by the pool

    - #### getIdleCount

          public int getIdleCount()
                           throws UnsupportedOperationException

      Description copied from interface: `PoolingConfig`
      Return the number of idle objects in the pool.
      Specified by:
        `getIdleCount` in interface `PoolingConfig`
      Throws:
        `UnsupportedOperationException` - if not supported by the pool

    - #### destroy

          public void destroy()
                       throws Exception

      Closes the underlying `ObjectPool` when destroying this object.
      Specified by:
        `destroy` in interface `DisposableBean`
      Throws:
        `Exception` - in case of shutdown errors. Exceptions will get logged but not rethrown to allow other beans to release their resources too.

    - #### makeObject

          public Object makeObject()
                            throws BeansException

      Specified by:
        `makeObject` in interface `org.apache.commons.pool.PoolableObjectFactory`
      Throws:
        `BeansException`

    - #### destroyObject

          public void destroyObject(Object obj)
                             throws Exception

      Specified by:
        `destroyObject` in interface `org.apache.commons.pool.PoolableObjectFactory`
      Throws:
        `Exception`

    - #### validateObject

          public boolean validateObject(Object obj)

      Specified by:
        `validateObject` in interface `org.apache.commons.pool.PoolableObjectFactory`

    - #### activateObject

          public void activateObject(Object obj)

      Specified by:
        `activateObject` in interface `org.apache.commons.pool.PoolableObjectFactory`

    - #### passivateObject

          public void passivateObject(Object obj)

      Specified by:
        `passivateObject` in interface `org.apache.commons.pool.PoolableObjectFactory`