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

Class GenericObjectPool<T,​E extends Exception>

  • 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 Detail

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

      • 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 Detail

      • 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 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 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 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 Exception

      • checkOutInterruptibly

        public T checkOutInterruptibly​(long timeout)
                        throws E extends Exception,
                               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
        E extends Exception

      • checkIn

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

      • 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