Package org.apache.commons.pool2.impl

Class BaseGenericObjectPool<T>

  • Type Parameters:
    T - Type of element pooled in this pool.
    All Implemented Interfaces:
    java.lang.AutoCloseable
    Direct Known Subclasses:
    GenericKeyedObjectPool, GenericObjectPool
    public abstract class BaseGenericObjectPool<T>
extends BaseObject
implements java.lang.AutoCloseable
    Base class that provides common functionality for GenericObjectPool and GenericKeyedObjectPool. The primary reason this class exists is reduce code duplication between the two pool implementations.

    Concrete implementations of this class are expected to be thread-safe.

    Since:
    2.0

    • Field Detail

      • MEAN_TIMING_STATS_CACHE_SIZE

        public static final int MEAN_TIMING_STATS_CACHE_SIZE
        The size of the caches used to store historical data for some attributes so that rolling means may be calculated.
        See Also:
        Constant Field Values

      • EVICTION_POLICY_TYPE_NAME

        private static final java.lang.String EVICTION_POLICY_TYPE_NAME

      • DEFAULT_REMOVE_ABANDONED_TIMEOUT

        private static final java.time.Duration DEFAULT_REMOVE_ABANDONED_TIMEOUT

      • maxTotal

        private volatile int maxTotal

      • blockWhenExhausted

        private volatile boolean blockWhenExhausted

      • maxWaitDuration

        private volatile java.time.Duration maxWaitDuration

      • lifo

        private volatile boolean lifo

      • fairness

        private final boolean fairness

      • testOnCreate

        private volatile boolean testOnCreate

      • testOnBorrow

        private volatile boolean testOnBorrow

      • testOnReturn

        private volatile boolean testOnReturn

      • testWhileIdle

        private volatile boolean testWhileIdle

      • durationBetweenEvictionRuns

        private volatile java.time.Duration durationBetweenEvictionRuns

      • numTestsPerEvictionRun

        private volatile int numTestsPerEvictionRun

      • minEvictableIdleDuration

        private volatile java.time.Duration minEvictableIdleDuration

      • softMinEvictableIdleDuration

        private volatile java.time.Duration softMinEvictableIdleDuration

      • evictorShutdownTimeoutDuration

        private volatile java.time.Duration evictorShutdownTimeoutDuration

      • closeLock

        final java.lang.Object closeLock

      • closed

        volatile boolean closed

      • evictionLock

        final java.lang.Object evictionLock

      • factoryClassLoader

        private final java.lang.ref.WeakReference<java.lang.ClassLoader> factoryClassLoader
        Class loader for evictor thread to use since, in a JavaEE or similar environment, the context class loader for the evictor thread may not have visibility of the correct factory. See POOL-161. Uses a weak reference to avoid potential memory leaks if the Pool is discarded rather than closed.

      • objectName

        private final javax.management.ObjectName objectName

      • creationStackTrace

        private final java.lang.String creationStackTrace

      • borrowedCount

        private final java.util.concurrent.atomic.AtomicLong borrowedCount

      • returnedCount

        private final java.util.concurrent.atomic.AtomicLong returnedCount

      • createdCount

        final java.util.concurrent.atomic.AtomicLong createdCount

      • destroyedCount

        final java.util.concurrent.atomic.AtomicLong destroyedCount

      • destroyedByEvictorCount

        final java.util.concurrent.atomic.AtomicLong destroyedByEvictorCount

      • destroyedByBorrowValidationCount

        final java.util.concurrent.atomic.AtomicLong destroyedByBorrowValidationCount

      • maxBorrowWaitDuration

        private final java.util.concurrent.atomic.AtomicReference<java.time.Duration> maxBorrowWaitDuration

      • messageStatistics

        private volatile boolean messageStatistics

      • collectDetailedStatistics

        private volatile boolean collectDetailedStatistics

      • abandonedConfig

        protected volatile AbandonedConfig abandonedConfig
        Additional configuration properties for abandoned object tracking.

    • Constructor Detail

      • BaseGenericObjectPool

        public BaseGenericObjectPool​(BaseObjectPoolConfig<T> config,
                             java.lang.String jmxNameBase,
                             java.lang.String jmxNamePrefix)
        Handles JMX registration (if required) and the initialization required for monitoring.
        Parameters:
        config - Pool configuration
        jmxNameBase - The default base JMX name for the new pool unless overridden by the config
        jmxNamePrefix - Prefix to be used for JMX name for the new pool

    • Method Detail

      • appendStats

        java.lang.String appendStats​(java.lang.String string)
        Appends statistics if enabled.

        Statistics may not accurately reflect snapshot state at the time of the exception because we do not want to lock the pool when gathering this information.

        Parameters:
        string - The root string.
        Returns:
        The root string plus statistics.

      • assertOpen

        final void assertOpen()
               throws java.lang.IllegalStateException
        Verifies that the pool is open.
        Throws:
        java.lang.IllegalStateException - if the pool is closed.

      • close

        public abstract void close()
        Closes the pool, destroys the remaining idle objects and, if registered in JMX, deregisters it.
        Specified by:
        close in interface java.lang.AutoCloseable

      • createRemoveList

        java.util.ArrayList<PooledObject<T>> createRemoveList​(AbandonedConfig abandonedConfig,
                                                      java.util.Map<BaseGenericObjectPool.IdentityWrapper<T>,​PooledObject<T>> allObjects)
        Creates a list of pooled objects to remove based on their state.
        Parameters:
        abandonedConfig - The abandoned configuration.
        allObjects - PooledObject instances to consider.
        Returns:
        a list of pooled objects to remove based on their state.

      • durationSince

        final java.time.Duration durationSince​(java.time.Instant startInstant)
        Returns the duration since the given start time.
        Parameters:
        startInstant - the start time
        Returns:
        the duration since the given start time

      • ensureMinIdle

        abstract void ensureMinIdle()
                     throws java.lang.Exception
        Tries to ensure that the configured minimum number of idle instances are available in the pool.
        Throws:
        java.lang.Exception - if an error occurs creating idle instances

      • evict

        public abstract void evict()
                    throws java.lang.Exception
        Perform numTests idle object eviction tests, evicting examined objects that meet the criteria for eviction. If testWhileIdle is true, examined objects are validated when visited (and removed if invalid); otherwise only objects that have been idle for more than minEvicableIdleTimeMillis are removed.
        Throws:
        java.lang.Exception - when there is a problem evicting idle objects.

      • getBlockWhenExhausted

        public final boolean getBlockWhenExhausted()
        Gets whether to block when the borrowObject() method is invoked when the pool is exhausted (the maximum number of "active" objects has been reached).
        Returns:
        true if borrowObject() should block when the pool is exhausted
        See Also:
        setBlockWhenExhausted(boolean)

      • getBorrowedCount

        public final long getBorrowedCount()
        Gets the total number of objects successfully borrowed from this pool over the lifetime of the pool.
        Returns:
        the borrowed object count

      • getCollectDetailedStatistics

        public boolean getCollectDetailedStatistics()
        Gets whether detailed timing statistics collection is enabled. When false, the pool will not collect detailed timing statistics for mean active time, mean idle time, and mean borrow wait time, improving performance under high load.
        Returns:
        true if detailed statistics collection is enabled, false if disabled for improved performance.
        Since:
        2.13.0

      • getCreatedCount

        public final long getCreatedCount()
        Gets the total number of objects created for this pool over the lifetime of the pool.
        Returns:
        the created object count

      • getCreationStackTrace

        public final java.lang.String getCreationStackTrace()
        Gets the stack trace for the call that created this pool. JMX registration may trigger a memory leak so it is important that pools are deregistered when no longer used by calling the close() method. This method is provided to assist with identifying code that creates but does not close it thereby creating a memory leak.
        Returns:
        pool creation stack trace

      • getDestroyedByBorrowValidationCount

        public final long getDestroyedByBorrowValidationCount()
        Gets the total number of objects destroyed by this pool as a result of failing validation during borrowObject() over the lifetime of the pool.
        Returns:
        validation destroyed object count

      • getDestroyedByEvictorCount

        public final long getDestroyedByEvictorCount()
        Gets the total number of objects destroyed by the evictor associated with this pool over the lifetime of the pool.
        Returns:
        the evictor destroyed object count

      • getDestroyedCount

        public final long getDestroyedCount()
        Gets the total number of objects destroyed by this pool over the lifetime of the pool.
        Returns:
        the destroyed object count

      • getDurationBetweenEvictionRuns

        public final java.time.Duration getDurationBetweenEvictionRuns()
        Gets the duration to sleep between runs of the idle object evictor thread. When non-positive, no idle object evictor thread will be run.
        Returns:
        number of milliseconds to sleep between evictor runs
        Since:
        2.11.0
        See Also:
        setTimeBetweenEvictionRuns(java.time.Duration)

      • getEvictionPolicy

        public EvictionPolicy<T> getEvictionPolicy()
        Gets the EvictionPolicy defined for this pool.
        Returns:
        the eviction policy
        Since:
        2.4, 2.6.0 Changed access from protected to public.

      • getEvictorShutdownTimeout

        @Deprecated
