de.aristaflow.adept2.util.objectpool.generic

Class GenericObjectPool<T,E extends java.lang.Exception>

java.lang.Object

de.aristaflow.adept2.util.objectpool.generic.GenericObjectPool<T,E>

Type Parameters:

T - the type of objects managed by the object pool

E - the type of exceptions involved in the life cycle of the managed objects

All Implemented Interfaces:

ObjectPool<T,E>

public class GenericObjectPool<T,E extends java.lang.Exception>
extends java.lang.Object
implements ObjectPool<T,E>

A generic but sophisticated implementation of ObjectPool.

The pool has a certain number of slots that is determined by PoolConfiguration.getMaxObjectCount(). Some slots contain checked out objects, all other slots are available. They are either empty or contain available objects that can be checked out. If no object's are available, an empty slot will be filled with a new object which can then be checked out.

Please note: If at all, Object.equals(Object) and Object.hashCode() on the pooled objects must be implemented in such a way that no two different objects in the pool share the same "identity".

Some features:

• Leases: A lease is the permission to use an object that is granted when the object is checked out. This lease may be time-limited and expire after a certain period of time. After that, the right to use the object / resource may be revoked and the object reclaimed at any time, which depends on the pool's configuration.
• Abandoned objects: After a certain period of time since the last active time of an object, the object may be considered abandoned. After that, the object may be reclaimed at any time, which depends on the pool's configuration.
• Caller traces: Optionally the stack traces when objects are checked out can be recorded. When an object e.g. needs to be reclaimed, the stack trace can be used to identify the leak.

Author:

Patrick Schmidt

Field Summary

Fields

Modifier and Type	Field and Description
protected java.util.logging.Logger	logger The logger for log messages.

Constructor Summary

Constructors

Constructor and Description
GenericObjectPool(ObjectLifeCycle<T,E> objectLifeCycle, ObjectWrapperLifeCycle<T,E> objectWrapperLifeCycle, PoolConfiguration configuration, java.util.logging.Logger logger) Constructs a new GenericObjectPool.

Method Summary

Modifier and Type	Method and Description
void	awaitTermination() Waits and blocks until this pool is terminated.
boolean	awaitTermination(long timeout) Waits for the given amount of milliseconds for the pool to terminate.
void	checkIn(T object) Returns an object to the pool.
void	checkIn(T origObject, boolean indicateError) Besides returning an object to the pool, this method allows the borrower to indicate that the object being checked in is or may be invalid.
T	checkOut() Returns an available object from the object pool.
T	checkOutInterruptibly() This method is equivalent to checkOut() except that the calling thread may be interrupted.
T	checkOutInterruptibly(long timeout) This method is equivalent to checkOut() except that the calling thread may be interrupted and that it only ways for the given amount of time for an object to become available.
protected void	finalize()
void	forceShutdown() Forces a shutdown of this object pool, i.e. no more objects can be checked out.
void	forceShutdown(long delay) Initiates a shutdown of this object pool, i.e. no more objects can be checked out, but objects can still be checked back in.
int	getAvailableObjectCount() Returns the current number of available objects, i.e. objects that are sitting idle in the pool.
int	getCheckedOutObjectCount() Returns the current number of checked out objects.
int	getObjectCount() Returns the current number of pooled objects.
ObjectPoolListener<T>	getObjectPoolListener() Returns the current listener of this pool.
boolean	isShutdown() Returns true if either ObjectPool.shutdown() or ObjectPool.forceShutdown() have been called on this pool.
boolean	isTerminated() Returns true if this pool is completely shut down and has ceased all activities.
void	setObjectPoolListener(ObjectPoolListener<T> objectPoolListener) Registers the given listener with this pool.
void	shutdown() Initiates an orderly shutdown of this object pool, i.e. no more objects can be checked out, but objects can still be checked back in.

Methods inherited from class java.lang.Object

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

Field Detail

logger

protected final java.util.logging.Logger logger

The logger for log messages.

Constructor Detail

GenericObjectPool

public GenericObjectPool(ObjectLifeCycle<T,E> objectLifeCycle,
                         ObjectWrapperLifeCycle<T,E> objectWrapperLifeCycle,
                         PoolConfiguration configuration,
                         java.util.logging.Logger logger)

Constructs a new GenericObjectPool. With the given object life cycle, wrapper life cycle (optional) and configuration.

Parameters:

objectLifeCycle - the object life cycle to use

objectWrapperLifeCycle - the object wrapper life cycle to use (optional)

configuration - the configuration to use

logger - The logger for log messages.

Method Detail

getObjectPoolListener

public ObjectPoolListener<T> getObjectPoolListener()

Returns the current listener of this pool.

Returns:

the current listener of this pool

setObjectPoolListener

public void setObjectPoolListener(ObjectPoolListener<T> objectPoolListener)

Registers the given listener with this pool. There can only be one listener, i.e. any previous listener will be removed. null is allowed.

Parameters:

objectPoolListener - the new listener

getObjectCount

public int getObjectCount()

Returns the current number of pooled objects. This includes available objects as well as checked out objects.

Returns:

the current number of pooled objects

getAvailableObjectCount

public int getAvailableObjectCount()

Returns the current number of available objects, i.e. objects that are sitting idle in the pool.

Returns:

the current number of available objects

getCheckedOutObjectCount

public int getCheckedOutObjectCount()

Returns the current number of checked out objects.

Returns:

the current number of checked out objects

checkOut

