Package de.aristaflow.adept2.util.objectpool

Interface ObjectLifeCycle<T,E extends Exception>

Type Parameters:

T - the type of object handled by this life cycle

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

public interface ObjectLifeCycle<T,E extends Exception>

This interface defines and allows to control the life cycle of a pooled object. This interface is recommended but not required when implementing ObjectPool.

If no checked exceptions are thrown, RuntimeException may be used as the second type parameter.

All descriptions here are of course only suggestions, but following them allows an efficient and consistent interaction between an object pool and an object life cycle.

Author:

Patrick Schmidt

Method Summary

Modifier and Type	Method	Description
void	activate(T p_object)	Activates the given object right before it is returned by ObjectPool.checkOut().
T	create()	Creates a new object.
void	destroy(T object)	Destroys the given object and is called right before an object is removed from the pool.
long	getLastActiveTime(T object)	Returns the time of the last recorded activity of the given object (i.e.
boolean	isValid(T object)	Examines the given object and returns whether it is still valid and usable.
void	passivate(T object)	Passivates the given object while it's being checked in.

Method Detail

create

T create()
  throws E extends Exception

Creates a new object. The object is expected to be activated, ready to be checked out immediately (activate(Object) will not be called on a just created object).

If the pool decides to create objects before they are actually required, it's possible that they are passivated immediately after their creation.

Returns:

a new (activated) object

Throws:

E - if there's a problem while creating an object. This exception will usually be propagated through ObjectPool.checkOut(). However, transparently retrying for a few times (and therefore swallowing exceptions) is well within the pool's discretion. If this method isn't called within ObjectPool.checkOut(), the exceptions may also be swallowed.

E extends Exception

activate

void activate(T p_object)
       throws E extends Exception

Activates the given object right before it is returned by ObjectPool.checkOut(). Implementations of this method might e.g. ensure that an object is in the same default state as new objects returned by create().

This method is only called for passivated objects, i.e. not for objects that were just created (created objects are expected to already be activated).

isValid(Object) is usually called right after this method.

Exceptions thrown by this method are usually swallowed by the pool, as it will most likely try to acquire another object instead (i.e. pick another one from the available ones or create a new one). I.e. an exception will generally result in the object being destroyed.

Parameters:

p_object - the object to be activated

Throws:

E - if there's a problem while activating the object; this exception may be swallowed by the pool and will generally result in the object being destroyed

E extends Exception

passivate

void passivate(T object)
        throws E extends Exception

Passivates the given object while it's being checked in. The main purpose of this method is to conclude the burrower's activities and release any resources that were forgotten to be closed explicitly by the burrower.

Raised exceptions will be propagated back to the burrower through ObjectPool.checkIn(Object) and are usually not interpreted as the object now being invalid. If that's the case, the object should rather be marked as invalid which is then e.g. detected by isValid(Object). In other words, this method should only throw exceptions that are in some way valuable to the burrower.

Example: The pool is used for Connections. When a returned connection has its auto commit turned off, this method will (according to preferences) try a rollback, a commit and/or turn auto commit on (which will trigger a commit). All three may throw SQLExceptions that should be propagated back to the user (through ObjectPool.checkIn(Object)).

Parameters:

object - the object to be passivated

Throws:

E - if there's a problem while passivating the object; this exception should not be swallowed by the pool, but instead be propagated through ObjectPool.checkIn(Object)

E extends Exception

destroy

void destroy(T object)
      throws E extends Exception

Destroys the given object and is called right before an object is removed from the pool. This method may be called at any point and should be able to deal with objects in any state.

Even though this method is allowed to throw an exception, that exception is usually swallowed by the pool implementation.

Parameters:

object - the object to be destroyed

Throws:

E - if there's a problem while destroying the object; this exception is usually swallowed by the pool

E extends Exception

isValid

boolean isValid(T object)

Examines the given object and returns whether it is still valid and usable. This method may be called at any point and should be able to deal with objects in any state.

activation and right after passivation. It may also be used for periodic validation of available pooled objects (if supported by the pool). Therefore it should be as efficient as possible.

Parameters:

object - the object to be tested for validity

Returns:

whether the given object is still valid and usable

getLastActiveTime

long getLastActiveTime(T object)

Returns the time of the last recorded activity of the given object (i.e. the last time, the object was used by the borrower). If this information is not available within the object, -1 is returned.

This method is only called if the pool does not support or use a ObjectWrapperLifeCycle (since it offers the same method).

Parameters:

object - the object

Returns:

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