public final java.time.Duration getEvictorShutdownTimeout()
        Deprecated.
        Use getEvictorShutdownTimeoutDuration().
        Gets the timeout that will be used when waiting for the Evictor to shutdown if this pool is closed and it is the only pool still using the the value for the Evictor.
        Returns:
        The timeout that will be used while waiting for the Evictor to shut down.
        Since:
        2.10.0

      • getEvictorShutdownTimeoutDuration

        public final java.time.Duration getEvictorShutdownTimeoutDuration()
        Gets the timeout that will be used when waiting for the Evictor to shutdown if this pool is closed and it is the only pool still using the the value for the Evictor.
        Returns:
        The timeout that will be used while waiting for the Evictor to shut down.
        Since:
        2.11.0

      • getEvictorShutdownTimeoutMillis

        @Deprecated
public final long getEvictorShutdownTimeoutMillis()
        Deprecated.
        Use getEvictorShutdownTimeoutDuration().
        Gets the timeout that will be used when waiting for the Evictor to shutdown if this pool is closed and it is the only pool still using the the value for the Evictor.
        Returns:
        The timeout in milliseconds that will be used while waiting for the Evictor to shut down.

      • getFairness

        public final boolean getFairness()
        Gets whether or not the pool serves threads waiting to borrow objects fairly. True means that waiting threads are served as if waiting in a FIFO queue.
        Returns:
        true if waiting threads are to be served by the pool in arrival order

      • getJmxName

        public final javax.management.ObjectName getJmxName()
        Gets the name under which the pool has been registered with the platform MBean server or null if the pool has not been registered.
        Returns:
        the JMX name

      • getLifo

        public final boolean getLifo()
        Gets whether the pool has LIFO (last in, first out) behavior with respect to idle objects - always returning the most recently used object from the pool, or as a FIFO (first in, first out) queue, where the pool always returns the oldest object in the idle object pool.
        Returns:
        true if the pool is configured with LIFO behavior or false if the pool is configured with FIFO behavior
        See Also:
        setLifo(boolean)

      • getLogAbandoned

        public boolean getLogAbandoned()
        Gets whether this pool identifies and logs any abandoned objects.
        Returns:
        true if abandoned object removal is configured for this pool and removal events are to be logged otherwise false
        Since:
        2.11.0
        See Also:
        AbandonedConfig.getLogAbandoned()

      • getMaxBorrowWaitDuration

        public final java.time.Duration getMaxBorrowWaitDuration()
        Gets the maximum time a thread has waited to borrow objects from the pool.
        Returns:
        maximum wait time in milliseconds since the pool was created
        Since:
        2.12.0

      • getMaxBorrowWaitTimeMillis

        @Deprecated
