org.apache.commons.pool2.overview.html Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of commons-pool2 Show documentation
Apache Commons Object Pooling Library
There is a newer version: 2.12.0



   
      Overview of the org.apache.commons.pool2 component
   
   
      
         Generic Object pooling API with several implementations.
      
      
         The org.apache.commons.pool2 package defines a simple
         interface for a pool of object instances, and a handful of base
         classes that may be useful when creating pool implementations.
         The API supports pooling of unique objects which can be requested
         via a key as well as pools where all objects are equivalent.
      
      
         The org.apache.commons.pool2.impl package contains
         several pool implementations.
         {@link org.apache.commons.pool2.impl.GenericObjectPool
         GenericObjectPool} has many configuration options and can support
         a limited set of objects such as would be useful in a database
         connection pool.
         {@link org.apache.commons.pool2.impl.SoftReferenceObjectPool
         SoftReferenceObjectPool} has no limit on the number of objects in the
         pool, but the garbage collector can remove idle objects from the pool
         as needed.  There is also a keyed version of
         {@link org.apache.commons.pool2.impl.GenericObjectPool
         GenericObjectPool},
         {@link org.apache.commons.pool2.impl.GenericKeyedObjectPool
         GenericKeyedObjectPool}
      
      
         Here is a simple example of pooling HashMap instances.
         First create an {@link org.apache.commons.pool2.PoolableObjectFactory
         PoolableObjectFactory}
      
    public class HashMapFactory
        extends {@link org.apache.commons.pool2.BasePoolableObjectFactory BasePoolableObjectFactory}<Map<Object,Object>>
    {
        /**
         * Creates an instance that can be returned by the pool.
         * @return an instance that can be returned by the pool.
         */
        public Map<Object,Object> makeObject()
            throws Exception
        {
            return new HashMap<Object,Object>();
        }

        /**
         * Uninitialize an instance to be returned to the pool.
         * @param obj the instance to be passivated
         */
        public void passivateObject(Map<Object,Object> obj)
            throws Exception
        {
            obj.clear();
        }
    }

      
         A class that makes frequent use of a Map could then use a pool
         as shown below:
      
    public class Foo
    {
        private {@link org.apache.commons.pool2.ObjectPool ObjectPool<Map<Object,Object>>} pool;
        public Foo()
        {
            {@link org.apache.commons.pool2.PoolableObjectFactory PoolableObjectFactory<Map<Object,Object>>} factory = new HashMapFactory();
            pool = new {@link org.apache.commons.pool2.impl.GenericObjectPool GenericObjectPool}<Map<Object,Object>>(factory);
        }

        public doSomething()
        {
            ...
            Map<Object,Object> map = null;
            try
            {
                map = pool.borrowObject();
                // use map
                ...
            }
            finally
            {
                if (map != null)
                {
                    pool.returnObject(map);
                }
            }
            ...
        }
    }



The above example shows how one would use an
{@link org.apache.commons.pool2.ObjectPool ObjectPool}.  The other supplied
implementations or another special purpose pool would be used similarly.