2010/12/15 - Apache Excalibur has been retired.

For more information, please explore the Attic.

Setting Up the PoolManager

In order to set up a CommandManager. For those instructions, follow the Command "How To". From there, you want to set up the PoolManager using the following code: 

                
// Using the CommandManager in the variable "commandManager"

PoolManager poolManager = new DefaultPoolManager( commandManager );

Creating Your Pool

The PoolManager is responsible for manufacturing managed pools, and for managing their sizes. All PoolManager managed pools are "soft" limiting. They will continue to grow while they are being accessed heavily, but it will shrink during times of inactivity. To create your pool, use the following code: 

                
int initialEntries = 20;
ObjectFactory objectFactory = new MySpecialObjectFactory();

Pool managedPool = poolManager.getManagedPool( objectFactory, initialEntries );

Writing an ObjectFactory

Writing an Object Factory is not that difficult. You just need to implement the ObjectFactory interface. Below is an example implementation: 

                    
public class MySpecialObjectFactory implements ObjectFactory
{
    private final Class m_mySpecialClass;

    /** Create default object type */
    public MySpecialObjectFactory()
    {
        this( MySpecialObject.class );
    }

    /** Create generic object type */
    public MySpecialObjectFactory( Class specialClass )
    {
        if ( null == specialClass )
        {
            throw new IllegalArgumentException ("Class cannot be null");
        }

        m_mySpecialClass = specialClass;
    }

    /** Implement the getCreatedClass() method */
    public Class getCreatedClass()
    {
        return m_mySpecialClass;
    }

    /** Create an instance */
    public Object newInstance()
        throws Exception
    {
        return getCreatedClass().newInstance();
    }

    /** Dispose of an instance */
    public void dispose( Object obj )
    {
        // perform permanent cleanup code
    }
}

Unmanaged Pools

There are two unmanaged pool types in MPool: FixedSizePool and BlockingFixedSizePool. They are similar to one another, but differ in how they respond to insufficient resources. The FixedSizePool fails fast, and throws an exception. The BlockingFixedSizePool tries to wait for a specified number of milliseconds.

The Fixed Size Pools are not managed because they will only have a certain number of pooled objects at any time. They will never grow or shrink. They are useful for instances where the number of elements are known in advanced. One example is a JDBC connection pool because some vendors require you to pay per connection licensing fees.

Using the Pool

Using the pools is quite simple: 

                
Object pooledResource = managedPool.acquire();

// do whatever I want with the pooled resource

managedPool.release( pooledResource );

What if we have an object that needs to perform some simple cleanup? Have your Object implement the Resettable interface. What if we are migrating from the old Pool package? You don't have to do anything. MPool knows about the old Pool package, and will check for its recyclable method. It will only call the Resettable.reset() method if your object implements both interfaces. Both of these will work: 

                
import org.apache.excalibur.mpool.Resettable;

public class ResettableObject implements Resettable
{
    // All the methods and stuff for the real object...

    public void reset()
    {
        // perform small cleanup code...
    }
}
              
            
                
import org.apache.avalon.excalibur.pool.Recyclable;

public class ResettableObject implements Recyclable
{
    // All the methods and stuff for the real object...

    public void recycle()
    {
        // perform small cleanup code...
    }
}