public T checkOut()
           throws E extends java.lang.Exception

Returns an available object from the object pool. If all pooled objects are checked out this method will block until one is available.

Specified by:

checkOut in interface ObjectPool<T,E extends java.lang.Exception>

Returns:

an available object from the object pool

Throws:

E - if the pool has to create a new object and this triggers an exception (e.g. passed through exceptions from ObjectLifeCycle.create())

E extends java.lang.Exception

checkOutInterruptibly

public T checkOutInterruptibly()
                        throws E extends java.lang.Exception,
                               java.lang.InterruptedException

This method is equivalent to checkOut() except that the calling thread may be interrupted.

Returns:

an object from the pool (or a wrapper)

Throws:

E - see checkOut()

java.lang.InterruptedException - if the calling thread is interrupted

E extends java.lang.Exception

checkOutInterruptibly

public T checkOutInterruptibly(long timeout)
                        throws E extends java.lang.Exception,
                               java.lang.InterruptedException

This method is equivalent to checkOut() except that the calling thread may be interrupted and that it only ways for the given amount of time for an object to become available.

Parameters:

timeout - the time (in milliseconds) to wait for an object to become available

Returns:

an object from the pool (or a wrapper); or null if the timeout expires

Throws:

E - see checkOut()

java.lang.InterruptedException - if the calling thread is interrupted

E extends java.lang.Exception

checkIn

public void checkIn(T object)
             throws E extends java.lang.Exception

Description copied from interface: ObjectPool

Returns an object to the pool. This method may be called even after the object pool was ordered to shut down, but not once the pool is terminated.

If the returned object is a wrapper for the actual object, the wrapper is invalidated (see ObjectWrapperLifeCycle).

Specified by:

checkIn in interface ObjectPool<T,E extends java.lang.Exception>

Parameters:

object - the object to be returned

Throws:

E - if passivating the object failed (see ObjectLifeCycle.passivate(Object))

E extends java.lang.Exception

checkIn

public void checkIn(T origObject,
                    boolean indicateError)
             throws E extends java.lang.Exception

Besides returning an object to the pool, this method allows the borrower to indicate that the object being checked in is or may be invalid. However, it's up to the pool and its configuration what to do with this information. Other than that, see checkIn(Object).

Parameters:

origObject - the object to be returned

indicateError - this allows the caller to indicate that the object didn't work as expected; this this will cause the pool to validate the object if it wasn't already doing it anyway

Throws:

E - if passivating the object failed (see ObjectLifeCycle.passivate(Object))

java.lang.IllegalArgumentException - if the given object is not managed by this pool

java.lang.IllegalStateException - if the pool is already terminated

E extends java.lang.Exception

awaitTermination

public void awaitTermination()
                      throws java.lang.InterruptedException

Waits and blocks until this pool is terminated.

Throws:

java.lang.InterruptedException - if the current thread is interrupted

awaitTermination

public boolean awaitTermination(long timeout)
                         throws java.lang.InterruptedException

Waits for the given amount of milliseconds for the pool to terminate.

Parameters:

timeout - the time to wait for the termination of the object pool

Returns:

whether the pool was terminated at the time this method returns

Throws:

java.lang.InterruptedException - if the current thread is interrupted

isShutdown

public boolean isShutdown()

Description copied from interface: ObjectPool

Returns true if either ObjectPool.shutdown() or ObjectPool.forceShutdown() have been called on this pool. I.e. it's either completely shut down (i.e. terminated) or still in the process of shutting down.

Specified by:

isShutdown in interface ObjectPool<T,E extends java.lang.Exception>

Returns:

whether the pool is either terminated or still in the process of shutting down

isTerminated

public boolean isTerminated()

Description copied from interface: ObjectPool

Returns true if this pool is completely shut down and has ceased all activities.

Specified by:

isTerminated in interface ObjectPool<T,E extends java.lang.Exception>

Returns:

whether the pool is completely shut down

shutdown

public void shutdown()

Description copied from interface: ObjectPool

Initiates an orderly shutdown of this object pool, i.e. no more objects can be checked out, but objects can still be checked back in. Available objects will be destroyed immediately, checked out objects as soon as they're returned to the pool.

Scheduled operations like the monitoring of expired leases may still continue.

If the pool is already shutting down, this method does not have any additional effects.

Specified by:

shutdown in interface ObjectPool<T,E extends java.lang.Exception>

forceShutdown

public void forceShutdown()

Description copied from interface: ObjectPool

Forces a shutdown of this object pool, i.e. no more objects can be checked out. All objects (available and checked out) will be destroyed immediately and the pool will cease all its activities.

This method may be called even if the pool is already shutting down.

Specified by:

forceShutdown in interface ObjectPool<T,E extends java.lang.Exception>

forceShutdown

public void forceShutdown(long delay)

Initiates a shutdown of this object pool, i.e. no more objects can be checked out, but objects can still be checked back in. Available objects will be destroyed immediately, check out objects as soon as they're returned to the pool. After the specified delay, the pool will be shut down forcefully, i.e. all remaining (checked out) objects will be destroyed and it will cease all its activities. In other words, a forced shut down will be an orderly shutdown until the delay expires.

This method may be called even if the pool is already shutting down. Any previous delay should be reset to the new value.

Parameters:

delay - the delay in milliseconds before the pool will be forcefully shut down

finalize

protected void finalize()
                 throws java.lang.Throwable

Overrides:

finalize in class java.lang.Object

Throws:

java.lang.Throwable