Package de.aristaflow.adept2.util.objectpool.generic

Class GenericObjectPool<T,E extends 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>, AutoCloseable
public class GenericObjectPool<T,E extends Exception> extends 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.

  • Field Details

    • logger

      protected final Logger logger
      The logger for log messages.

    • VALIDATION_INTERVAL

      protected final long VALIDATION_INTERVAL
      The time in milliseconds between validation of objects. This will be ignored in case of indications for an invalid object.

    • executor

      protected final ScheduledThreadPoolExecutor executor
      The executor for the repeatable administrative tasks.

    • availObjectExpirationCheck

      protected final de.aristaflow.adept2.util.objectpool.generic.RepeatableTask availObjectExpirationCheck
      The task for checking the expiration of available objects.

    • leaseExpirationCheck

      protected final de.aristaflow.adept2.util.objectpool.generic.RepeatableTask leaseExpirationCheck
      The task checking for lease expiration, that is, objects that have been borrowed too long.

  • Constructor Details

    • GenericObjectPool

      @Deprecated(since="14.0.0", forRemoval=true) public GenericObjectPool(ObjectLifeCycle<T,E> objectLifeCycle, ObjectWrapperLifeCycle<T,E> objectWrapperLifeCycle, PoolConfiguration configuration, Logger logger)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use GenericObjectPool(String, ObjectLifeCycle, ObjectWrapperLifeCycle, PoolConfiguration, Logger) instead.
      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.

    • GenericObjectPool

      public GenericObjectPool(String name, ObjectLifeCycle<T,E> objectLifeCycle, ObjectWrapperLifeCycle<T,E> objectWrapperLifeCycle, PoolConfiguration configuration, Logger logger)
      Creates a new GenericObjectPool with the designated name (for the thread executing administrative tasks), the designated object life cycle, wrapper life cycle (optional) and configuration.
      Parameters:
      name - The name of this object pool used for the thread executing administrative tasks.
      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 Details

    • 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
      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 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())

    • checkOutInterruptibly

      public T checkOutInterruptibly() throws E, 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()
      InterruptedException - if the calling thread is interrupted

    • checkOutInterruptibly

      public T checkOutInterruptibly(long timeout) throws E, 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()
      InterruptedException - if the calling thread is interrupted

    • checkIn

      public void checkIn(T object) throws E
      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 Exception>
      Parameters:
      object - the object to be returned
      Throws:
      E - if passivating the object failed (see ObjectLifeCycle.passivate(Object))

    • checkIn

      public void checkIn(T origObject, boolean indicateError) throws E
      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))
      IllegalArgumentException - if the given object is not managed by this pool
      IllegalStateException - if the pool is already terminated

    • awaitTermination

      public void awaitTermination() throws InterruptedException
      Waits and blocks until this pool is terminated.
      Throws:
      InterruptedException - if the current thread is interrupted

    • awaitTermination

      public boolean awaitTermination(long timeout) throws 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:
      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 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 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 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 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