Class GenericObjectPool<T>

Method Details

• getMaxActive

  public int getMaxActive()

  Returns the maximum number of objects that can be allocated by the pool (checked out to clients, or idle awaiting checkout) at a given time. When non-positive, there is no limit to the number of objects that can be managed by the pool at one time.

  Returns:

  the cap on the total number of object instances managed by the pool.

  See Also:

  • setMaxActive(int)

• setMaxActive

  public void setMaxActive(int maxActive)

  Sets the cap on the number of objects that can be allocated by the pool (checked out to clients, or idle awaiting checkout) at a given time. Use a negative value for no limit.

  Parameters:

  maxActive - The cap on the total number of object instances managed by the pool. Negative values mean that there is no limit to the number of objects allocated by the pool.

  See Also:

  • getMaxActive()

• getWhenExhaustedAction

  public byte getWhenExhaustedAction()

  Returns the action to take when the borrowObject() method is invoked when the pool is exhausted (the maximum number of "active" objects has been reached).

  Returns:

  one of WHEN_EXHAUSTED_BLOCK, WHEN_EXHAUSTED_FAIL or WHEN_EXHAUSTED_GROW

  See Also:

  • setWhenExhaustedAction(byte)

• setWhenExhaustedAction

  public void setWhenExhaustedAction(byte whenExhaustedAction)

  Sets the action to take when the borrowObject() method is invoked when the pool is exhausted (the maximum number of "active" objects has been reached).

  Parameters:

  whenExhaustedAction - the action code, which must be one of WHEN_EXHAUSTED_BLOCK, WHEN_EXHAUSTED_FAIL, or WHEN_EXHAUSTED_GROW

  See Also:

  • getWhenExhaustedAction()

• getMaxWait

  public long getMaxWait()

  Returns the maximum amount of time (in milliseconds) the borrowObject() method should block before throwing an exception when the pool is exhausted and the "when exhausted" action is WHEN_EXHAUSTED_BLOCK. When less than or equal to 0, the borrowObject() method may block indefinitely.

  Returns:

  maximum number of milliseconds to block when borrowing an object.

  See Also:

  • setMaxWait(long)
  • setWhenExhaustedAction(byte)
  • WHEN_EXHAUSTED_BLOCK

• setMaxWait

  public void setMaxWait(long maxWait)

  Sets the maximum amount of time (in milliseconds) the borrowObject() method should block before throwing an exception when the pool is exhausted and the "when exhausted" action is WHEN_EXHAUSTED_BLOCK. When less than or equal to 0, the borrowObject() method may block indefinitely.

  Parameters:

  maxWait - maximum number of milliseconds to block when borrowing an object.

  See Also:

  • getMaxWait()
  • setWhenExhaustedAction(byte)
  • WHEN_EXHAUSTED_BLOCK

• getMaxIdle

  public int getMaxIdle()

  Returns the cap on the number of "idle" instances in the pool.

  Returns:

  the cap on the number of "idle" instances in the pool.

  See Also:

  • setMaxIdle(int)

• setMaxIdle

  public void setMaxIdle(int maxIdle)

  Sets the cap on the number of "idle" instances in the pool. If maxIdle is set too low on heavily loaded systems it is possible you will see objects being destroyed and almost immediately new objects being created. This is a result of the active threads momentarily returning objects faster than they are requesting them them, causing the number of idle objects to rise above maxIdle. The best value for maxIdle for heavily loaded system will vary but the default is a good starting point.

  Parameters:

  maxIdle - The cap on the number of "idle" instances in the pool. Use a negative value to indicate an unlimited number of idle instances.

  See Also:

  • getMaxIdle()

• setMinIdle

  public void setMinIdle(int minIdle)

  Sets the minimum number of objects allowed in the pool before the evictor thread (if active) spawns new objects. Note that no objects are created when numActive + numIdle >= maxActive. This setting has no effect if the idle object evictor is disabled (i.e. if timeBetweenEvictionRunsMillis <= 0).

  Parameters:

  minIdle - The minimum number of objects.

  See Also:

  • getMinIdle()
  • getTimeBetweenEvictionRunsMillis()

