Module com.github.robtimus.pool

Package com.github.robtimus.pool

Class Pool<T extends PoolableObject<X>,X extends Exception>

java.lang.Object

com.github.robtimus.pool.Pool<T,X>

Type Parameters:

T - The type of objects in the pool.

X - The type of exception that operations on objects in the pool can throw.

public final class Pool<T extends PoolableObject<X>,X extends Exception>
extends Object

A simple object pool implementation.

Instances of this class are thread-safe.

Author:

Rob Spoor

Constructor Summary

Constructors

Constructor	Description
Pool(PoolConfig config, PoolableObjectFactory<T,X> factory, PoolLogger logger)	Creates a new pool.

Method Summary

Modifier and Type	Method	Description
T	acquire()	Acquires an object.
T	acquire(long maxWaitTime, TimeUnit timeUnit)	Acquires an object.
<E extends Exception> T	acquire(long maxWaitTime, TimeUnit timeUnit, Supplier<E> errorSupplier)	Acquires an object.
T	acquire(Duration maxWaitTime)	Acquires an object.
<E extends Exception> T	acquire(Duration maxWaitTime, Supplier<E> errorSupplier)	Acquires an object.
<E extends Exception> T	acquire(Supplier<E> errorSupplier)	Acquires an object.
Optional<T>	acquireNow()	Acquires an object if possible.
T	acquireOrCreate()	Acquires an object if possible.
void	forAllIdleObjects(PoolableObjectConsumer<T,X> action)	Runs an operation on all idle objects.
boolean	isActive()	Returns whether or not this pool is active.
void	shutdown()	Shuts down this pool.
static <T extends PoolableObject<None>> Pool<T,None>	throwingNone(PoolConfig config, Supplier<T> supplier, PoolLogger logger)	Creates a new pool that throws no exceptions.

Methods inherited from class java.lang.Object

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

Constructor Detail

Pool

public Pool(PoolConfig config,
            PoolableObjectFactory<T,X> factory,
            PoolLogger logger)
     throws X extends Exception

Creates a new pool.

Parameters:

config - The configuration to use.

factory - The object factory to use.

logger - The logger to use to log events triggered by the pool or pooled objects.

Throws:

NullPointerException - If the given configuration, factory or logger is null.

X - If the given config requests a positive initial size, and one or more objects could not be created.

X extends Exception

Method Detail

acquire

public T acquire()
          throws X extends Exception,
                 InterruptedException

Acquires an object. This method will block until an object is available or the maximum wait time, as defined in the configuration used to create this pool, expires. If the configured maximum wait time is negative, this method will block until an object is available.

Returns:

The acquired object.

Throws:

X - If an error occurs while acquiring an object.

NoSuchElementException - If the maximum wait time expires before an object could be acquired.

InterruptedException - If the current thread is interrupted while acquiring an object.

IllegalStateException - If this pool has shut down.

X extends Exception

acquire

public T acquire(Duration maxWaitTime)
          throws X extends Exception,
                 InterruptedException

Acquires an object. This method will block until an object is available or the maximum wait time expires.

Parameters:

maxWaitTime - The maximum wait time. If null or negative, this method will block until an object is available.

Returns:

The acquired object.

Throws:

X - If an error occurs while acquiring an object.

NoSuchElementException - If the maximum wait time expires before an object could be acquired.

InterruptedException - If the current thread is interrupted while acquiring an object.

IllegalStateException - If this pool has shut down.

X extends Exception

acquire

public T acquire(long maxWaitTime,
                 TimeUnit timeUnit)
          throws X extends Exception,
                 InterruptedException

Acquires an object. This method will block until an object is available or the maximum wait time expires.

Parameters:

maxWaitTime - The maximum wait time. If negative, this method will block until an object is available.

timeUnit - The time unit for the maximum wait time.

Returns:

The acquired object.

Throws:

NullPointerException - If the given time unit is null.

X - If an error occurs while acquiring an object.

NoSuchElementException - If the maximum wait time expires before an object could be acquired.

InterruptedException - If the current thread is interrupted while acquiring an object.

IllegalStateException - If this pool has shut down.

X extends Exception

acquire

public <E extends Exception> T acquire(Supplier<E> errorSupplier)
                                throws X extends Exception,
                                       E extends Exception,
                                       InterruptedException

Acquires an object. This method will block until an object is available or the maximum wait time, as defined in the configuration used to create this pool, expires. If the configured maximum wait time is negative, this method will block until an object is available.

Type Parameters:

E - The type of exception to throw if the maximum wait time expires.

Parameters:

