de.aristaflow.adept2.util.objectpool

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

Type Parameters:

T - the type of object managed by this pool

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

All Known Implementing Classes:

GenericObjectPool

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

This is the basic interface for an object pool, a facility to support easy reuse of objects and resources; especially those that are expensive to create and/or have limited availability.

This interface only defines a few basic methods required to utilize the pool. How resources / objects are managed internally is completely up to implementations.

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

Most of the declared runtime exceptions are just hints to implementors. If the pool doesn't e.g. track the objects it created, it obviously can't confirm if a checked in object is really one of them. In this case it also can't destroy any checked out objects during a forced shut down, which makes a regular and a forced shutdown basically the same.

Author:

Patrick Schmidt

Method Summary

Modifier and Type	Method and Description
void	checkIn(T object) Returns an object to the pool.
T	checkOut() Retrieves an object from the pool or throws a NoSuchElementException if the pool can't (or just won't for some reason) currently provide an object and does not block until one becomes available.
void	forceShutdown() Forces a shutdown of this object pool, i.e. no more objects can be checked out.
boolean	isShutdown() Returns true if either shutdown() or forceShutdown() have been called on this pool.
boolean	isTerminated() Returns true if this pool is completely shut down and has ceased all activities.
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.

Method Detail

checkOut

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

Retrieves an object from the pool or throws a NoSuchElementException if the pool can't (or just won't for some reason) currently provide an object and does not block until one becomes available. This method must not be called after the object pool was ordered to shut down.

The returned object may be a wrapper of the actual object (see ObjectWrapperLifeCycle).

Returns:

an object from the pool (or a wrapper)

Throws:

E - if creating an object failed (see ObjectLifeCycle.create())

java.lang.IllegalStateException - if the pool is already shut(ting) down

java.util.NoSuchElementException - if the pool can't (or just won't for some reason) provide an object and does not block until one is available

E extends java.lang.Exception

checkIn

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

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).

Parameters:

object - the object to be returned

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

isShutdown

boolean isShutdown()

Returns true if either shutdown() or 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.

Returns:

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

isTerminated

boolean isTerminated()

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

Returns:

whether the pool is completely shut down

shutdown

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. 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.

forceShutdown

void forceShutdown()

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.