com.thoughtworks.proxy.toys.pool

Class Pool<T>

java.lang.Object

com.thoughtworks.proxy.toys.pool.Pool<T>

All Implemented Interfaces:

java.io.Serializable

public class Pool<T>
extends java.lang.Object
implements java.io.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 the 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. Every time 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.

A Pool instance can be created as usual with a builder, but also using various constructors to support dependency injection.

Since:

0.2

See Also:

com.thoughtworks.proxy.toys.pool, Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Pool.PoolBuild<T>
protected static class	Pool.PoolingInvoker<T> The Invoker of the proxy.
static class	Pool.PoolModeOrBuild<T>
static class	Pool.PoolResettedBy<T>
static class	Pool.PoolWith<T>

Field Summary

Fields

Modifier and Type	Field and Description
private java.util.List<ObjectReference<T>>	availableInstances
private java.util.Map<T,java.lang.ref.WeakReference<T>>	busyInstances
private ProxyFactory	factory
private Resetter<? super T>	resetter
private static java.lang.reflect.Method	returnInstanceToPool
private SerializationMode	serializationMode
private static long	serialVersionUID
private java.lang.Class<?>[]	types

Constructor Summary

Constructors

Modifier	Constructor and Description
private	Pool()
	Pool(java.lang.Class<T> type) Construct an Pool using the StandardProxyFactory for elements that do not have to be resetted.
	Pool(java.lang.Class<T> type, ProxyFactory proxyFactory) Construct a populated Pool with a specific proxy factory for elements that do not have to be resetted.
	Pool(java.lang.Class<T> type, Resetter<? super T> resetter) Construct an Pool using the StandardProxyFactory.
	Pool(java.lang.Class<T> type, Resetter<? super T> resetter, ProxyFactory proxyFactory) Construct a populated Pool with a specific proxy factory.
	Pool(java.lang.Class<T> type, Resetter<? super T> resetter, ProxyFactory proxyFactory, SerializationMode mode) Construct a populated Pool with a specific proxy factory and a serialization mode.

Method Summary

Modifier and Type	Method and Description
void	add(T... instances) Add an array of new instances as resources to the pool.
static <T> Pool.PoolResettedBy<T>	create(java.lang.Class<T> type) Creates a factory for a pool instance which proxy the managed elements in the pool.
T	get() Get an instance from the pool.
int	getAvailable() Return the number of available instances of the pool.
private void	readObject(java.io.ObjectInputStream in)
void	release(T object) Release a pool instance manually.
private void	returnInstanceToPool(ObjectReference<T> reference)
int	size() Retrieve the number of instances managed by the pool.
private void	writeObject(java.io.ObjectOutputStream out)

Methods inherited from class java.lang.Object

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

Field Detail

serialVersionUID

private static final long serialVersionUID

See Also:

Constant Field Values

returnInstanceToPool

private static final java.lang.reflect.Method returnInstanceToPool

types

private java.lang.Class<?>[] types

factory

private ProxyFactory factory

busyInstances

private transient java.util.Map<T,java.lang.ref.WeakReference<T>> busyInstances

availableInstances

private transient java.util.List<ObjectReference<T>> availableInstances

resetter

private Resetter<? super T> resetter

serializationMode

private SerializationMode serializationMode

Constructor Detail

Pool

public Pool(java.lang.Class<T> type)

Construct an Pool using the StandardProxyFactory for elements that do not have to be resetted.

Parameters:

type - the type of the instances

Since:

1.0

Pool

public Pool(java.lang.Class<T> type,
            Resetter<? super T> 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(java.lang.Class<T> type,
            ProxyFactory proxyFactory)

Construct a populated Pool with a specific proxy factory for elements that do not have to be resetted.

Parameters:

type - the type of the instances

proxyFactory - the proxy factory to use

Since:

1.0

Pool

public Pool(java.lang.Class<T> type,
            Resetter<? super T> 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(java.lang.Class<T> type,
            Resetter<? super T> resetter,
            ProxyFactory proxyFactory,
            SerializationMode mode)

Construct a populated Pool with a specific proxy factory and a serialization mode. This mode specify the behavior in case of a serialization of the Pool:

• SerializationMode.STANDARD: the standard mode, i.e. all elements of the pool are also serialized and a NotSerializableException may thrown
• SerializationMode.NONE: no element of the pool is also serialized and it must be populated again after serialization
• SerializationMode.FORCE: all element of the pool are serialized, if possible. Otherwise the pool is empty after serialization and must be populated again.

Parameters:

type - the type of the instances

resetter - the resetter of the pooled elements

proxyFactory - the proxy factory to use

mode - the serialization mode.

Since:

1.0

Pool

private Pool()

Method Detail

create

public static <T> Pool.PoolResettedBy<T> create(java.lang.Class<T> type)

Creates a factory for a pool instance which proxy the managed elements in the pool.

Parameters:

type - the type of the instances

Returns:

return the pool with parameters specified

Since:

1.0

add

public void add(T... instances)

Add an array of new instances as resources to the pool. The pool's monitor will be notified.

Parameters:

instances - the instances

Throws:

java.lang.NullPointerException - if instance is null

Since:

0.2

get

public T 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 forced by calling System.gc() first.

Returns:

an available instance from the pool or null.

Since:

0.2

release

public void release(T object)

Release a pool instance manually.

Parameters:

object - the instance to release

Throws:

java.lang.ClassCastException - if object was not Poolable.

java.lang.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 forced by calling System.gc() first. The pool's monitor will be notified, if any object was collected and the Resetter returned 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

returnInstanceToPool

private void returnInstanceToPool(ObjectReference<T> reference)

writeObject

private void writeObject(java.io.ObjectOutputStream out)
                  throws java.io.IOException

Throws:

java.io.IOException

readObject

private void readObject(java.io.ObjectInputStream in)
                 throws java.io.IOException,
                        java.lang.ClassNotFoundException

Throws:

java.io.IOException

java.lang.ClassNotFoundException