errorSupplier - A supplier for the exception to throw if the maximum wait time expires.

Returns:

The acquired object.

Throws:

NullPointerException - If the given supplier is null and the maximum wait time expires.

X - If an error occurs while acquiring an object.

E - If the maximum wait time expires before an object could be acquired.

InterruptedException - If the current thread is interrupted while acquiring an object.

IllegalStateException - If this pool has shut down.

X extends Exception

acquire

public <E extends Exception> T acquire(Duration maxWaitTime,
                                       Supplier<E> errorSupplier)
                                throws X extends Exception,
                                       E extends Exception,
                                       InterruptedException

Acquires an object. This method will block until an object is available or the maximum wait time expires.

Type Parameters:

E - The type of exception to throw if the maximum wait time expires.

Parameters:

maxWaitTime - The maximum wait time. If null or negative, this method will block until an object is available.

errorSupplier - A supplier for the exception to throw if the maximum wait time expires.

Returns:

The acquired object.

Throws:

NullPointerException - If the given supplier is null and the maximum wait time expires.

X - If an error occurs while acquiring an object.

E - If the maximum wait time expires before an object could be acquired.

InterruptedException - If the current thread is interrupted while acquiring an object.

IllegalStateException - If this pool has shut down.

X extends Exception

acquire

public <E extends Exception> T acquire(long maxWaitTime,
                                       TimeUnit timeUnit,
                                       Supplier<E> errorSupplier)
                                throws X extends Exception,
                                       E extends Exception,
                                       InterruptedException

Acquires an object. This method will block until an object is available or the maximum wait time expires.

Type Parameters:

E - The type of exception to throw if the maximum wait time expires.

Parameters:

maxWaitTime - The maximum wait time. If negative, this method will block until an object is available.

timeUnit - The time unit for the maximum wait time.

errorSupplier - A supplier for the exception to throw if the maximum wait time expires.

Returns:

The acquired object.

Throws:

NullPointerException - If the given time unit is null. or if the given supplier is null and the maximum wait time expires.

X - If an error occurs while acquiring an object.

E - If the maximum wait time expires before an object could be acquired.

InterruptedException - If the current thread is interrupted while acquiring an object.

IllegalStateException - If this pool has shut down.

X extends Exception

acquireNow

public Optional<T> acquireNow()
                       throws X extends Exception

Acquires an object if possible. This method will not block if no objects are available.

Returns:

An Optional describing the acquired object, or Optional.empty() if no object was available.

Throws:

X - If an error occurs while acquiring an object.

IllegalStateException - If this pool has shut down.

X extends Exception

acquireOrCreate

public T acquireOrCreate()
                  throws X extends Exception

Acquires an object if possible. This method will not block if no objects are available; instead, a new object will be created that will not be returned to the pool. This can be used in cases where an object is necessary right now, and blocking could lead to deadlock or similar issues.

Returns:

The acquired or created object.

Throws:

X - If an error occurs while acquiring an object.

IllegalStateException - If this pool has shut down.

X extends Exception

forAllIdleObjects

public void forAllIdleObjects(PoolableObjectConsumer<T,X> action)
                       throws X extends Exception

Runs an operation on all idle objects. These will be acquired in bulk, after which the operation is run on them sequentially. Afterwards, each object will be returned to the pool.

Any object that is no longer valid or has been idle too long will be removed from the pool before running the operation on idle objects. As a result, all arguments to the operation will be valid.

Parameters:

action - The operation to run.

Throws:

X - If an error occurs while running the operation on any of the idle objects.

NullPointerException - If the given operation is null.

X extends Exception

isActive

public boolean isActive()

Returns whether or not this pool is active.

Returns:

true if this pool is active, or false if it has shut down.

shutdown

public void shutdown()
              throws X extends Exception

Shuts down this pool. For all idle object the resources are released, and it will no longer be possible to acquire new objects. Any already acquired objects will remain valid until they are returned to the pool.

Throws:

X - If an error occurs while releasing resources for any of the idle objects.

X extends Exception

throwingNone

public static <T extends PoolableObject<None>> Pool<T,None> throwingNone(PoolConfig config,
                                                                               Supplier<T> supplier,
                                                                               PoolLogger logger)

Creates a new pool that throws no exceptions.

Type Parameters:

T - The type of objects in the pool.

Parameters:

config - The configuration to use.

supplier - A supplier to serve as object factory.

logger - The logger to use to log events triggered by the pool or pooled objects.

Returns:

The created pool.

Throws:

NullPointerException - If the given configuration, supplier or logger is null.