com.cafesoft.core.pool
Interface ObjectPool

All Superinterfaces:

Recyclable

All Known Implementing Classes:

DefaultObjectPool

public interface ObjectPool

extends Recyclable

The ObjectPool interface defines a collection of methods that define a basic ObjectPool. This particular interface supports the ability to modify the minimum and maximum number of objects created in the pool. In addition, allows for developer to specify an expiration time at which idle objects are reclaimed for reuse.

Since:

10/19/01

Method Summary

Object	borrowObject() Borrow an object from the ObjectPool Note: Implementing class should make this method synchronized.
void	cleanIdle() Remove idle objects from the ObjectPool.
void	cleanIdle(int number) Remove the given number of idle objects from the ObjectPool.
void	close() Close the ObjectPool.
long	getExpiration() Get the expiration time of objects in the ObjectPool
int	getMaximum() Get the maximum number of objects the ObjectPool must maintain
int	getMinimum() Get the minimum number of objects the ObjectPool must maintain
PoolableObjectFactory	getPoolableObjectFactory() Get the PoolableObjectFactory that the ObjectPool is currently using.
int	numActive() Get the number of active ObjectPool objects being used.
int	numIdle() Get the number of idle ObjectPool objects being used.
void	returnObject(Object object) Return an object to the ObjectPool.
void	setDebug(boolean debug) Set debug on or off
void	setExpiration(long expiration) Set the expiration time for objects in the ObjectPool.
void	setMaximum(int maximum) Set the maximum number of objects both active and inactive that the ObjectPool must maintain.
void	setMinimum(int minimum) Set the minimum number of objects both active and inactive that the ObjectPool must maintain.
void	setPoolableObjectFactory(PoolableObjectFactory poolableObjectFactory) Set the PoolableObjectFactory that the ObjectPool will use.

Methods inherited from interface com.cafesoft.core.util.Recyclable

recycle

Method Detail

borrowObject

public Object borrowObject()
                    throws Exception

Borrow an object from the ObjectPool

Note: Implementing class should make this method synchronized.

This method is responsible for "checking-out" an object for use. It is recommended that the implementing class provide a Class specific get method that casts the generic object returned by this method to the appropriate class.

For example:

 ConnectionPool implements ObjectPool
 {
      public Connection getConnection() throws ConnectionException
      {
          return (Connection) borrowObject();
      }
 }
 

Returns:

an object from the ObjectPool

Throws:

Exception - thrown if an error occurs while trying to get an instance of an object to use. Typically this will be the result of the createObject() method from the implementing PoolableObjectFactory assigned to the ObjectPool

returnObject

public void returnObject(Object object)

Return an object to the ObjectPool.

Note: Implementing class should make this method synchronized.

This method is responsible for "checking-in" an object. It is recommended that the implementing class provide a Class specific return method that accepts the specific class as a parameter.

For example:

 ConnectionPool implements ObjectPool
 {
      public void releaseConnection(Connection connection)
      {
          returnObject(connection);
      }
 }
 

Parameters:

object - The object to be returned to the ObjectPool

cleanIdle

public void cleanIdle()

Remove idle objects from the ObjectPool.

Remove objects that are not actively used and release their resources. See the implementation for specifics as to the algorithm that is used to determine idle object status.

cleanIdle

public void cleanIdle(int number)

Remove the given number of idle objects from the ObjectPool.

Remove objects that are not actively used and release their resources. See the implementation for specifics as to the algorithm that is used to determine idle object status.

Parameters:

number - the number of idle objects to remove unless removing the specified number of objects would put the ObjectPool below it's minimum number of objects

close

public void close()

Close the ObjectPool.

Destroy all objects and release all resources that were used by both the objects in the ObjectPool and the ObjectPool itself

numActive

public int numActive()

Get the number of active ObjectPool objects being used.

Returns:

An integer representing the number of active ObjectPool objects

numIdle

public int numIdle()

Get the number of idle ObjectPool objects being used.

Returns:

An integer representing the number of idle ObjectPool objects

getPoolableObjectFactory

public PoolableObjectFactory getPoolableObjectFactory()

Get the PoolableObjectFactory that the ObjectPool is currently using.

The PoolableObjectFactory is responsible for object creation, destruction, and validation.

Returns:

The PoolableObjectFactory being used or null if a PoolableObjectFactory is currently not set.

setPoolableObjectFactory

public void setPoolableObjectFactory(PoolableObjectFactory poolableObjectFactory)

Set the PoolableObjectFactory that the ObjectPool will use.

The PoolableObjectFactory is responsible for object creation, destruction, and validation.

Parameters:

poolableObjectFactory - The new poolableObjectFactory for the ObjectPool to use.

setMinimum

public void setMinimum(int minimum)

Set the minimum number of objects both active and inactive that the ObjectPool must maintain. Use 0 to set no minimum.

Formula for determining minimum object status
numActive() + numIdle() >= minimum

Parameters:

minimum - The new minimum number of objects that the ObjectPool must maintain.

setMaximum

public void setMaximum(int maximum)

Set the maximum number of objects both active and inactive that the ObjectPool must maintain. Use 0 to set no maximum.

Formula for determining maximum object status
numActive() + numIdle() <= maximum

Parameters:

maximum - The new maximum number of objects that the ObjectPool must maintain.

setExpiration

public void setExpiration(long expiration)

Set the expiration time for objects in the ObjectPool. Use 0 to set no expiration time.

Set the time that an object is allowed to remain in an idle state before it is collected and recycled by the pool. The implementing class is responsible for creating the mechanism to use the expiration time to expire objects.

Parameters:

expiration - The new expiration time for the ObjectPool to use.

getMinimum

public int getMinimum()

Get the minimum number of objects the ObjectPool must maintain

Returns:

The minimum number of objects the ObjectPool must maintain

getMaximum

public int getMaximum()

Get the maximum number of objects the ObjectPool must maintain

Returns:

The maximum number of objects the ObjectPool must maintain

getExpiration

public long getExpiration()

Get the expiration time of objects in the ObjectPool

Returns:

The expiration time of objects in the ObjectPool

setDebug

public void setDebug(boolean debug)

Set debug on or off

Parameters:

debug - the value of debug true is on false is off