Commons Pool
------------

The Commons Pool project is built around a single idea - the creation of an ``ObjectPool``. This page captures our "best practices" discovered over the course of building the GeoTools project.

References:

* http://commons.apache.org/pool/

ObjectPool as a Cache
^^^^^^^^^^^^^^^^^^^^^

You can configure an ``SoftReferenceObjectPool`` to use weak references, the result functions the same as a cache.

ObjectPool for Interning
^^^^^^^^^^^^^^^^^^^^^^^^

You can configure an ``ObjectPool`` to use weak references in order to "Intern" objects and prevent duplicates from being
used in your application.

ObjectPool as a Pool
^^^^^^^^^^^^^^^^^^^^

First comes the set up - so the object pool can create the objects as needed.::
  
  public interface KeyedPoolableObjectFactory {
    Object makeObject(Object key);
    void activateObject(Object key, Object obj);
    void passivateObject(Object key, Object obj);
    boolean validateObject(Object key, Object obj);
    void destroyObject(Object key, Object obj);
  }

ObjectPool Configuration
''''''''''''''''''''''''

And then comes the configuration (of ``GenericKeyedObjectPool`` ):


* Number of Objects
  
  ``maxActive``
    capacity of created objects
  
  ``maxIdle``
    maximum number of lurkers

* What to do when at capacity:
  
  ``whenExhausedAction``
     fail, grow or block when capacity reached
  
* When to check objects in pool
  
  ``testOnBorrow``
    Check with ``validateObject`` when borrowed
  
  ``testOnreturn``
    Check with ``validateObject`` when returned
  
  ``testWhenIdle``
    Check with ``validateObject`` from the eviction thread

* Eviction Thread
  
  ``timeBetweenEvictionRunsMillis``
    Time to sleep
  
  ``minEvictableIdleTimeMills``
    time to wait before an object could be cleaned up

The way it works is this, for a ``maxActive`` of 20 at most 20 objects will be created. If they are all returned the pool will throw the instances away until it has ``maxIdle`` (this is kind of its comfort zone). After this point each object will have to time out (based on ``minEvictableIdleTimeMills``) before it is reclaimed.::
      
      maxActive
   /--This is the absolute capacity of our ``ObjectCache``
   |
   |  Objects are immediately evicted when they are not in use
   |
   \-> ``maxIdle``
   /-- This is the "comfort zone" that your ``ObjectCache`` will try for under heavy use
   |
   |  Objects are evicted when they have not been used, every ``minEvictableIdleTimeMills`` 
   |
   \-> Empty

Eviction
''''''''

Here is how eviction works:

1. it will grab ``numTestsPerEvictionRun`` objects from the pool
2. for any object that has exceeded ``minEvictableIdleTimeMillis`` it will call
   ``validateObject``
3. it will throw away any object that fails the ``validateObject`` test
4. If we have less than ``minIdle`` left in the pool new objects will be spawned

You can perform eviction in a thread controlled by setting ``testWhenIdle`` and providing a value for ``timeBetweenEvictionRunsMillis``.

GenericObjectPool Configuration
'''''''''''''''''''''''''''''''

``GenericObjectPool`` introduces the concept of a "soft min" operating as a preferred number object objects to hold in reserved (even when we are completely idle).

This concept is a little freaky in that it looks like the ``GenericObjectPool`` will create these objects in a background thread even if nothing is going on.

``minIdle``
   minimum number of lurkers

``softMinEvictableIdleTimeMills``
   time to wait before an object is cleaned up

The way it works is this, for a ``maxActive`` of 20 at most 20 objects will be created. If they are all returned the pool will throw the instances away until it has ``maxIdle`` (this is kind of its comfort zone). As each object times out we will be left with ``minIdle`` number of objects in the pool.::
    
      maxActive
   /--This is the absolute capacity of our ``ObjectCache``
   |
   |  Objects are immediately evicted when they are not in use
   |
   \-> ``maxIdle``
   /-- This is the "comfort zone" that your ``ObjectCache`` will try for under heavy use
   |
   |  Objects are evicted when they have not been used, every ``minEvictableIdleTimeMills`` 
   |
   \-> ``minIdle``
   /-> This is the number of Objects reserved when we are completely idle
   |
   | Objects are spawned as needed, every ``softMinEvictableIdleTimeMills``
   |
   \-- Empty