public final long getMaxBorrowWaitTimeMillis()
        Deprecated.
        Use getMaxBorrowWaitDuration().
        Gets the maximum time a thread has waited to borrow objects from the pool.
        Returns:
        maximum wait time in milliseconds since the pool was created

      • getMaxTotal

        public final int getMaxTotal()
        Gets the maximum number of objects that can be allocated by the pool (checked out to clients, or idle awaiting checkout) at a given time. When negative, there is no limit to the number of objects that can be managed by the pool at one time.
        Returns:
        the cap on the total number of object instances managed by the pool.
        See Also:
        setMaxTotal(int)

      • getMaxWaitDuration

        public final java.time.Duration getMaxWaitDuration()
        Gets the maximum duration the borrowObject() method should block before throwing an exception when the pool is exhausted and getBlockWhenExhausted() is true. When less than 0, the borrowObject() method may block indefinitely.
        Returns:
        the maximum number of milliseconds borrowObject() will block.
        Since:
        2.11.0
        See Also:
        setMaxWait(java.time.Duration), setBlockWhenExhausted(boolean)

      • getMeanActiveDuration

        public final java.time.Duration getMeanActiveDuration()
        Gets the mean time objects are active for based on the last MEAN_TIMING_STATS_CACHE_SIZE objects returned to the pool.
        Returns:
        mean time an object has been checked out from the pool among recently returned objects.
        Since:
        2.12.0

      • getMeanActiveTimeMillis

        @Deprecated
public final long getMeanActiveTimeMillis()
        Deprecated.
        Use getMeanActiveDuration().
        Gets the mean time objects are active for based on the last MEAN_TIMING_STATS_CACHE_SIZE objects returned to the pool.
        Returns:
        mean time an object has been checked out from the pool among recently returned objects.

      • getMeanBorrowWaitDuration

        public final java.time.Duration getMeanBorrowWaitDuration()
        Gets the mean time threads wait to borrow an object based on the last MEAN_TIMING_STATS_CACHE_SIZE objects borrowed from the pool.
        Returns:
        mean time in milliseconds that a recently served thread has had to wait to borrow an object from the pool.
        Since:
        2.12.0

      • getMeanBorrowWaitTimeMillis

        @Deprecated
public final long getMeanBorrowWaitTimeMillis()
        Deprecated.
        Use getMeanBorrowWaitDuration().
        Gets the mean time threads wait to borrow an object based on the last MEAN_TIMING_STATS_CACHE_SIZE objects borrowed from the pool.
        Returns:
        mean time in milliseconds that a recently served thread has had to wait to borrow an object from the pool.

      • getMeanIdleDuration

        public final java.time.Duration getMeanIdleDuration()
        Gets the mean time objects are idle for based on the last MEAN_TIMING_STATS_CACHE_SIZE objects borrowed from the pool.
        Returns:
        mean time an object has been idle in the pool among recently borrowed objects.
        Since:
        2.12.0

      • getMeanIdleTimeMillis

        @Deprecated