• getMinIdle

  public int getMinIdle()

  Returns the minimum number of objects allowed in the pool before the evictor thread (if active) spawns new objects. (Note no objects are created when: numActive + numIdle >= maxActive)

  Returns:

  The minimum number of objects.

  See Also:

  • setMinIdle(int)

• getTestOnBorrow

  public boolean getTestOnBorrow()

  When true, objects will be validated before being returned by the borrowObject() method. If the object fails to validate, it will be dropped from the pool, and we will attempt to borrow another.

  Returns:

  true if objects are validated before being borrowed.

  See Also:

  • setTestOnBorrow(boolean)

• setTestOnBorrow

  public void setTestOnBorrow(boolean testOnBorrow)

  When true, objects will be validated before being returned by the borrowObject() method. If the object fails to validate, it will be dropped from the pool, and we will attempt to borrow another.

  Parameters:

  testOnBorrow - true if objects should be validated before being borrowed.

  See Also:

  • getTestOnBorrow()

• getTestOnReturn

  public boolean getTestOnReturn()

  When true, objects will be validated before being returned to the pool within the returnObject(T).

  Returns:

  true when objects will be validated after returned to returnObject(T).

  See Also:

  • setTestOnReturn(boolean)

• setTestOnReturn

  public void setTestOnReturn(boolean testOnReturn)

  When true, objects will be validated before being returned to the pool within the returnObject(T).

  Parameters:

  testOnReturn - true so objects will be validated after returned to returnObject(T).

  See Also:

  • getTestOnReturn()

• getTimeBetweenEvictionRunsMillis

  public long getTimeBetweenEvictionRunsMillis()

  Returns the number of milliseconds to sleep between runs of the idle object evictor thread. When non-positive, no idle object evictor thread will be run.

  Returns:

  number of milliseconds to sleep between evictor runs.

  See Also:

  • setTimeBetweenEvictionRunsMillis(long)

• setTimeBetweenEvictionRunsMillis

  public void setTimeBetweenEvictionRunsMillis(long timeBetweenEvictionRunsMillis)

  Sets the number of milliseconds to sleep between runs of the idle object evictor thread. When non-positive, no idle object evictor thread will be run.

  Parameters:

  timeBetweenEvictionRunsMillis - number of milliseconds to sleep between evictor runs.

  See Also:

  • getTimeBetweenEvictionRunsMillis()

• getNumTestsPerEvictionRun

  public int getNumTestsPerEvictionRun()

  Returns the max number of objects to examine during each run of the idle object evictor thread (if any).

  Returns:

  max number of objects to examine during each evictor run.

  See Also:

  • setNumTestsPerEvictionRun(int)
  • setTimeBetweenEvictionRunsMillis(long)

• setNumTestsPerEvictionRun

  public void setNumTestsPerEvictionRun(int numTestsPerEvictionRun)

  Sets the max number of objects to examine during each run of the idle object evictor thread (if any).

  When a negative value is supplied, ceil(getNumIdle())/abs(getNumTestsPerEvictionRun()) tests will be run. That is, when the value is -n, roughly one nth of the idle objects will be tested per run. When the value is positive, the number of tests actually performed in each run will be the minimum of this value and the number of instances idle in the pool.

  Parameters:

  numTestsPerEvictionRun - max number of objects to examine during each evictor run.

  See Also:

  • getNumTestsPerEvictionRun()
  • setTimeBetweenEvictionRunsMillis(long)

• getMinEvictableIdleTimeMillis

  public long getMinEvictableIdleTimeMillis()

  Returns the minimum amount of time an object may sit idle in the pool before it is eligible for eviction by the idle object evictor (if any).

  Returns:

  minimum amount of time an object may sit idle in the pool before it is eligible for eviction.

  See Also:

  • setMinEvictableIdleTimeMillis(long)
  • setTimeBetweenEvictionRunsMillis(long)

• setMinEvictableIdleTimeMillis

  public void setMinEvictableIdleTimeMillis(long minEvictableIdleTimeMillis)

  Sets the minimum amount of time an object may sit idle in the pool before it is eligible for eviction by the idle object evictor (if any). When non-positive, no objects will be evicted from the pool due to idle time alone.

  Parameters:

  minEvictableIdleTimeMillis - minimum amount of time an object may sit idle in the pool before it is eligible for eviction.

  See Also:

  • getMinEvictableIdleTimeMillis()
  • setTimeBetweenEvictionRunsMillis(long)

