org.apache.avalon.excalibur.pool

Class ValidatedResourceLimitingPool

java.lang.Object

org.apache.avalon.framework.logger.AbstractLogEnabled

org.apache.avalon.excalibur.pool.InstrumentedResourceLimitingPool

org.apache.avalon.excalibur.pool.TraceableResourceLimitingPool

org.apache.avalon.excalibur.pool.ValidatedResourceLimitingPool

All Implemented Interfaces:

org.apache.avalon.excalibur.pool.Pool, org.apache.avalon.framework.activity.Disposable, org.apache.avalon.framework.logger.LogEnabled, org.apache.avalon.framework.thread.ThreadSafe, org.apache.excalibur.instrument.Instrumentable

public class ValidatedResourceLimitingPool
extends TraceableResourceLimitingPool

A ResourceLimitingPool which validates reused poolables before they are returned with a call get().

Since:

4.1

Version:

CVS $Revision: 1.6 $ $Date: 2004/03/31 08:07:28 $

Author:

Avalon Development Team

Nested Class Summary

Nested classes/interfaces inherited from class org.apache.avalon.excalibur.pool.TraceableResourceLimitingPool

TraceableResourceLimitingPool.State, TraceableResourceLimitingPool.TraceException

Field Summary

Fields

Modifier and Type	Field and Description
private boolean	m_needsValidation Used for communication between the get() and newPoolable() methods, only valid within a single synchronized block.

Fields inherited from class org.apache.avalon.excalibur.pool.InstrumentedResourceLimitingPool

DEFAULT_INSTRUMENTABLE_NAME, INSTRUMENT_BLOCKS_NAME, INSTRUMENT_CREATES_NAME, INSTRUMENT_DECOMMISSIONS_NAME, INSTRUMENT_GETS_NAME, INSTRUMENT_PUTS_NAME, INSTRUMENT_READY_SIZE_NAME, INSTRUMENT_SIZE_NAME, m_semaphore

Fields inherited from interface org.apache.excalibur.instrument.Instrumentable

EMPTY_INSTRUMENT_ARRAY, EMPTY_INSTRUMENTABLE_ARRAY

Constructor Summary

Constructors

Constructor and Description
ValidatedResourceLimitingPool(org.apache.avalon.excalibur.pool.ObjectFactory factory, int max, boolean maxStrict, boolean blocking, long blockTimeout, long trimInterval) Creates a new ValidatedResourceLimitingPool
ValidatedResourceLimitingPool(org.apache.avalon.excalibur.pool.ObjectFactory factory, int max, boolean maxStrict, boolean blocking, long blockTimeout, long trimInterval, boolean trace) Creates a new ValidatedResourceLimitingPool

Method Summary

Methods

Modifier and Type	Method and Description
org.apache.avalon.excalibur.pool.Poolable	get() Gets a Poolable from the pool.
protected org.apache.avalon.excalibur.pool.Poolable	newPoolable() Create a new poolable instance by by calling the newInstance method on the pool's ObjectFactory.
protected boolean	validatePoolable(org.apache.avalon.excalibur.pool.Poolable poolable) If the poolable implements Validatable, then its validate() method will be called to give the poolable a chance to validate itself.

Methods inherited from class org.apache.avalon.excalibur.pool.TraceableResourceLimitingPool

getState, put, removePoolable

Methods inherited from class org.apache.avalon.excalibur.pool.InstrumentedResourceLimitingPool

dispose, getChildInstrumentables, getInstrumentableName, getInstruments, getReadySize, getSize, permanentlyRemovePoolable, setInstrumentableName, trim

Methods inherited from class org.apache.avalon.framework.logger.AbstractLogEnabled

enableLogging, getLogger, setupLogger, setupLogger, setupLogger

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.apache.avalon.framework.logger.LogEnabled

enableLogging

Field Detail

m_needsValidation

private boolean m_needsValidation

Used for communication between the get() and newPoolable() methods, only valid within a single synchronized block.

Constructor Detail

ValidatedResourceLimitingPool

public ValidatedResourceLimitingPool(org.apache.avalon.excalibur.pool.ObjectFactory factory,
                             int max,
                             boolean maxStrict,
                             boolean blocking,
                             long blockTimeout,
                             long trimInterval,
                             boolean trace)

Creates a new ValidatedResourceLimitingPool

Parameters:

factory - The ObjectFactory which will be used to create new Poolables as needed by the pool.

max - Maximum number of Poolables which can be stored in the pool, 0 implies no limit.

maxStrict - true if the pool should never allow more than max Poolable to be created. Will cause an exception to be thrown if more than max Poolables are requested and blocking is false.

blocking - true if the pool should cause a thread calling get() to block when Poolables are not currently available on the pool.

blockTimeout - The maximum amount of time, in milliseconds, that a call to get() will block before an exception is thrown. A value of 0 implies an indefinate wait.

trimInterval - The minimum interval with which old unused poolables will be removed from the pool. A value of 0 will cause the pool to never trim poolables.

trace - True if tracing of gets is enabled for the pool.

ValidatedResourceLimitingPool

public ValidatedResourceLimitingPool(org.apache.avalon.excalibur.pool.ObjectFactory factory,
                             int max,
                             boolean maxStrict,
                             boolean blocking,
                             long blockTimeout,
                             long trimInterval)

Creates a new ValidatedResourceLimitingPool

Parameters:

factory - The ObjectFactory which will be used to create new Poolables as needed by the pool.

max - Maximum number of Poolables which can be stored in the pool, 0 implies no limit.

maxStrict - true if the pool should never allow more than max Poolable to be created. Will cause an exception to be thrown if more than max Poolables are requested and blocking is false.

blocking - true if the pool should cause a thread calling get() to block when Poolables are not currently available on the pool.

blockTimeout - The maximum amount of time, in milliseconds, that a call to get() will block before an exception is thrown. A value of 0 implies an indefinate wait.

trimInterval - The minimum interval with which old unused poolables will be removed from the pool. A value of 0 will cause the pool to never trim poolables.

Method Detail

get

public org.apache.avalon.excalibur.pool.Poolable get()
                                              throws java.lang.Exception

Gets a Poolable from the pool. If there is room in the pool, a new Poolable will be created. Depending on the parameters to the constructor, the method may block or throw an exception if a Poolable is not available on the pool.

Specified by:

get in interface org.apache.avalon.excalibur.pool.Pool

Overrides:

get in class TraceableResourceLimitingPool

Returns:

Always returns a Poolable. Contract requires that put must always be called with the Poolable returned.

Throws:

java.lang.Exception - An exception may be thrown as described above or if there is an exception thrown by the ObjectFactory's newInstance() method.

newPoolable

protected org.apache.avalon.excalibur.pool.Poolable newPoolable()
                                                         throws java.lang.Exception

Create a new poolable instance by by calling the newInstance method on the pool's ObjectFactory. This is the method to override when you need to enforce creational policies. This method is only called by threads that have m_semaphore locked.

Overrides:

newPoolable in class InstrumentedResourceLimitingPool

Throws:

java.lang.Exception

validatePoolable

protected boolean validatePoolable(org.apache.avalon.excalibur.pool.Poolable poolable)
                            throws java.lang.Exception

If the poolable implements Validatable, then its validate() method will be called to give the poolable a chance to validate itself. Different functionality can be achieved by overriding this method. This method is only called by threads that have m_semaphore locked.

Parameters:

poolable - The Poolable to be validated

Returns:

true if the Poolable is valid, false if it should be removed from the pool.

Throws:

java.lang.Exception