public final long getMeanIdleTimeMillis()
        Deprecated.
        Use getMeanIdleDuration().
        Gets the mean time objects are idle for based on the last MEAN_TIMING_STATS_CACHE_SIZE objects borrowed from the pool.
        Returns:
        mean time an object has been idle in the pool among recently borrowed objects.

      • getMessageStatistics

        public boolean getMessageStatistics()
        Gets whether to include statistics in exception messages.

        Statistics may not accurately reflect snapshot state at the time of the exception because we do not want to lock the pool when gathering this information.

        Returns:
        whether to include statistics in exception messages.
        Since:
        2.11.0

      • getMinEvictableIdleDuration

        public final java.time.Duration getMinEvictableIdleDuration()
        Gets the minimum amount of time an object may sit idle in the pool before it is eligible for eviction by the idle object evictor (if any - see setDurationBetweenEvictionRuns(Duration)). When non-positive, no objects will be evicted from the pool due to idle time alone.
        Returns:
        minimum amount of time an object may sit idle in the pool before it is eligible for eviction
        Since:
        2.11.0
        See Also:
        setMinEvictableIdleTimeMillis(long), setTimeBetweenEvictionRunsMillis(long)

      • getNumIdle

        public abstract int getNumIdle()
        Gets the number of instances currently idle in this pool.
        Returns:
        count of instances available for checkout from the pool

      • getNumTestsPerEvictionRun

        public final int getNumTestsPerEvictionRun()
        Gets the maximum number of objects to examine during each run (if any) of the idle object evictor thread. When positive, the number of tests performed for a run will be the minimum of the configured value and the number of idle instances in the pool. When negative, the number of tests performed will be ceil(getNumIdle()/ abs(getNumTestsPerEvictionRun())) which means that when the value is -n roughly one nth of the idle objects will be tested per run.
        Returns:
        max number of objects to examine during each evictor run
        See Also:
        setNumTestsPerEvictionRun(int), setTimeBetweenEvictionRunsMillis(long)

      • getRemoveAbandonedOnBorrow

        public boolean getRemoveAbandonedOnBorrow()
        Gets whether a check is made for abandoned objects when an object is borrowed from this pool.
        Returns:
        true if abandoned object removal is configured to be activated by borrowObject otherwise false
        Since:
        2.11.0
        See Also:
        AbandonedConfig.getRemoveAbandonedOnBorrow()

      • getRemoveAbandonedOnMaintenance

        public boolean getRemoveAbandonedOnMaintenance()
        Gets whether a check is made for abandoned objects when the evictor runs.
        Returns:
        true if abandoned object removal is configured to be activated when the evictor runs otherwise false
        Since:
        2.11.0
        See Also:
        AbandonedConfig.getRemoveAbandonedOnMaintenance()

      • getRemoveAbandonedTimeoutDuration

        public java.time.Duration getRemoveAbandonedTimeoutDuration()
        Gets the timeout before which an object will be considered to be abandoned by this pool.
        Returns:
        The abandoned object timeout in seconds if abandoned object removal is configured for this pool; Integer.MAX_VALUE otherwise.
        Since:
        2.11.0
        See Also:
        AbandonedConfig.getRemoveAbandonedTimeoutDuration()

      • getReturnedCount

        public final long getReturnedCount()
        Gets the total number of objects returned to this pool over the lifetime of the pool. This excludes attempts to return the same object multiple times.
        Returns:
        the returned object count

      • getStackTrace

        private java.lang.String getStackTrace​(java.lang.Exception e)
        Gets the stack trace of an exception as a string.
        Parameters:
        e - exception to trace
        Returns:
        exception stack trace as a string

      • getStatsString

        java.lang.String getStatsString()
        Gets a statistics string.
        Returns:
        a statistics string.

      • getSwallowedExceptionListener

        public final SwallowedExceptionListener getSwallowedExceptionListener()
        Gets the listener used (if any) to receive notifications of exceptions unavoidably swallowed by the pool.
        Returns:
        The listener or null for no listener

      • getTestOnBorrow

        public final boolean getTestOnBorrow()
        Gets whether objects borrowed from the pool will be validated before being returned from the borrowObject() method. Validation is performed by the validateObject() method of the factory associated with the pool. If the object fails to validate, it will be removed from the pool and destroyed, and a new attempt will be made to borrow an object from the pool.
        Returns:
        true if objects are validated before being returned from the borrowObject() method
        See Also:
        setTestOnBorrow(boolean)

      • getTestOnCreate

        public final boolean getTestOnCreate()
        Gets whether objects created for the pool will be validated before being returned from the borrowObject() method. Validation is performed by the validateObject() method of the factory associated with the pool. If the object fails to validate, then borrowObject() will fail.
        Returns:
        true if newly created objects are validated before being returned from the borrowObject() method
        Since:
        2.2
        See Also:
        setTestOnCreate(boolean)

      • getTestOnReturn

        public final boolean getTestOnReturn()
        Gets whether objects borrowed from the pool will be validated when they are returned to the pool via the returnObject() method. Validation is performed by the validateObject() method of the factory associated with the pool. Returning objects that fail validation are destroyed rather then being returned the pool.
        Returns:
        true if objects are validated on return to the pool via the returnObject() method
        See Also:
        setTestOnReturn(boolean)

      • getTestWhileIdle

        public final boolean getTestWhileIdle()
        Gets whether objects sitting idle in the pool will be validated by the idle object evictor (if any - see setDurationBetweenEvictionRuns(Duration)). Validation is performed by the validateObject() method of the factory associated with the pool. If the object fails to validate, it will be removed from the pool and destroyed.
        Returns:
        true if objects will be validated by the evictor
        See Also:
        setTestWhileIdle(boolean), setTimeBetweenEvictionRunsMillis(long)

      • getTimeBetweenEvictionRuns

        @Deprecated
