Package org.ldaptive.pool

Class AbstractConnectionPool

java.lang.Object
org.ldaptive.AbstractFreezable
org.ldaptive.pool.AbstractConnectionPool
All Implemented Interfaces:
Freezable, ConnectionPool
Direct Known Subclasses:
BlockingConnectionPool
public abstract class AbstractConnectionPool extends AbstractFreezable implements ConnectionPool
Contains the base implementation for pooling connections. The main design objective for the supplied pooling implementations is to provide a pool that does not block on connection creation or destruction. This is what accounts for the multiple locks available on this class. The pool is backed by two queues, one for available connections and one for active connections. Connections that are available via getConnection() exist in the available queue. Connections that are actively in use exist in the active queue. This implementation uses FIFO operations for each queue.

  • Field Details

    • DEFAULT_MIN_POOL_SIZE

      public static final int DEFAULT_MIN_POOL_SIZE
      Default min pool size, value is 3.
      See Also:

    • DEFAULT_MAX_POOL_SIZE

      public static final int DEFAULT_MAX_POOL_SIZE
      Default max pool size, value is 10.
      See Also:

    • ALLOWED_POOL_SIZE

      private static final int ALLOWED_POOL_SIZE
      Allowed pool size for both max and min, value is 65535.
      See Also:

    • MAX_WORKER_TIME

      private static final Duration MAX_WORKER_TIME
      Maximum task execution time for worker threads.

    • POOL_ID

      private static final AtomicInteger POOL_ID
      ID used for pool name.

    • logger

      protected final Logger logger
      Logger for this class.

    • poolLock

      protected final ReentrantLock poolLock
      Lock for the entire pool.

    • poolNotEmpty

      protected final Condition poolNotEmpty
      Condition for notifying threads that a connection was returned.

    • checkOutLock

      protected final ReentrantLock checkOutLock
      Lock for check outs.

    • available

      protected Queue<PooledConnectionProxy> available
      List of available connections in the pool.

    • active

      protected Queue<PooledConnectionProxy> active
      List of connections in use.

    • name

      private String name
      Pool name.

    • minPoolSize

      private int minPoolSize
      Minimum pool size.

    • maxPoolSize

      private int maxPoolSize
      Maximum pool size.

    • validateOnCheckIn

      private boolean validateOnCheckIn
      Whether the ldap connection should be validated when returned to the pool.

    • validateOnCheckOut

      private boolean validateOnCheckOut
      Whether the ldap connection should be validated when given from the pool.

    • validatePeriodically

      private boolean validatePeriodically
      Whether the pool should be validated periodically.

    • activator

      private ConnectionActivator activator
      For activating connections.

    • passivator

      private ConnectionPassivator passivator
      For passivating connections.

    • validator

      private ConnectionValidator validator
      For validating connections.

    • pruneStrategy

      private PruneStrategy pruneStrategy
      For removing connections.

    • connectionFactory

      private DefaultConnectionFactory connectionFactory
      Connection factory to create connections with.

    • connectOnCreate

      private boolean connectOnCreate
      Whether to connect to the ldap on connection creation.

    • queueType

      private QueueType queueType
      Type of queue. LIFO or FIFO.

    • poolExecutor

      private ScheduledExecutorService poolExecutor
      Executor for scheduling pool tasks.

    • initialized

      private volatile boolean initialized
      Whether initialize() has been successfully invoked.

    • failFastInitialize

      private boolean failFastInitialize
      Whether initialize() should throw if pooling configuration requirements are not met.

  • Constructor Details

    • AbstractConnectionPool

      public AbstractConnectionPool()

  • Method Details

    • freeze

      public void freeze()
      Description copied from interface: Freezable
      Freezes this object, making it immutable.
      Specified by:
      freeze in interface Freezable
      Overrides:
      freeze in class AbstractFreezable

    • getName

      public String getName()
      Returns the name for this pool.
      Returns:
      pool name

    • setName

      public void setName(String s)
      Sets the name for this pool.
      Parameters:
      s - pool name

    • getMinPoolSize

      public int getMinPoolSize()
      Returns the min pool size. Default value is DEFAULT_MIN_POOL_SIZE. This value represents the size of the pool after a prune has occurred.
      Returns:
      min pool size

    • setMinPoolSize

      public void setMinPoolSize(int size)
      Sets the min pool size.
      Parameters:
      size - min pool size, greater than or equal to zero

    • getMaxPoolSize

      public int getMaxPoolSize()
      Returns the max pool size. Default value is DEFAULT_MAX_POOL_SIZE. This value may or may not be strictly enforced depending on the pooling implementation.
      Returns:
      max pool size

    • setMaxPoolSize

      public void setMaxPoolSize(int size)
      Sets the max pool size.
      Parameters:
      size - max pool size, greater than or equal to zero

    • isValidateOnCheckIn

      public boolean isValidateOnCheckIn()
      Returns the validate on check in flag.
      Returns:
      validate on check in

    • setValidateOnCheckIn

      public void setValidateOnCheckIn(boolean b)
      Sets the validate on check in flag.
      Parameters:
      b - validate on check in

    • isValidateOnCheckOut

      public boolean isValidateOnCheckOut()
      Returns the validate on check out flag.
      Returns:
      validate on check in

    • setValidateOnCheckOut

      public void setValidateOnCheckOut(boolean b)
      Sets the validate on check out flag.
      Parameters:
      b - validate on check out

    • isValidatePeriodically

      public boolean isValidatePeriodically()
      Returns the validate periodically flag.
      Returns:
      validate periodically

    • setValidatePeriodically

      public void setValidatePeriodically(boolean b)
      Sets the validate periodically flag.
      Parameters:
      b - validate periodically

    • getActivator

      public ConnectionActivator getActivator()
      Returns the activator for this pool.
      Returns:
      activator

    • setActivator

      public void setActivator(ConnectionActivator a)
      Sets the activator for this pool.
      Parameters:
      a - activator

    • getPassivator

      public ConnectionPassivator getPassivator()
      Returns the passivator for this pool.
      Returns:
      passivator

    • setPassivator

      public void setPassivator(ConnectionPassivator p)
      Sets the passivator for this pool.
      Parameters:
      p - passivator

    • getValidator

      public ConnectionValidator getValidator()
      Returns the connection validator for this pool.
      Returns:
      connection validator

    • setValidator

      public void setValidator(ConnectionValidator cv)
      Sets the connection validator for this pool.
      Parameters:
      cv - connection validator

    • getPruneStrategy

      public PruneStrategy getPruneStrategy()
      Returns the prune strategy for this pool.
      Returns:
      prune strategy

    • setPruneStrategy

      public void setPruneStrategy(PruneStrategy ps)
      Sets the prune strategy for this pool.
      Parameters:
      ps - prune strategy

    • getDefaultConnectionFactory

      public DefaultConnectionFactory getDefaultConnectionFactory()
      Returns the connection factory for this pool.
      Returns:
      connection factory

    • setDefaultConnectionFactory

      public void setDefaultConnectionFactory(DefaultConnectionFactory cf)
      Sets the connection factory for this pool.
      Parameters:
      cf - connection factory

    • getConnectOnCreate

      public boolean getConnectOnCreate()
      Returns whether connections will attempt to connect after creation. Default is true.
      Returns:
      whether connections will attempt to connect after creation

    • setConnectOnCreate

      public void setConnectOnCreate(boolean b)
      Sets whether newly created connections will attempt to connect. Default is true.
      Parameters:
      b - connect on create

    • getQueueType

      public QueueType getQueueType()
      Returns the type of queue used for this connection pool.
      Returns:
      queue type

    • setQueueType

      public void setQueueType(QueueType type)
      Sets the type of queue used for this connection pool. This property may have an impact on the success of the prune strategy.
      Parameters:
      type - of queue

    • getFailFastInitialize

      public boolean getFailFastInitialize()
      Returns whether initialize() should throw if pooling configuration requirements are not met.
      Returns:
      whether initialize() should throw

    • setFailFastInitialize

      public void setFailFastInitialize(boolean b)
      Sets whether initialize() should throw if pooling configuration requirements are not met.
      Parameters:
      b - whether initialize() should throw

    • isInitialized

      public boolean isInitialized()
      Returns whether this pool has been initialized.
      Returns:
      whether this pool has been initialized

    • throwIfNotInitialized

      protected void throwIfNotInitialized()
      Used to determine whether initialize() has been invoked for this pool.
      Throws:
      IllegalStateException - if this pool has not been initialized

    • initialize

      public void initialize()
      Initialize this pool for use.
      Specified by:
      initialize in interface ConnectionPool
      Throws:
      IllegalStateException - if this pool has already been initialized, the pooling configuration is inconsistent or the pool does not contain at least one connection and its minimum size is greater than zero

    • grow

      protected void grow(int size)
      Attempts to grow the pool to the supplied size. If the pool size is greater than or equal to the supplied size, this method is a no-op.
      Parameters:
      size - to grow the pool to
      Throws:
      IllegalStateException - if the pool cannot grow to the supplied size and createAvailableConnections(int, boolean, boolean) throws

    • close

      public void close()
      Empty this pool, freeing any resources.
      Specified by:
      close in interface ConnectionPool
      Throws:
      IllegalStateException - if this pool has not been initialized

    • closeAllConnections

      private void closeAllConnections()
      Closes all connections in the pool.

    • closeConnections

      private void closeConnections(CallableWorker<PooledConnectionProxy> callableWorker, List<PooledConnectionProxy> connections)
      Asynchronously closes all the connections in the supplied list.
      Parameters:
      callableWorker - to execute async tasks
      connections - to close

    • getConnection

      public abstract Connection getConnection() throws PoolException
      Returns a connection from the pool.
      Specified by:
      getConnection in interface ConnectionPool
      Returns:
      connection
      Throws:
      PoolException - if this operation fails
      BlockingTimeoutException - if this pool is configured with a block time and it occurs
      IllegalStateException - if this pool has not been initialized

    • putConnection

      public abstract void putConnection(Connection c)
      Returns a connection to the pool.
      Parameters:
      c - connection
      Throws:
      IllegalStateException - if this pool has not been initialized

    • createConnection

      private PooledConnectionProxy createConnection(boolean throwOnFailure)
      Create a new connection. If connectOnCreate is true, the connection will be opened.
      Parameters:
      throwOnFailure - whether to throw illegal state exception
      Returns:
      pooled connection or null
      Throws:
      IllegalStateException - if connectOnCreate is true and the connection cannot be opened

    • createConnections

      private List<PooledConnectionProxy> createConnections(CallableWorker<PooledConnectionProxy> callableWorker, int count, boolean throwOnFailure)
      Asynchronously creates new connections and confirms that the connections can be passivated and validated. See passivateAndValidateConnection(PooledConnectionProxy). This method can make up to (count * 2) attempts in a best effort to create the number of connections requested.
      Parameters:
      callableWorker - to execute async tasks
      count - number of connections to attempt to create
      throwOnFailure - whether to throw illegal state exception on any connection creation failure
      Returns:
      list of new connections
      Throws:
      IllegalStateException - if throwOnFailure is true and count connections are not successfully created

    • createAvailableConnections

      protected void createAvailableConnections(int count, boolean throwOnFailure, boolean throwIfNotInitialized)
      Asynchronously creates new connections and adds them to the available queue. See createConnections(CallableWorker, int, boolean) .
      Parameters:
      count - number of connections to attempt to create
      throwOnFailure - whether to throw illegal state exception on any connection creation failure
      throwIfNotInitialized - whether to throw illegal state exception if the pool is not initialized
      Throws:
      IllegalStateException - if throwOnFailure is true and count connections are not successfully created

    • createAvailableConnection

      protected PooledConnectionProxy createAvailableConnection(boolean throwOnFailure)
      Create a new connection and place it in the available pool.
      Parameters:
      throwOnFailure - whether to throw illegal state exception
      Returns:
      connection that was placed in the available pool
      Throws:
      IllegalStateException - if createConnection(boolean) throws

    • createActiveConnection

      protected PooledConnectionProxy createActiveConnection(boolean throwOnFailure)
      Create a new connection and place it in the active queue. This method creates the connection and then attempts to acquire the pool lock in order to add the connection to the active queue. Therefore, this method can be invoked both with and without acquiring the pool lock.
      Parameters:
      throwOnFailure - whether to throw illegal state exception on connection creation failure
      Returns:
      connection that was placed in the active pool
      Throws:
      IllegalStateException - if createConnection(boolean) throws

    • removeAvailableConnection

      protected void removeAvailableConnection(PooledConnectionProxy pc)
      Remove a connection from the available pool.
      Parameters:
      pc - connection that is in the available pool

    • removeActiveConnection

      protected void removeActiveConnection(PooledConnectionProxy pc)
      Remove a connection from the active pool.
      Parameters:
      pc - connection that is in the active pool

    • removeAvailableAndActiveConnection

      protected void removeAvailableAndActiveConnection(PooledConnectionProxy pc)
      Remove a connection from both the available and active pools.
      Parameters:
      pc - connection that is in both the available and active pools

    • activateAndValidateConnection

      protected void activateAndValidateConnection(PooledConnectionProxy pc) throws PoolException
      Attempts to activate and validate a connection. Performed before a connection is returned from getConnection(). Validation only occurs if validateOnCheckOut is true. If a connection fails either activation or validation it is removed from the pool.
      Parameters:
      pc - connection
      Throws:
      PoolException - if either activation or validation fails

    • passivateAndValidateConnection

      protected boolean passivateAndValidateConnection(PooledConnectionProxy pc)
      Attempts to passivate and validate a connection. Performed when a connection is given to putConnection(Connection) and when a new connection enters the pool. Validation only occurs if validateOnCheckIn is true.
      Parameters:
      pc - connection
      Returns:
      whether both passivation and validation succeeded

    • prune

      public void prune()
      Attempts to reduce the size of the pool back to its configured minimum.
      Throws:
      IllegalStateException - if this pool has not been initialized

    • validate

      public void validate()
      Attempts to validate all connections in the pool.
      Throws:
      IllegalStateException - if this pool has not been initialized

    • availableCount

      public int availableCount()
      Description copied from interface: ConnectionPool
      Returns the number of connections available for use.
      Specified by:
      availableCount in interface ConnectionPool
      Returns:
      count

    • activeCount

      public int activeCount()
      Description copied from interface: ConnectionPool
      Returns the number of connections in use.
      Specified by:
      activeCount in interface ConnectionPool
      Returns:
      count

    • getPooledConnectionStatistics

      public Set<PooledConnectionStatistics> getPooledConnectionStatistics()
      Description copied from interface: ConnectionPool
      Returns the statistics for each connection in the pool.
      Specified by:
      getPooledConnectionStatistics in interface ConnectionPool
      Returns:
      connection statistics

    • createConnectionProxy

      protected Connection createConnectionProxy(PooledConnectionProxy pc)
      Creates a connection proxy using the supplied pool connection.
      Parameters:
      pc - pool connection to create proxy with
      Returns:
      connection proxy

    • retrieveConnectionProxy

      protected PooledConnectionProxy retrieveConnectionProxy(Connection proxy)
      Retrieves the invocation handler from the supplied connection proxy.
      Parameters:
      proxy - connection proxy
      Returns:
      pooled connection proxy

    • toString

      public String toString()
      Overrides:
      toString in class Object