• getSoftMinEvictableIdleTimeMillis

  public long getSoftMinEvictableIdleTimeMillis()

  Returns the minimum amount of time an object may sit idle in the pool before it is eligible for eviction by the idle object evictor (if any), with the extra condition that at least "minIdle" amount of object remain in the pool.

  Returns:

  minimum amount of time an object may sit idle in the pool before it is eligible for eviction.

  Since:

  Pool 1.3

  See Also:

  • setSoftMinEvictableIdleTimeMillis(long)

• setSoftMinEvictableIdleTimeMillis

  public void setSoftMinEvictableIdleTimeMillis(long softMinEvictableIdleTimeMillis)

  Sets the minimum amount of time an object may sit idle in the pool before it is eligible for eviction by the idle object evictor (if any), with the extra condition that at least "minIdle" object instances remain in the pool. When non-positive, no objects will be evicted from the pool due to idle time alone.

  Parameters:

  softMinEvictableIdleTimeMillis - minimum amount of time an object may sit idle in the pool before it is eligible for eviction.

  Since:

  Pool 1.3

  See Also:

  • getSoftMinEvictableIdleTimeMillis()

• getTestWhileIdle

  public boolean getTestWhileIdle()

  When true, objects will be validated by the idle object evictor (if any). If an object fails to validate, it will be dropped from the pool.

  Returns:

  true when objects will be validated by the evictor.

  See Also:

  • setTestWhileIdle(boolean)
  • setTimeBetweenEvictionRunsMillis(long)

• setTestWhileIdle

  public void setTestWhileIdle(boolean testWhileIdle)

  When true, objects will be validated by the idle object evictor (if any). If an object fails to validate, it will be dropped from the pool.

  Parameters:

  testWhileIdle - true so objects will be validated by the evictor.

  See Also:

  • getTestWhileIdle()
  • setTimeBetweenEvictionRunsMillis(long)

• getLifo

  public boolean getLifo()

  Whether or not the idle object pool acts as a LIFO queue. True means that borrowObject returns the most recently used ("last in") idle object in the pool (if there are idle instances available). False means that the pool behaves as a FIFO queue - objects are taken from the idle object pool in the order that they are returned to the pool.

  Returns:

  true if the pool is configured to act as a LIFO queue

  Since:

  1.4

• setLifo

  public void setLifo(boolean lifo)

  Sets the LIFO property of the pool. True means that borrowObject returns the most recently used ("last in") idle object in the pool (if there are idle instances available). False means that the pool behaves as a FIFO queue - objects are taken from the idle object pool in the order that they are returned to the pool.

  Parameters:

  lifo - the new value for the LIFO property

  Since:

  1.4

• setConfig

  public void setConfig(GenericObjectPool.Config conf)

  Sets my configuration.

  Parameters:

  conf - configuration to use.

  See Also:

  • GenericObjectPool.Config

• borrowObject

  public T borrowObject() throws Exception

  Borrows an object from the pool.

  If there is an idle instance available in the pool, then either the most-recently returned (if lifo == true) or "oldest" (lifo == false) instance sitting idle in the pool will be activated and returned. If activation fails, or testOnBorrow is set to true and validation fails, the instance is destroyed and the next available instance is examined. This continues until either a valid instance is returned or there are no more idle instances available.

  If there are no idle instances available in the pool, behavior depends on the maxActive and (if applicable) whenExhaustedAction and maxWait properties. If the number of instances checked out from the pool is less than maxActive, a new instance is created, activated and (if applicable) validated and returned to the caller.

  If the pool is exhausted (no available idle instances and no capacity to create new ones), this method will either block (WHEN_EXHAUSTED_BLOCK), throw a NoSuchElementException (WHEN_EXHAUSTED_FAIL), or grow (WHEN_EXHAUSTED_GROW - ignoring maxActive). The length of time that this method will block when whenExhaustedAction == WHEN_EXHAUSTED_BLOCK is determined by the maxWait property.

  When the pool is exhausted, multiple calling threads may be simultaneously blocked waiting for instances to become available. As of pool 1.5, a "fairness" algorithm has been implemented to ensure that threads receive available instances in request arrival order.

  Specified by:

  borrowObject in interface ObjectPool<T>

  Specified by:

  borrowObject in class BaseObjectPool<T>

  Returns:

  object instance

  Throws:

  NoSuchElementException - if an instance cannot be returned

  Exception - if an instance cannot be obtained from the pool