public final java.time.Duration getTimeBetweenEvictionRuns()
        Deprecated.
        getDurationBetweenEvictionRuns().
        Gets the duration to sleep between runs of the idle object evictor thread. When non-positive, no idle object evictor thread will be run.
        Returns:
        number of milliseconds to sleep between evictor runs
        Since:
        2.10.0
        See Also:
        setTimeBetweenEvictionRuns(java.time.Duration)

      • getTimeBetweenEvictionRunsMillis

        @Deprecated
public final long getTimeBetweenEvictionRunsMillis()
        Deprecated.
        Use getDurationBetweenEvictionRuns().
        Gets the number of milliseconds to sleep between runs of the idle object evictor thread. When non-positive, no idle object evictor thread will be run.
        Returns:
        number of milliseconds to sleep between evictor runs
        See Also:
        setTimeBetweenEvictionRunsMillis(long)

      • isAbandonedConfig

        public boolean isAbandonedConfig()
        Tests whether or not abandoned object removal is configured for this pool.
        Returns:
        true if this pool is configured to detect and remove abandoned objects
        Since:
        2.11.0

      • isClosed

        public final boolean isClosed()
        Tests whether this pool instance is closed.
        Returns:
        true when this pool is closed.

      • jmxRegister

        private javax.management.ObjectName jmxRegister​(BaseObjectPoolConfig<T> config,
                                                java.lang.String jmxNameBase,
                                                java.lang.String jmxNamePrefix)
        Registers the pool with the platform MBean server. The registered name will be jmxNameBase + jmxNamePrefix + i where i is the least integer greater than or equal to 1 such that the name is not already registered. Swallows MBeanRegistrationException, NotCompliantMBeanException returning null.
        Parameters:
        config - Pool configuration
        jmxNameBase - default base JMX name for this pool
        jmxNamePrefix - name prefix
        Returns:
        registered ObjectName, null if registration fails

      • jmxUnregister

        final void jmxUnregister()
        Unregisters this pool's MBean.

      • markReturningState

        protected void markReturningState​(PooledObject<T> pooledObject)
        Marks the object as returning to the pool.
        Parameters:
        pooledObject - instance to return to the keyed pool

      • setAbandonedConfig

        public void setAbandonedConfig​(AbandonedConfig abandonedConfig)
        Sets the abandoned object removal configuration.
        Parameters:
        abandonedConfig - the new configuration to use. This is used by value.
        Since:
        2.11.0
        See Also:
        AbandonedConfig

      • setBlockWhenExhausted

        public final void setBlockWhenExhausted​(boolean blockWhenExhausted)
        Sets whether to block when the borrowObject() method is invoked when the pool is exhausted (the maximum number of "active" objects has been reached).
        Parameters:
        blockWhenExhausted - true if borrowObject() should block when the pool is exhausted
        See Also:
        getBlockWhenExhausted()

      • setCollectDetailedStatistics

        public void setCollectDetailedStatistics​(boolean collectDetailedStatistics)
        Sets whether detailed timing statistics collection is enabled. When false, the pool will not collect detailed timing statistics, improving performance under high load at the cost of reduced monitoring capabilities.

        This setting affects data collection for mean active time, mean idle time, and mean borrow wait time.

        Parameters:
        collectDetailedStatistics - whether to collect detailed statistics.
        Since:
        2.13.0

      • setConfig

        protected void setConfig​(BaseObjectPoolConfig<T> config)
        Sets the receiver with the given configuration.
        Parameters:
        config - Initialization source.

      • setDurationBetweenEvictionRuns

        public final void setDurationBetweenEvictionRuns​(java.time.Duration timeBetweenEvictionRuns)
        Sets the number of milliseconds to sleep between runs of the idle object evictor thread.
        • When positive, the idle object evictor thread starts.
        • When null or non-positive, no idle object evictor thread runs.
        Parameters:
        timeBetweenEvictionRuns - duration to sleep between evictor runs
        Since:
        2.12.0
        See Also:
        getDurationBetweenEvictionRuns()

      • setEvictionPolicy

        public void setEvictionPolicy​(EvictionPolicy<T> evictionPolicy)
        Sets the eviction policy for this pool.
        Parameters:
        evictionPolicy - the eviction policy for this pool.
        Since:
        2.6.0

      • setEvictionPolicy

        private void setEvictionPolicy​(java.lang.String className,
                               java.lang.ClassLoader classLoader)
                        throws java.lang.ClassNotFoundException,
                               java.lang.InstantiationException,
                               java.lang.IllegalAccessException,
                               java.lang.reflect.InvocationTargetException,
                               java.lang.NoSuchMethodException
        Sets the eviction policy.
        Parameters:
        className - Eviction policy class name.
        classLoader - Load the class from this class loader.
        Throws:
        java.lang.LinkageError - if the linkage fails
        java.lang.ExceptionInInitializerError - if the initialization provoked by this method fails
        java.lang.ClassNotFoundException - if the class cannot be located by the specified class loader
        java.lang.IllegalAccessException - if this Constructor object is enforcing Java language access control and the underlying constructor is inaccessible.
        java.lang.IllegalArgumentException - if the number of actual and formal parameters differ; if an unwrapping conversion for primitive arguments fails; or if, after possible unwrapping, a parameter value cannot be converted to the corresponding formal parameter type by a method invocation conversion; if this constructor pertains to an enum type.
        java.lang.InstantiationException - if the class that declares the underlying constructor represents an abstract class.
        java.lang.reflect.InvocationTargetException - if the underlying constructor throws an exception.
        java.lang.ExceptionInInitializerError - if the initialization provoked by this method fails.
        java.lang.NoSuchMethodException - if a matching method is not found.
        java.lang.SecurityException - If a security manage is present and the caller's class loader is not the same as or an ancestor of the class loader for the current class and invocation of s.checkPackageAccess() denies access to the package of this class.

      • setEvictionPolicyClassName

        public final void setEvictionPolicyClassName​(java.lang.String evictionPolicyClassName)
        Sets the name of the EvictionPolicy implementation that is used by this pool. The Pool will attempt to load the class using the thread context class loader. If that fails, the use the class loader for the EvictionPolicy interface.
        Parameters:
        evictionPolicyClassName - the fully qualified class name of the new eviction policy
        Since:
        2.6.0 If loading the class using the thread context class loader fails, use the class loader for the EvictionPolicy interface.
        See Also:
        getEvictionPolicyClassName()

      • setEvictionPolicyClassName

        public final void setEvictionPolicyClassName​(java.lang.String evictionPolicyClassName,
                                             java.lang.ClassLoader classLoader)
        Sets the name of the EvictionPolicy implementation that is used by this pool. The Pool will attempt to load the class using the given class loader. If that fails, use the class loader for the EvictionPolicy interface.
        Parameters:
        evictionPolicyClassName - the fully qualified class name of the new eviction policy
        classLoader - the class loader to load the given evictionPolicyClassName.
        Since:
        2.6.0 If loading the class using the given class loader fails, use the class loader for the EvictionPolicy interface.
        See Also:
        getEvictionPolicyClassName()

      • setEvictorShutdownTimeout

        public final void setEvictorShutdownTimeout​(java.time.Duration evictorShutdownTimeout)
        Sets the timeout that will be used when waiting for the Evictor to shutdown if this pool is closed and it is the only pool still using the value for the Evictor.
        Parameters:
        evictorShutdownTimeout - the timeout in milliseconds that will be used while waiting for the Evictor to shut down.
        Since:
        2.10.0

      • setEvictorShutdownTimeoutMillis

        @Deprecated
