org.apache.tapestry.util.pool
Class Pool

java.lang.Object
  org.apache.tapestry.util.pool.Pool

All Implemented Interfaces:

ICleanable, IRenderDescription

public class Pool
extends Object
implements ICleanable, IRenderDescription

A Pool is used to pool instances of a useful class. It uses keys, much like a Map, to identify a list of pooled objects. Retrieving an object from the Pool atomically removes it from the pool. It can then be stored again later. In this way, a single Pool instance can manage many different types of pooled objects, filed under different keys.

Unlike traditional Pools, this class does not create new instances of the objects it stores (with the exception of simple Java Beans, via retrieve(Class). The usage pattern is to retrieve an instance from the Pool, and if the instance is null, create a new instance.

The implementation of Pool is threadsafe.

Pool implements ICleanable, with a goal of only keeping pooled objects that have been needed within a recent time frame. A generational system is used, where each pooled object is assigned a generation count. executeCleanup() discards objects whose generation count is too old (outside of a window).

Objects in the pool can receive two notifications: one notification when they are stored into the pool, and one when they are discarded from the pool.

Classes that implement IPoolable receive notifications directly, as per the two methods of that interface.

Alternately, an adaptor for the other classes can be registerered (using registerAdaptor(Class, IPoolableAdaptor). The adaptor will be invoked to handle the notification when a pooled object is stored or discarded.

Version:

$Id: Pool.java 243791 2004-02-19 17:38:13Z hlship $

Author:

Howard Lewis Ship

Constructor Summary

Pool()
Creates a new Pool using the default map size.

Pool(boolean useSharedJanitor)

Pool(int mapSize)
Deprecated. Use Pool() instead.

Pool(int mapSize, boolean useSharedJanitor)
Deprecated. Use Pool(boolean) instead.

Method Summary

void	clear() Removes all previously pooled objects from this Pool.
void	executeCleanup() Peforms culling of unneeded pooled objects.
IPoolableAdaptor	getAdaptor(Object object) Returns an adaptor appropriate to the object.
int	getKeyCount() Returns the number of keys within the pool.
int	getPooledCount() Returns the number of object pooled, the sum of the number of objects in pooled under each key.
int	getWindow() Returns the window used to cull pooled objects during a cleanup.
void	registerAdaptor(Class registrationClass, IPoolableAdaptor adaptor) Registers an adaptor for a particular class (or interface).
protected void	registerAdaptors() Invoked from the constructor to register the default set of IPoolableAdaptor.
void	renderDescription(IMarkupWriter writer) Object should render a description of itself to the writer.
Object	retrieve(Class objectClass) Retrieves an instance of the named class.
Object	retrieve(Object key) Returns a previously pooled object with the given key, or null if no such object exists.
void	setWindow(int value) Sets the window, or number of generations that an object may stay in the pool before being culled.
void	store(Object object) Stores an object using its class as a key.
void	store(Object key, Object object) Stores an object in the pool for later retrieval, resetting the object for storage within the pool.
String	toString()

Methods inherited from class java.lang.Object

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

Constructor Detail

Pool

public Pool()

Creates a new Pool using the default map size. Creation of the map is deferred.

Pool

public Pool(int mapSize)

Deprecated. Use Pool() instead.

Creates a new Pool using the specified map size. The map is created immediately.

Pool

public Pool(boolean useSharedJanitor)

Parameters:

useSharedJanitor - if true, then the Pool is added to the shared janitor.

Since:

1.0.5

Pool

public Pool(int mapSize,
            boolean useSharedJanitor)

Deprecated. Use Pool(boolean) instead.

Standard constructor.

Parameters:

mapSize - initial size of the map.

useSharedJanitor - if true, then the Pool is added to the shared janitor.

Since:

1.0.5

Method Detail

getWindow

public int getWindow()

Returns the window used to cull pooled objects during a cleanup. The default is 10, which works out to about five minutes with a standard janitor (on a 30 second cycle).

Since:

1.0.5

setWindow

public void setWindow(int value)

Sets the window, or number of generations that an object may stay in the pool before being culled.

Throws:

IllegalArgumentException - if value is less than 1.

Since:

1.0.5

retrieve

public Object retrieve(Object key)

Returns a previously pooled object with the given key, or null if no such object exists. Getting an object from a Pool removes it from the Pool, but it can later be re-added with store(Object,Object).

retrieve

public Object retrieve(Class objectClass)

Retrieves an instance of the named class. If no pooled instance is available, a new instance is created (using the no arguments constructor). Objects are pooled using their actual class as a key.

However, don't be fooled by false economies. Unless an object is very expensive to create, pooling is more expensive than simply instantiating temporary instances and letting the garbage collector deal with it (this is counter intuitive, but true). For example, this method was originally created to allow pooling of StringBuffer, but testing showed that it was a net defecit.

store

public void store(Object object)

Stores an object using its class as a key.

See Also:

retrieve(Class)

store

public void store(Object key,
                  Object object)

Stores an object in the pool for later retrieval, resetting the object for storage within the pool.

clear

public void clear()

Removes all previously pooled objects from this Pool.

getPooledCount

public int getPooledCount()

Returns the number of object pooled, the sum of the number of objects in pooled under each key.

Since:

1.0.2

getKeyCount

public int getKeyCount()

Returns the number of keys within the pool.

Since:

1.0.2

executeCleanup

public void executeCleanup()

Peforms culling of unneeded pooled objects.

Specified by:

executeCleanup in interface ICleanable

Since:

1.0.5

toString

public String toString()

Overrides:

toString in class Object

renderDescription

public void renderDescription(IMarkupWriter writer)

Description copied from interface: IRenderDescription

Object should render a description of itself to the writer.

Specified by:

renderDescription in interface IRenderDescription

Since:

1.0.6

registerAdaptors

protected void registerAdaptors()

Invoked from the constructor to register the default set of IPoolableAdaptor. Subclasses may override this to register a different set.

Registers:

• NullPoolableAdaptor for class Object
• DefaultPoolableAdaptor for interface IPoolable
• StringBufferAdaptor for StringBuffer

Since:

3.0

registerAdaptor

public void registerAdaptor(Class registrationClass,
                            IPoolableAdaptor adaptor)

Registers an adaptor for a particular class (or interface).

Since:

3.0

getAdaptor

public IPoolableAdaptor getAdaptor(Object object)

Returns an adaptor appropriate to the object.