• invalidateObject

  public void invalidateObject(T obj) throws Exception

  Invalidates an object from the pool.

  By contract, obj must have been obtained using borrowObject.

  This method should be used when an object that has been borrowed is determined (due to an exception or other problem) to be invalid.

  Activation of this method decrements the active count and attempts to destroy the instance.

  Specified by:

  invalidateObject in interface ObjectPool<T>

  Specified by:

  invalidateObject in class BaseObjectPool<T>

  Parameters:

  obj - a borrowed instance to be disposed.

  Throws:

  Exception - if the configured PoolableObjectFactory throws an exception destroying obj

• clear

  public void clear()

  Clears any objects sitting idle in the pool by removing them from the idle instance pool and then invoking the configured PoolableObjectFactory.destroyObject(Object) method on each idle instance.

  Implementation notes:

  • This method does not destroy or effect in any way instances that are checked out of the pool when it is invoked.
  • Invoking this method does not prevent objects being returned to the idle instance pool, even during its execution. It locks the pool only during instance removal. Additional instances may be returned while removed items are being destroyed.
  • Exceptions encountered destroying idle instances are swallowed.

  Specified by:

  clear in interface ObjectPool<T>

  Overrides:

  clear in class BaseObjectPool<T>

• getNumActive

  public int getNumActive()

  Return the number of instances currently borrowed from this pool.

  Specified by:

  getNumActive in interface ObjectPool<T>

  Overrides:

  getNumActive in class BaseObjectPool<T>

  Returns:

  the number of instances currently borrowed from this pool

• getNumIdle

  public int getNumIdle()

  Return the number of instances currently idle in this pool.

  Specified by:

  getNumIdle in interface ObjectPool<T>

  Overrides:

  getNumIdle in class BaseObjectPool<T>

  Returns:

  the number of instances currently idle in this pool

• returnObject

  public void returnObject(T obj) throws Exception

  Returns an object instance to the pool.

  If maxIdle is set to a positive value and the number of idle instances has reached this value, the returning instance is destroyed.

  If testOnReturn == true, the returning instance is validated before being returned to the idle instance pool. In this case, if validation fails, the instance is destroyed.

  Note: There is no guard to prevent an object being returned to the pool multiple times. Clients are expected to discard references to returned objects and ensure that an object is not returned to the pool multiple times in sequence (i.e., without being borrowed again between returns). Violating this contract will result in the same object appearing multiple times in the pool and pool counters (numActive, numIdle) returning incorrect values.

  Specified by:

  returnObject in interface ObjectPool<T>

  Specified by:

  returnObject in class BaseObjectPool<T>

  Parameters:

  obj - instance to return to the pool

  Throws:

  Exception

• close

  public void close() throws Exception

  Closes the pool. Once the pool is closed, borrowObject() will fail with IllegalStateException, but returnObject(Object) and invalidateObject(Object) will continue to work, with returned objects destroyed on return.

  Destroys idle instances in the pool by invoking clear().

  Specified by:

  close in interface ObjectPool<T>

  Overrides:

  close in class BaseObjectPool<T>

  Throws:

  Exception

• evict

  public void evict() throws Exception

  Perform numTests idle object eviction tests, evicting examined objects that meet the criteria for eviction. If testWhileIdle is true, examined objects are validated when visited (and removed if invalid); otherwise only objects that have been idle for more than minEvicableIdletimeMillis are removed.

  Successive activations of this method examine objects in in sequence, cycling through objects in oldest-to-youngest order.

  Throws:

  Exception - if the pool is closed or eviction fails.

• addObject

  public void addObject() throws Exception

  Create an object, and place it into the pool. addObject() is useful for "pre-loading" a pool with idle objects.

  Specified by:

  addObject in interface ObjectPool<T>

  Overrides:

  addObject in class BaseObjectPool<T>

  Throws:

  Exception - when PoolableObjectFactory.makeObject() fails.

  IllegalStateException - after ObjectPool.close() has been called on this pool.

  UnsupportedOperationException - when this pool cannot add new idle objects.