public final void setEvictorShutdownTimeoutMillis​(long evictorShutdownTimeoutMillis)
        Deprecated.
        Use setEvictorShutdownTimeout(Duration).
        Sets the timeout that will be used when waiting for the Evictor to shutdown if this pool is closed and it is the only pool still using the value for the Evictor.
        Parameters:
        evictorShutdownTimeoutMillis - the timeout in milliseconds that will be used while waiting for the Evictor to shut down.

      • setLifo

        public final void setLifo​(boolean lifo)
        Sets whether the pool has LIFO (last in, first out) behavior with respect to idle objects - always returning the most recently used object from the pool, or as a FIFO (first in, first out) queue, where the pool always returns the oldest object in the idle object pool.
        Parameters:
        lifo - true if the pool is to be configured with LIFO behavior or false if the pool is to be configured with FIFO behavior
        See Also:
        getLifo()

      • setMaxTotal

        public final void setMaxTotal​(int maxTotal)
        Sets the cap on the number of objects that can be allocated by the pool (checked out to clients, or idle awaiting checkout) at a given time. Use a negative value for no limit.
        Parameters:
        maxTotal - The cap on the total number of object instances managed by the pool. Negative values mean that there is no limit to the number of objects allocated by the pool.
        See Also:
        getMaxTotal()

      • setMaxWait

        public final void setMaxWait​(java.time.Duration maxWaitDuration)
        Sets the maximum duration the borrowObject() method should block before throwing an exception when the pool is exhausted and getBlockWhenExhausted() is true. When less than 0, the borrowObject() method may block indefinitely.
        Parameters:
        maxWaitDuration - the maximum duration borrowObject() will block or negative for indefinitely.
        Since:
        2.11.0
        See Also:
        getMaxWaitDuration(), setBlockWhenExhausted(boolean)

      • setMaxWaitMillis

        @Deprecated
