de.aristaflow.adept2.util.objectpool

Interface ObjectWrapperLifeCycle<T,E extends java.lang.Exception>

Type Parameters:

T - the type of object wrapped by this wrapper life cycle

E - the specific type of exceptions associated when using the objects

public interface ObjectWrapperLifeCycle<T,E extends java.lang.Exception>

This interface is a companion to ObjectLifeCycle, defining and allowing to control the life cycle of an object wrapper.

Wrappers are required if object pools should not hand out references to the actual objects. This prevents that references to the real object are kept (and used) even after checking an object back into the pool. This also allows the pool to forcibly reclaim the pooled object if necessary by invalidating the wrapper. Another benefit is that objects can be returned to the pool without the user needing a reference to the pool, i.e. only the wrapper needs to have it.

Also, interfaces that provide methods to explicitly release the resource, like Connection.close(), will need to be wrapped. This allows the objects to be treated as usual, without having the user to know whether - to stick with the example - the connection is actually closed or returned to a pool behind the scenes.

AbstractObjectWrapper is a convenient base class for wrapper implementations.

Author:

Patrick Schmidt

Method Summary

Modifier and Type	Method and Description
long	getLastActiveTime(T wrapper) Returns the time of the wrapped object's last recorded activity (i.e. the last time, the wrapped object was used by the borrower).
void	invalidate(T wrapper) Invalidates the given wrapper.
boolean	isWrapper(T object) Returns whether the given object is a wrapper (as returned by wrap(ObjectPool,Object)).
T	unwrap(T wrapper) Returns the object that is wrapped by the given wrapper (as returned by wrap(ObjectPool,Object)).
T	wrap(ObjectPool<T,E> objectPool, T object) Wraps the given object and returns the created wrapper.

Method Detail

wrap

T wrap(ObjectPool<T,E> objectPool,
       T object)

Wraps the given object and returns the created wrapper.

This method is not supposed to call any methods on the given object pool. Instead the reference is just passed on to the wrapper if it needs it.

Parameters:

objectPool - the object pool calling this method

object - the object to be wrapped

Returns:

the wrapper for the given object

unwrap

T unwrap(T wrapper)

Returns the object that is wrapped by the given wrapper (as returned by wrap(ObjectPool,Object)). This will not invalidate the wrapper!

Parameters:

wrapper - the wrapper for which to return the contained object

Returns:

the object that is wrapped by the given wrapper

Throws:

java.lang.ClassCastException - if the given object is no wrapper

java.lang.IllegalArgumentException - if the wrapper has already been invalidated

isWrapper

boolean isWrapper(T object)

Returns whether the given object is a wrapper (as returned by wrap(ObjectPool,Object)).

Parameters:

object - the object to be tested

Returns:

whether the given object is a wrapper

invalidate

void invalidate(T wrapper)

Invalidates the given wrapper. I.e. all subsequent attempts to use the object through that wrapper must fail, e.g. by throwing an IllegalStateException.

Parameters:

wrapper - the wrapper to be invalidated

Throws:

java.lang.IllegalArgumentException - if the given object is no wrapper

getLastActiveTime

long getLastActiveTime(T wrapper)

Returns the time of the wrapped object's last recorded activity (i.e. the last time, the wrapped object was used by the borrower). This information may be present in the wrapped object directly or provided by the wrapper. If this information is not available at all, -1 is returned.

Parameters:

wrapper - the wrapper of the object

Returns:

the time of the wrapped object's last recorded activity or -1 if this information is not available; other negative numbers are not allowed

Throws:

java.lang.IllegalArgumentException - if the given object is no wrapper or the wrapper has already been invalidated