com.thoughtworks.proxy.toys.pool
Class Pool

java.lang.Object
  extended by com.thoughtworks.proxy.toys.pool.Pool
All Implemented Interfaces:
Serializable

public class Pool
extends Object
implements Serializable

A simple pool implementation that collects its unused components of a specific type automatically.

The pool will only manage instances that were explicitly passed into the pool before. For more sophisticated pooling strategies, derive from this class or wrap it.

The implementation will provide these instances wrapped by a proxy, that will return the instance automatically to the pool, if it falls out of scope and is collected by the garbage collector. Since the pool only returns instances wrapped by a proxy that implements the Poolable interface, this can be used to release th instance manually to the pool also. With an implementation of the Resetter interface each element's status can be reset or the element can be dropped from the pool at all, if it is exhausted.

A client can use the pool's monitor for an improved synchronization. Everytime an object is returned to the pool, all waiting Threads of the monitor will be notified. This notification will happen independently of the result of the Resetter.reset(Object) method.

Since:
0.2
Author:
Jörg Schaible
See Also:
com.thoughtworks.proxy.toys.pool, Serialized Form

Nested Class Summary
protected static class Pool.PoolingInvoker
          The Invoker of the proxy.
 
Field Summary
static int SERIALIZATION_FORCE
          SERIALIZATION_FORCE is the value for serialization of the pool with or without serializable objects.
static int SERIALIZATION_NONE
          SERIALIZATION_NONE is the value for serialization of the pool without the objects.
static int SERIALIZATION_STANDARD
          SERIALIZATION_STANDARD is the value for the standard serialization of the pool with its objects.
 
Constructor Summary
Pool(Class type, Resetter resetter)
          Construct an Pool using the StandardProxyFactory.
Pool(Class type, Resetter resetter, ProxyFactory proxyFactory)
          Construct a populated Pool with a specific proxy factory.
Pool(Class type, Resetter resetter, ProxyFactory proxyFactory, int serializationMode)
          Construct a populated Pool with a specific proxy factory and a serialization mode.
 
Method Summary
 void add(Object instance)
          Add a new instance as resource to the pool.
 void add(Object[] instances)
          Add an array of new instances as resources to the pool.
 Object get()
          Get an instance from the pool.
 int getAvailable()
          Return the number of available instances of the pool.
 void release(Object object)
          Release a pool instance manually.
 int size()
          Retrieve the number of instances managed by the pool.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

SERIALIZATION_FORCE

public static final int SERIALIZATION_FORCE
SERIALIZATION_FORCE is the value for serialization of the pool with or without serializable objects. If the obejcts cannot be serialized, the pool is emtpy after serialization und must be populated again.

See Also:
Constant Field Values

SERIALIZATION_STANDARD

public static final int SERIALIZATION_STANDARD
SERIALIZATION_STANDARD is the value for the standard serialization of the pool with its objects. If the obejcts cannot be serialized, a NotSerializableException is thrown.

See Also:
Constant Field Values

SERIALIZATION_NONE

public static final int SERIALIZATION_NONE
SERIALIZATION_NONE is the value for serialization of the pool without the objects. The pool is emtpy after serialization und must be populated again.

See Also:
Constant Field Values
Constructor Detail

Pool

public Pool(Class type,
            Resetter resetter)
Construct an Pool using the StandardProxyFactory.

Parameters:
type - the type of the instances
resetter - the resetter of the pooled elements
Since:
0.2

Pool

public Pool(Class type,
            Resetter resetter,
            ProxyFactory proxyFactory)
Construct a populated Pool with a specific proxy factory.

Parameters:
type - the type of the instances
resetter - the resetter of the pooled elements
proxyFactory - the proxy factory to use
Since:
0.2

Pool

public Pool(Class type,
            Resetter resetter,
            ProxyFactory proxyFactory,
            int serializationMode)
Construct a populated Pool with a specific proxy factory and a serialization mode. This mode specify the behaviour in case of a serialization of the Pool:

Parameters:
type - the type of the instances
resetter - the resetter of the pooled elements
proxyFactory - the proxy factory to use
serializationMode - true if serialization is done even if the pooled objects are not serializable. The deserialized Pool will not have any objects in the Pool though.
Throws:
IllegalArgumentException - if the serialization mode is not one of the predefined values
Since:
0.2
Method Detail

add

public void add(Object instance)
Add a new instance as resource to the pool. The pool's monitor will be notified.

Parameters:
instance - the new instance
Throws:
NullPointerException - if instance is null
Since:
0.2

add

public void add(Object[] instances)
Add an array of new instances as resources to the pool. The pool's monitor will be notified.

Parameters:
instances - the instances
Throws:
NullPointerException - if instance is null
Since:
0.2

get

public Object get()
Get an instance from the pool. If no instance is immediately available, the method will check internally for returned objects from the garbage collector. This can be foreced by calling System.gc() first.

Returns:
an available instance from the pool or null.
Since:
0.2

release

public void release(Object object)
Release a pool instance manually.

Parameters:
object - the instance to release
Throws:
ClassCastException - if object was not Poolable.
IllegalArgumentException - if the object was not from this pool.
Since:
0.2

getAvailable

public int getAvailable()
Return the number of available instances of the pool. The method will also try to collect any pool instance that was freed by the garbage collector. This can be foreced by calling System.gc() first. The pool's monitor will be notified, if any object was collected and the Resetter retunred the object.

Returns:
the number of available instances.
Since:
0.2

size

public int size()
Retrieve the number of instances managed by the pool.

Returns:
the number of instances.
Since:
0.2