public final void setMaxWaitMillis​(long maxWaitMillis)
        Deprecated.
        Use setMaxWait(java.time.Duration).
        Sets the maximum amount of time (in milliseconds) the borrowObject() method should block before throwing an exception when the pool is exhausted and getBlockWhenExhausted() is true. When less than 0, the borrowObject() method may block indefinitely.
        Parameters:
        maxWaitMillis - the maximum number of milliseconds borrowObject() will block or negative for indefinitely.
        See Also:
        getMaxWaitDuration(), setBlockWhenExhausted(boolean)

      • setMessagesStatistics

        public void setMessagesStatistics​(boolean messagesDetails)
        Sets whether to include statistics in exception messages.

        Statistics may not accurately reflect snapshot state at the time of the exception because we do not want to lock the pool when gathering this information.

        Parameters:
        messagesDetails - whether to include statistics in exception messages.
        Since:
        2.11.0

      • setMinEvictableIdleDuration

        public final void setMinEvictableIdleDuration​(java.time.Duration minEvictableIdleTime)
        Sets the minimum amount of time an object may sit idle in the pool before it is eligible for eviction by the idle object evictor (if any - see setDurationBetweenEvictionRuns(Duration)). When non-positive, no objects will be evicted from the pool due to idle time alone.
        Parameters:
        minEvictableIdleTime - minimum amount of time an object may sit idle in the pool before it is eligible for eviction
        Since:
        2.12.0
        See Also:
        getMinEvictableIdleTime(), setTimeBetweenEvictionRuns(java.time.Duration)

      • setNumTestsPerEvictionRun

        public final void setNumTestsPerEvictionRun​(int numTestsPerEvictionRun)
        Sets the maximum number of objects to examine during each run (if any) of the idle object evictor thread. When positive, the number of tests performed for a run will be the minimum of the configured value and the number of idle instances in the pool. When negative, the number of tests performed will be ceil(getNumIdle()/ abs(getNumTestsPerEvictionRun())) which means that when the value is -n roughly one nth of the idle objects will be tested per run.
        Parameters:
        numTestsPerEvictionRun - max number of objects to examine during each evictor run
        See Also:
        getNumTestsPerEvictionRun(), setTimeBetweenEvictionRunsMillis(long)

      • setSoftMinEvictableIdleDuration

        public final void setSoftMinEvictableIdleDuration​(java.time.Duration softMinEvictableIdleTime)
        Sets the minimum amount of time an object may sit idle in the pool before it is eligible for eviction by the idle object evictor (if any - see setDurationBetweenEvictionRuns(Duration)), with the extra condition that at least minIdle object instances remain in the pool. This setting is overridden by getMinEvictableIdleTime() (that is, if getMinEvictableIdleTime() is positive, then getSoftMinEvictableIdleTime() is ignored).
        Parameters:
        softMinEvictableIdleTime - minimum amount of time an object may sit idle in the pool before it is eligible for eviction if minIdle instances are available
        Since:
        2.12.0
        See Also:
        getSoftMinEvictableIdleTimeMillis()

      • setSwallowedExceptionListener

        public final void setSwallowedExceptionListener​(SwallowedExceptionListener swallowedExceptionListener)
        Sets the listener used (if any) to receive notifications of exceptions unavoidably swallowed by the pool.
        Parameters:
        swallowedExceptionListener - The listener or null for no listener

      • setTestOnBorrow

        public final void setTestOnBorrow​(boolean testOnBorrow)
        Sets whether objects borrowed from the pool will be validated before being returned from the borrowObject() method. Validation is performed by the validateObject() method of the factory associated with the pool. If the object fails to validate, it will be removed from the pool and destroyed, and a new attempt will be made to borrow an object from the pool.
        Parameters:
        testOnBorrow - true if objects should be validated before being returned from the borrowObject() method
        See Also:
        getTestOnBorrow()

      • setTestOnCreate

        public final void setTestOnCreate​(boolean testOnCreate)
        Sets whether objects created for the pool will be validated before being returned from the borrowObject() method. Validation is performed by the validateObject() method of the factory associated with the pool. If the object fails to validate, then borrowObject() will fail.
        Parameters:
        testOnCreate - true if newly created objects should be validated before being returned from the borrowObject() method
        Since:
        2.2
        See Also:
        getTestOnCreate()

      • setTestOnReturn

        public final void setTestOnReturn​(boolean testOnReturn)
        Sets whether objects borrowed from the pool will be validated when they are returned to the pool via the returnObject() method. Validation is performed by the validateObject() method of the factory associated with the pool. Returning objects that fail validation are destroyed rather then being returned the pool.
        Parameters:
        testOnReturn - true if objects are validated on return to the pool via the returnObject() method
        See Also:
        getTestOnReturn()

      • setTestWhileIdle

        public final void setTestWhileIdle​(boolean testWhileIdle)
        Sets whether objects sitting idle in the pool will be validated by the idle object evictor (if any - see setDurationBetweenEvictionRuns(Duration)). Validation is performed by the validateObject() method of the factory associated with the pool. If the object fails to validate, it will be removed from the pool and destroyed. Note that setting this property has no effect unless the idle object evictor is enabled by setting timeBetweenEvictionRunsMillis to a positive value.
        Parameters:
        testWhileIdle - true so objects will be validated by the evictor
        See Also:
        getTestWhileIdle(), setTimeBetweenEvictionRuns(java.time.Duration)

      • setTimeBetweenEvictionRuns

        @Deprecated
