org.picocontainer.gems.behaviors
Class Pooled<T>

java.lang.Object
  org.picocontainer.behaviors.AbstractBehavior<T>
      org.picocontainer.gems.behaviors.Pooled<T>

All Implemented Interfaces:

Serializable, Behavior<T>, ComponentAdapter<T>, ComponentLifecycle<T>, ComponentMonitorStrategy, LifecycleStrategy

public final class Pooled<T>
extends AbstractBehavior<T>

ComponentAdapter implementation that pools components.

The implementation utilizes a delegated ComponentAdapter to create the instances of the pool. The pool can be configured to grow unlimited or to a maximum size. If a component is requested from this adapter, the implementation returns an available instance from the pool or will create a new one, if the maximum pool size is not reached yet. If none is available, the implementation can wait a defined time for a returned object before it throws a Pooled.PoolException.

This implementation uses the Pool toy from the ProxyToys project. This ensures, that any component, that is out of scope will be automatically returned to the pool by the garbage collector. Additionally will every component instance also implement Poolable, that can be used to return the instance manually. After returning an instance it should not be used in client code anymore.

Before a returning object is added to the available instances of the pool again, it should be reinitialized to a normalized state. By providing a proper Resetter implementation this can be done automatically. If the object cannot be reused anymore it can also be dropped and the pool may request a new instance.

The pool supports components with a lifecycle. If the delegated ComponentAdapter implements a LifecycleStrategy, any component retrieved form the pool will be started before and stopped again, when it returns back into the pool. Also if a component cannot be resetted it will automatically be disposed. If the container of the pool is disposed, that any returning object is also disposed and will not return to the pool anymore. Note, that current implementation cannot dispose pooled objects.

Author:

Jörg Schaible, Aslak Hellesøy

See Also:

Serialized Form

Nested Class Summary

static interface	Pooled.Context Context of the Pooled used to initialize it.
static class	Pooled.DefaultContext The default context for a Pooled.
static class	Pooled.PoolException Exception thrown from the Pooled.

Nested classes/interfaces inherited from interface org.picocontainer.ComponentAdapter

ComponentAdapter.NOTHING

Field Summary

static int	BLOCK_ON_WAIT BLOCK_ON_WAIT forces the pool to wait until an object of the pool is returning in case none is immediately available.
static int	DEFAULT_MAX_SIZE DEFAULT_MAX_SIZE is the default size of the pool.
static Resetter	DEFAULT_RESETTER DEFAULT_RESETTER is a NoOperationResetter that is used by default.
static int	FAIL_ON_WAIT FAIL_ON_WAIT forces the pool to fail none is immediately available.
static int	UNLIMITED_SIZE UNLIMITED_SIZE is the value to set the maximum size of the pool to unlimited (Integer.MAX_VALUE in fact).

Fields inherited from class org.picocontainer.behaviors.AbstractBehavior

delegate

Constructor Summary

protected	Pooled() Construct an empty ComponentAdapter, used for serialization with reflection only.
	Pooled(ComponentAdapter delegate, Pooled.Context context) Construct a Pooled.

Method Summary

void	dispose(PicoContainer container) Dispose of the container will dispose all returning objects.
T	getComponentInstance(PicoContainer container, Type into)
String	getDescriptor()
int	size() Retrieve the current size of the pool.
void	start(PicoContainer container) Start of the container ensures that at least one pooled component has been started.
void	stop(PicoContainer container) Stop of the container has no effect for the pool.

Methods inherited from class org.picocontainer.behaviors.AbstractBehavior

accept, changeMonitor, componentHasLifecycle, currentMonitor, dispose, findAdapterOfType, getComponentImplementation, getComponentInstance, getComponentKey, getDelegate, hasLifecycle, isLazy, isStarted, start, stop, toString, verify

Methods inherited from class java.lang.Object

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

Field Detail

UNLIMITED_SIZE

public static final int UNLIMITED_SIZE

UNLIMITED_SIZE is the value to set the maximum size of the pool to unlimited (Integer.MAX_VALUE in fact).

See Also:

Constant Field Values

DEFAULT_MAX_SIZE

public static final int DEFAULT_MAX_SIZE

DEFAULT_MAX_SIZE is the default size of the pool.

See Also:

Constant Field Values

BLOCK_ON_WAIT

public static final int BLOCK_ON_WAIT

BLOCK_ON_WAIT forces the pool to wait until an object of the pool is returning in case none is immediately available.

See Also:

Constant Field Values

FAIL_ON_WAIT

public static final int FAIL_ON_WAIT

FAIL_ON_WAIT forces the pool to fail none is immediately available.

See Also:

Constant Field Values

DEFAULT_RESETTER

public static final Resetter DEFAULT_RESETTER

DEFAULT_RESETTER is a NoOperationResetter that is used by default.

Constructor Detail

Pooled

public Pooled(ComponentAdapter delegate,
              Pooled.Context context)

Construct a Pooled. Remember, that the implementation will request new components from the delegate as long as no component instance is available in the pool and the maximum pool size is not reached. Therefore the delegate may not return the same component instance twice. Ensure, that the used ComponentAdapter does not cache.

Parameters:

delegate - the delegated ComponentAdapter

context - the Pooled.Context of the pool

Throws:

IllegalArgumentException - if the maximum pool size or the serialization mode is invalid

Pooled

protected Pooled()

Construct an empty ComponentAdapter, used for serialization with reflection only.

Method Detail

getComponentInstance

public T getComponentInstance(PicoContainer container,
                              Type into)

As long as the maximum size of the pool is not reached and the pool is exhausted, the implementation will request its delegate for a new instance, that will be managed by the pool. Only if the maximum size of the pool is reached, the implementation may wait (depends on the initializing Pooled.Context) for a returning object.

Specified by:

getComponentInstance in interface ComponentAdapter<T>

Overrides:

getComponentInstance in class AbstractBehavior<T>

Throws:

Pooled.PoolException - if the pool is exhausted or waiting for a returning object timed out or was interrupted

getDescriptor

public String getDescriptor()

size

public int size()

Retrieve the current size of the pool. The returned value reflects the number of all managed components.

Returns:

the number of components.

start

public void start(PicoContainer container)

Start of the container ensures that at least one pooled component has been started. Applies only if the delegated ComponentAdapter supports a lifecylce by implementing LifecycleStrategy.

Specified by:

start in interface ComponentLifecycle<T>

Overrides:

start in class AbstractBehavior<T>

Throws:

IllegalStateException - if pool was already disposed

stop

public void stop(PicoContainer container)

Stop of the container has no effect for the pool. Applies only if the delegated ComponentAdapter supports a lifecylce by implementing LifecycleStrategy.

Specified by:

stop in interface ComponentLifecycle<T>

Overrides:

stop in class AbstractBehavior<T>

Throws:

IllegalStateException - if pool was already disposed

dispose

public void dispose(PicoContainer container)

Dispose of the container will dispose all returning objects. They will not be added to the pool anymore. Applies only if the delegated ComponentAdapter supports a lifecylce by implementing LifecycleStrategy.

Specified by:

dispose in interface ComponentLifecycle<T>

Overrides:

dispose in class AbstractBehavior<T>

Throws:

IllegalStateException - if pool was already disposed