public final void setTimeBetweenEvictionRuns​(java.time.Duration timeBetweenEvictionRuns)
        Deprecated.
        Use setDurationBetweenEvictionRuns(Duration).
        Sets the number of milliseconds to sleep between runs of the idle object evictor thread.
        • When positive, the idle object evictor thread starts.
        • When non-positive, no idle object evictor thread runs.
        Parameters:
        timeBetweenEvictionRuns - duration to sleep between evictor runs
        Since:
        2.10.0
        See Also:
        getDurationBetweenEvictionRuns()

      • setTimeBetweenEvictionRunsMillis

        @Deprecated
public final void setTimeBetweenEvictionRunsMillis​(long timeBetweenEvictionRunsMillis)
        Deprecated.
        Use setDurationBetweenEvictionRuns(Duration).
        Sets the number of milliseconds to sleep between runs of the idle object evictor thread.
        • When positive, the idle object evictor thread starts.
        • When non-positive, no idle object evictor thread runs.
        Parameters:
        timeBetweenEvictionRunsMillis - number of milliseconds to sleep between evictor runs
        See Also:
        getDurationBetweenEvictionRuns()

      • startEvictor

        final void startEvictor​(java.time.Duration delay)

        Starts the evictor with the given delay. If there is an evictor running when this method is called, it is stopped and replaced with a new evictor with the specified delay.

        This method needs to be final, since it is called from a constructor. See POOL-195.

        Parameters:
        delay - time in milliseconds before start and between eviction runs

      • stopEvictor

        void stopEvictor()
        Stops the evictor.

      • swallowException

        final void swallowException​(java.lang.Exception swallowException)
        Swallows an exception and notifies the configured listener for swallowed exceptions queue.
        Parameters:
        swallowException - exception to be swallowed

      • toStringAppendFields

        protected void toStringAppendFields​(java.lang.StringBuilder builder)
        Description copied from class: BaseObject
        Used by sub-classes to include the fields defined by the sub-class in the BaseObject.toString() output.
        Overrides:
        toStringAppendFields in class BaseObject
        Parameters:
        builder - Field names and values are appended to this object

      • updateStatsBorrow

        final void updateStatsBorrow​(PooledObject<T> p,
                             java.time.Duration waitDuration)
        Updates statistics after an object is borrowed from the pool.
        Parameters:
        p - object borrowed from the pool
        waitDuration - that the borrowing thread had to wait

      • updateStatsReturn

        final void updateStatsReturn​(java.time.Duration activeTime)
        Updates statistics after an object is returned to the pool.
        Parameters:
        activeTime - the amount of time (in milliseconds) that the returning object was checked out

      • wait

        final void wait​(java.lang.Object obj,
                java.time.Duration duration)
         throws java.lang.InterruptedException
        Waits for notification on the given object for the specified duration. Duration.ZERO causes the thread to wait indefinitely.
        Parameters:
        obj - the object to wait on
        duration - the duration to wait
        Throws:
        java.lang.InterruptedException - if interrupted while waiting
        java.lang.IllegalArgumentException - if the duration is negative