Class LDAPConnectionPool

  • All Implemented Interfaces:
    FullLDAPInterface, LDAPInterface, java.io.Closeable, java.lang.AutoCloseable

    @ThreadSafety(level=COMPLETELY_THREADSAFE)
    public final class LDAPConnectionPool
    extends AbstractConnectionPool
    This class provides an implementation of an LDAP connection pool, which is a structure that can hold multiple connections established to a given server that can be reused for multiple operations rather than creating and destroying connections for each operation. This connection pool implementation provides traditional methods for checking out and releasing connections, but it also provides wrapper methods that make it easy to perform operations using pooled connections without the need to explicitly check out or release the connections.

    Note that both the LDAPConnectionPool class and the LDAPConnection class implement the LDAPInterface interface. This is a common interface that defines a number of common methods for processing LDAP requests. This means that in many cases, an application can use an object of type LDAPInterface rather than LDAPConnection, which makes it possible to work with either a single standalone connection or with a connection pool.

    Creating a Connection Pool

    An LDAP connection pool can be created from either a single LDAPConnection (for which an appropriate number of copies will be created to fill out the pool) or using a ServerSet to create connections that may span multiple servers. For example:

       // Create a new LDAP connection pool with ten connections established and
       // authenticated to the same server:
       LDAPConnection connection = new LDAPConnection(address, port);
       BindResult bindResult = connection.bind(bindDN, password);
       LDAPConnectionPool connectionPool = new LDAPConnectionPool(connection, 10);
    
       // Create a new LDAP connection pool with 10 connections spanning multiple
       // servers using a server set.
       RoundRobinServerSet serverSet = new RoundRobinServerSet(addresses, ports);
       SimpleBindRequest bindRequest = new SimpleBindRequest(bindDN, password);
       LDAPConnectionPool connectionPool =
            new LDAPConnectionPool(serverSet, bindRequest, 10);
     
    Note that in some cases, such as when using StartTLS, it may be necessary to perform some additional processing when a new connection is created for use in the connection pool. In this case, a PostConnectProcessor should be provided to accomplish this. See the documentation for the StartTLSPostConnectProcessor class for an example that demonstrates its use for creating a connection pool with connections secured using StartTLS.

    Processing Operations with a Connection Pool

    If a single operation is to be processed using a connection from the connection pool, then it can be used without the need to check out or release a connection or perform any validity checking on the connection. This can be accomplished via the LDAPInterface interface that allows a connection pool to be treated like a single connection. For example, to perform a search using a pooled connection:
       SearchResult searchResult =
            connectionPool.search("dc=example,dc=com", SearchScope.SUB,
                                  "(uid=john.doe)");
     
    If an application needs to process multiple operations using a single connection, then it may be beneficial to obtain a connection from the pool to use for processing those operations and then return it back to the pool when it is no longer needed. This can be done using the getConnection() and releaseConnection(com.unboundid.ldap.sdk.LDAPConnection) methods. If during processing it is determined that the connection is no longer valid, then the connection should be released back to the pool using the releaseDefunctConnection(com.unboundid.ldap.sdk.LDAPConnection) method, which will ensure that the connection is closed and a new connection will be established to take its place in the pool.

    Note that it is also possible to process multiple operations on a single connection using the AbstractConnectionPool.processRequests(java.util.List<com.unboundid.ldap.sdk.LDAPRequest>, boolean) method. This may be useful if a fixed set of operations should be processed over the same connection and none of the subsequent requests depend upon the results of the earlier operations.

    Connection pools should generally not be used when performing operations that may change the state of the underlying connections. This is particularly true for bind operations and the StartTLS extended operation, but it may apply to other types of operations as well.

    Performing a bind operation using a connection from the pool will invalidate any previous authentication on that connection, and if that connection is released back to the pool without first being re-authenticated as the original user, then subsequent operation attempts may fail or be processed in an incorrect manner. Bind operations should only be performed in a connection pool if the pool is to be used exclusively for processing binds, if the bind request is specially crafted so that it will not change the identity of the associated connection (e.g., by including the retain identity request control in the bind request if using the LDAP SDK with a Ping Identity, UnboundID, or Nokia/Alcatel-Lucent 8661 Directory Server), or if the code using the connection pool makes sure to re-authenticate the connection as the appropriate user whenever its identity has been changed.

    The StartTLS extended operation should never be invoked on a connection which is part of a connection pool. It is acceptable for the pool to maintain connections which have been configured with StartTLS security prior to being added to the pool (via the use of the StartTLSPostConnectProcessor).

    Pool Connection Management

    When creating a connection pool, you may specify an initial number of connections and a maximum number of connections. The initial number of connections is the number of connections that should be immediately established and available for use when the pool is created. The maximum number of connections is the largest number of unused connections that may be available in the pool at any time.

    Whenever a connection is needed, whether by an attempt to check out a connection or to use one of the pool's methods to process an operation, the pool will first check to see if there is a connection that has already been established but is not currently in use, and if so then that connection will be used. If there aren't any unused connections that are already established, then the pool will determine if it has yet created the maximum number of connections, and if not then it will immediately create a new connection and use it. If the pool has already created the maximum number of connections, then the pool may wait for a period of time (as indicated by the getMaxWaitTimeMillis() method, which has a default value of zero to indicate that it should not wait at all) for an in-use connection to be released back to the pool. If no connection is available after the specified wait time (or there should not be any wait time), then the pool may automatically create a new connection to use if getCreateIfNecessary() returns true (which is the default). If it is able to successfully create a connection, then it will be used. If it cannot create a connection, or if getCreateIfNecessary() returns false, then an LDAPException will be thrown.

    Note that the maximum number of connections specified when creating a pool refers to the maximum number of connections that should be available for use at any given time. If getCreateIfNecessary() returns true, then there may temporarily be more active connections than the configured maximum number of connections. This can be useful during periods of heavy activity, because the pool will keep those connections established until the number of unused connections exceeds the configured maximum. If you wish to enforce a hard limit on the maximum number of connections so that there cannot be more than the configured maximum in use at any time, then use the setCreateIfNecessary(boolean) method to indicate that the pool should not automatically create connections when one is needed but none are available, and you may also want to use the setMaxWaitTimeMillis(long) method to specify a maximum wait time to allow the pool to wait for a connection to become available rather than throwing an exception if no connections are immediately available.
    • Constructor Detail

      • LDAPConnectionPool

        public LDAPConnectionPool​(@NotNull
                                  LDAPConnection connection,
                                  int numConnections)
                           throws LDAPException
        Creates a new LDAP connection pool with up to the specified number of connections, created as clones of the provided connection. Initially, only the provided connection will be included in the pool, but additional connections will be created as needed until the pool has reached its full capacity, at which point the create if necessary and max wait time settings will be used to determine how to behave if a connection is requested but none are available.
        Parameters:
        connection - The connection to use to provide the template for the other connections to be created. This connection will be included in the pool. It must not be null, and it must be established to the target server. It does not necessarily need to be authenticated if all connections in the pool are to be unauthenticated.
        numConnections - The total number of connections that should be created in the pool. It must be greater than or equal to one.
        Throws:
        LDAPException - If the provided connection cannot be used to initialize the pool, or if a problem occurs while attempting to establish any of the connections. If this is thrown, then all connections associated with the pool (including the one provided as an argument) will be closed.
      • LDAPConnectionPool

        public LDAPConnectionPool​(@NotNull
                                  LDAPConnection connection,
                                  int initialConnections,
                                  int maxConnections)
                           throws LDAPException
        Creates a new LDAP connection pool with the specified number of connections, created as clones of the provided connection.
        Parameters:
        connection - The connection to use to provide the template for the other connections to be created. This connection will be included in the pool. It must not be null, and it must be established to the target server. It does not necessarily need to be authenticated if all connections in the pool are to be unauthenticated.
        initialConnections - The number of connections to initially establish when the pool is created. It must be greater than or equal to one.
        maxConnections - The maximum number of connections that should be maintained in the pool. It must be greater than or equal to the initial number of connections. See the "Pool Connection Management" section of the class-level documentation for an explanation of how the pool treats the maximum number of connections.
        Throws:
        LDAPException - If the provided connection cannot be used to initialize the pool, or if a problem occurs while attempting to establish any of the connections. If this is thrown, then all connections associated with the pool (including the one provided as an argument) will be closed.
      • LDAPConnectionPool

        public LDAPConnectionPool​(@NotNull
                                  LDAPConnection connection,
                                  int initialConnections,
                                  int maxConnections,
                                  @Nullable
                                  PostConnectProcessor postConnectProcessor)
                           throws LDAPException
        Creates a new LDAP connection pool with the specified number of connections, created as clones of the provided connection.
        Parameters:
        connection - The connection to use to provide the template for the other connections to be created. This connection will be included in the pool. It must not be null, and it must be established to the target server. It does not necessarily need to be authenticated if all connections in the pool are to be unauthenticated.
        initialConnections - The number of connections to initially establish when the pool is created. It must be greater than or equal to one.
        maxConnections - The maximum number of connections that should be maintained in the pool. It must be greater than or equal to the initial number of connections. See the "Pool Connection Management" section of the class-level documentation for an explanation of how the pool treats the maximum number of connections.
        postConnectProcessor - A processor that should be used to perform any post-connect processing for connections in this pool. It may be null if no special processing is needed. Note that this processing will not be invoked on the provided connection that will be used as the first connection in the pool.
        Throws:
        LDAPException - If the provided connection cannot be used to initialize the pool, or if a problem occurs while attempting to establish any of the connections. If this is thrown, then all connections associated with the pool (including the one provided as an argument) will be closed.
      • LDAPConnectionPool

        public LDAPConnectionPool​(@NotNull
                                  LDAPConnection connection,
                                  int initialConnections,
                                  int maxConnections,
                                  @Nullable
                                  PostConnectProcessor postConnectProcessor,
                                  boolean throwOnConnectFailure)
                           throws LDAPException
        Creates a new LDAP connection pool with the specified number of connections, created as clones of the provided connection.
        Parameters:
        connection - The connection to use to provide the template for the other connections to be created. This connection will be included in the pool. It must not be null, and it must be established to the target server. It does not necessarily need to be authenticated if all connections in the pool are to be unauthenticated.
        initialConnections - The number of connections to initially establish when the pool is created. It must be greater than or equal to one.
        maxConnections - The maximum number of connections that should be maintained in the pool. It must be greater than or equal to the initial number of connections. See the "Pool Connection Management" section of the class-level documentation for an explanation of how the pool treats the maximum number of connections.
        postConnectProcessor - A processor that should be used to perform any post-connect processing for connections in this pool. It may be null if no special processing is needed. Note that this processing will not be invoked on the provided connection that will be used as the first connection in the pool.
        throwOnConnectFailure - If an exception should be thrown if a problem is encountered while attempting to create the specified initial number of connections. If true, then the attempt to create the pool will fail.if any connection cannot be established. If false, then the pool will be created but may have fewer than the initial number of connections (or possibly no connections).
        Throws:
        LDAPException - If the provided connection cannot be used to initialize the pool, or if a problem occurs while attempting to establish any of the connections. If this is thrown, then all connections associated with the pool (including the one provided as an argument) will be closed.
      • LDAPConnectionPool

        public LDAPConnectionPool​(@NotNull
                                  LDAPConnection connection,
                                  int initialConnections,
                                  int maxConnections,
                                  int initialConnectThreads,
                                  @Nullable
                                  PostConnectProcessor postConnectProcessor,
                                  boolean throwOnConnectFailure)
                           throws LDAPException
        Creates a new LDAP connection pool with the specified number of connections, created as clones of the provided connection.
        Parameters:
        connection - The connection to use to provide the template for the other connections to be created. This connection will be included in the pool. It must not be null, and it must be established to the target server. It does not necessarily need to be authenticated if all connections in the pool are to be unauthenticated.
        initialConnections - The number of connections to initially establish when the pool is created. It must be greater than or equal to one.
        maxConnections - The maximum number of connections that should be maintained in the pool. It must be greater than or equal to the initial number of connections. See the "Pool Connection Management" section of the class-level documentation for an explanation of how the pool treats the maximum number of connections.
        initialConnectThreads - The number of concurrent threads to use to establish the initial set of connections. A value greater than one indicates that the attempt to establish connections should be parallelized.
        postConnectProcessor - A processor that should be used to perform any post-connect processing for connections in this pool. It may be null if no special processing is needed. Note that this processing will not be invoked on the provided connection that will be used as the first connection in the pool.
        throwOnConnectFailure - If an exception should be thrown if a problem is encountered while attempting to create the specified initial number of connections. If true, then the attempt to create the pool will fail.if any connection cannot be established. If false, then the pool will be created but may have fewer than the initial number of connections (or possibly no connections).
        Throws:
        LDAPException - If the provided connection cannot be used to initialize the pool, or if a problem occurs while attempting to establish any of the connections. If this is thrown, then all connections associated with the pool (including the one provided as an argument) will be closed.
      • LDAPConnectionPool

        public LDAPConnectionPool​(@NotNull
                                  LDAPConnection connection,
                                  int initialConnections,
                                  int maxConnections,
                                  int initialConnectThreads,
                                  @Nullable
                                  PostConnectProcessor postConnectProcessor,
                                  boolean throwOnConnectFailure,
                                  @Nullable
                                  LDAPConnectionPoolHealthCheck healthCheck)
                           throws LDAPException
        Creates a new LDAP connection pool with the specified number of connections, created as clones of the provided connection.
        Parameters:
        connection - The connection to use to provide the template for the other connections to be created. This connection will be included in the pool. It must not be null, and it must be established to the target server. It does not necessarily need to be authenticated if all connections in the pool are to be unauthenticated.
        initialConnections - The number of connections to initially establish when the pool is created. It must be greater than or equal to one.
        maxConnections - The maximum number of connections that should be maintained in the pool. It must be greater than or equal to the initial number of connections. See the "Pool Connection Management" section of the class-level documentation for an explanation of how the pool treats the maximum number of connections.
        initialConnectThreads - The number of concurrent threads to use to establish the initial set of connections. A value greater than one indicates that the attempt to establish connections should be parallelized.
        postConnectProcessor - A processor that should be used to perform any post-connect processing for connections in this pool. It may be null if no special processing is needed. Note that this processing will not be invoked on the provided connection that will be used as the first connection in the pool.
        throwOnConnectFailure - If an exception should be thrown if a problem is encountered while attempting to create the specified initial number of connections. If true, then the attempt to create the pool will fail.if any connection cannot be established. If false, then the pool will be created but may have fewer than the initial number of connections (or possibly no connections).
        healthCheck - The health check that should be used for connections in this pool. It may be null if the default health check should be used.
        Throws:
        LDAPException - If the provided connection cannot be used to initialize the pool, or if a problem occurs while attempting to establish any of the connections. If this is thrown, then all connections associated with the pool (including the one provided as an argument) will be closed.
      • LDAPConnectionPool

        public LDAPConnectionPool​(@NotNull
                                  ServerSet serverSet,
                                  @Nullable
                                  BindRequest bindRequest,
                                  int numConnections)
                           throws LDAPException
        Creates a new LDAP connection pool with the specified number of connections, created using the provided server set. Initially, only one will be created and included in the pool, but additional connections will be created as needed until the pool has reached its full capacity, at which point the create if necessary and max wait time settings will be used to determine how to behave if a connection is requested but none are available.
        Parameters:
        serverSet - The server set to use to create the connections. It is acceptable for the server set to create the connections across multiple servers.
        bindRequest - The bind request to use to authenticate the connections that are established. It may be null if no authentication should be performed on the connections. Note that if the server set is configured to perform authentication, this bind request should be the same bind request used by the server set. This is important because even though the server set may be used to perform the initial authentication on a newly established connection, this connection pool may still need to re-authenticate the connection.
        numConnections - The total number of connections that should be created in the pool. It must be greater than or equal to one.
        Throws:
        LDAPException - If a problem occurs while attempting to establish any of the connections. If this is thrown, then all connections associated with the pool will be closed.
      • LDAPConnectionPool

        public LDAPConnectionPool​(@NotNull
                                  ServerSet serverSet,
                                  @Nullable
                                  BindRequest bindRequest,
                                  int initialConnections,
                                  int maxConnections)
                           throws LDAPException
        Creates a new LDAP connection pool with the specified number of connections, created using the provided server set.
        Parameters:
        serverSet - The server set to use to create the connections. It is acceptable for the server set to create the connections across multiple servers.
        bindRequest - The bind request to use to authenticate the connections that are established. It may be null if no authentication should be performed on the connections. Note that if the server set is configured to perform authentication, this bind request should be the same bind request used by the server set. This is important because even though the server set may be used to perform the initial authentication on a newly established connection, this connection pool may still need to re-authenticate the connection.
        initialConnections - The number of connections to initially establish when the pool is created. It must be greater than or equal to zero.
        maxConnections - The maximum number of connections that should be maintained in the pool. It must be greater than or equal to the initial number of connections, and must not be zero. See the "Pool Connection Management" section of the class-level documentation for an explanation of how the pool treats the maximum number of connections.
        Throws:
        LDAPException - If a problem occurs while attempting to establish any of the connections. If this is thrown, then all connections associated with the pool will be closed.
      • LDAPConnectionPool

        public LDAPConnectionPool​(@NotNull
                                  ServerSet serverSet,
                                  @Nullable
                                  BindRequest bindRequest,
                                  int initialConnections,
                                  int maxConnections,
                                  @Nullable
                                  PostConnectProcessor postConnectProcessor)
                           throws LDAPException
        Creates a new LDAP connection pool with the specified number of connections, created using the provided server set.
        Parameters:
        serverSet - The server set to use to create the connections. It is acceptable for the server set to create the connections across multiple servers.
        bindRequest - The bind request to use to authenticate the connections that are established. It may be null if no authentication should be performed on the connections. Note that if the server set is configured to perform authentication, this bind request should be the same bind request used by the server set. This is important because even though the server set may be used to perform the initial authentication on a newly established connection, this connection pool may still need to re-authenticate the connection.
        initialConnections - The number of connections to initially establish when the pool is created. It must be greater than or equal to zero.
        maxConnections - The maximum number of connections that should be maintained in the pool. It must be greater than or equal to the initial number of connections, and must not be zero. See the "Pool Connection Management" section of the class-level documentation for an explanation of how the pool treats the maximum number of connections.
        postConnectProcessor - A processor that should be used to perform any post-connect processing for connections in this pool. It may be null if no special processing is needed. Note that if the server set is configured with a non-null post-connect processor, then the post-connect processor provided to the pool must be null.
        Throws:
        LDAPException - If a problem occurs while attempting to establish any of the connections. If this is thrown, then all connections associated with the pool will be closed.
      • LDAPConnectionPool

        public LDAPConnectionPool​(@NotNull
                                  ServerSet serverSet,
                                  @Nullable
                                  BindRequest bindRequest,
                                  int initialConnections,
                                  int maxConnections,
                                  @Nullable
                                  PostConnectProcessor postConnectProcessor,
                                  boolean throwOnConnectFailure)
                           throws LDAPException
        Creates a new LDAP connection pool with the specified number of connections, created using the provided server set.
        Parameters:
        serverSet - The server set to use to create the connections. It is acceptable for the server set to create the connections across multiple servers.
        bindRequest - The bind request to use to authenticate the connections that are established. It may be null if no authentication should be performed on the connections. Note that if the server set is configured to perform authentication, this bind request should be the same bind request used by the server set. This is important because even though the server set may be used to perform the initial authentication on a newly established connection, this connection pool may still need to re-authenticate the connection.
        initialConnections - The number of connections to initially establish when the pool is created. It must be greater than or equal to zero.
        maxConnections - The maximum number of connections that should be maintained in the pool. It must be greater than or equal to the initial number of connections, and must not be zero. See the "Pool Connection Management" section of the class-level documentation for an explanation of how the pool treats the maximum number of connections.
        postConnectProcessor - A processor that should be used to perform any post-connect processing for connections in this pool. It may be null if no special processing is needed. Note that if the server set is configured with a non-null post-connect processor, then the post-connect processor provided to the pool must be null.
        throwOnConnectFailure - If an exception should be thrown if a problem is encountered while attempting to create the specified initial number of connections. If true, then the attempt to create the pool will fail.if any connection cannot be established. If false, then the pool will be created but may have fewer than the initial number of connections (or possibly no connections).
        Throws:
        LDAPException - If a problem occurs while attempting to establish any of the connections and throwOnConnectFailure is true. If this is thrown, then all connections associated with the pool will be closed.
      • LDAPConnectionPool

        public LDAPConnectionPool​(@NotNull
                                  ServerSet serverSet,
                                  @Nullable
                                  BindRequest bindRequest,
                                  int initialConnections,
                                  int maxConnections,
                                  int initialConnectThreads,
                                  @Nullable
                                  PostConnectProcessor postConnectProcessor,
                                  boolean throwOnConnectFailure)
                           throws LDAPException
        Creates a new LDAP connection pool with the specified number of connections, created using the provided server set.
        Parameters:
        serverSet - The server set to use to create the connections. It is acceptable for the server set to create the connections across multiple servers.
        bindRequest - The bind request to use to authenticate the connections that are established. It may be null if no authentication should be performed on the connections. Note that if the server set is configured to perform authentication, this bind request should be the same bind request used by the server set. This is important because even though the server set may be used to perform the initial authentication on a newly established connection, this connection pool may still need to re-authenticate the connection.
        initialConnections - The number of connections to initially establish when the pool is created. It must be greater than or equal to zero.
        maxConnections - The maximum number of connections that should be maintained in the pool. It must be greater than or equal to the initial number of connections, and must not be zero. See the "Pool Connection Management" section of the class-level documentation for an explanation of how the pool treats the maximum number of connections.
        initialConnectThreads - The number of concurrent threads to use to establish the initial set of connections. A value greater than one indicates that the attempt to establish connections should be parallelized.
        postConnectProcessor - A processor that should be used to perform any post-connect processing for connections in this pool. It may be null if no special processing is needed. Note that if the server set is configured with a non-null post-connect processor, then the post-connect processor provided to the pool must be null.
        throwOnConnectFailure - If an exception should be thrown if a problem is encountered while attempting to create the specified initial number of connections. If true, then the attempt to create the pool will fail.if any connection cannot be established. If false, then the pool will be created but may have fewer than the initial number of connections (or possibly no connections).
        Throws:
        LDAPException - If a problem occurs while attempting to establish any of the connections and throwOnConnectFailure is true. If this is thrown, then all connections associated with the pool will be closed.
      • LDAPConnectionPool

        public LDAPConnectionPool​(@NotNull
                                  ServerSet serverSet,
                                  @Nullable
                                  BindRequest bindRequest,
                                  int initialConnections,
                                  int maxConnections,
                                  int initialConnectThreads,
                                  @Nullable
                                  PostConnectProcessor postConnectProcessor,
                                  boolean throwOnConnectFailure,
                                  @Nullable
                                  LDAPConnectionPoolHealthCheck healthCheck)
                           throws LDAPException
        Creates a new LDAP connection pool with the specified number of connections, created using the provided server set.
        Parameters:
        serverSet - The server set to use to create the connections. It is acceptable for the server set to create the connections across multiple servers.
        bindRequest - The bind request to use to authenticate the connections that are established. It may be null if no authentication should be performed on the connections. Note that if the server set is configured to perform authentication, this bind request should be the same bind request used by the server set. This is important because even though the server set may be used to perform the initial authentication on a newly established connection, this connection pool may still need to re-authenticate the connection.
        initialConnections - The number of connections to initially establish when the pool is created. It must be greater than or equal to zero.
        maxConnections - The maximum number of connections that should be maintained in the pool. It must be greater than or equal to the initial number of connections, and must not be zero. See the "Pool Connection Management" section of the class-level documentation for an explanation of how the pool treats the maximum number of connections.
        initialConnectThreads - The number of concurrent threads to use to establish the initial set of connections. A value greater than one indicates that the attempt to establish connections should be parallelized.
        postConnectProcessor - A processor that should be used to perform any post-connect processing for connections in this pool. It may be null if no special processing is needed. Note that if the server set is configured with a non-null post-connect processor, then the post-connect processor provided to the pool must be null.
        throwOnConnectFailure - If an exception should be thrown if a problem is encountered while attempting to create the specified initial number of connections. If true, then the attempt to create the pool will fail if any connection cannot be established. If false, then the pool will be created but may have fewer than the initial number of connections (or possibly no connections).
        healthCheck - The health check that should be used for connections in this pool. It may be null if the default health check should be used.
        Throws:
        LDAPException - If a problem occurs while attempting to establish any of the connections and throwOnConnectFailure is true. If this is thrown, then all connections associated with the pool will be closed.
    • Method Detail

      • close

        public void close()
        Closes this connection pool. All connections currently held in the pool that are not in use will be closed, and any outstanding connections will be automatically closed when they are released back to the pool.
        Specified by:
        close in interface java.lang.AutoCloseable
        Specified by:
        close in interface java.io.Closeable
        Specified by:
        close in interface FullLDAPInterface
        Specified by:
        close in class AbstractConnectionPool
      • close

        public void close​(boolean unbind,
                          int numThreads)
        Closes this connection pool, optionally using multiple threads to close the connections in parallel.
        Specified by:
        close in class AbstractConnectionPool
        Parameters:
        unbind - Indicates whether to try to send an unbind request to the server before closing the connection.
        numThreads - The number of threads to use when closing the connections.
      • isClosed

        public boolean isClosed()
        Indicates whether this connection pool has been closed.
        Specified by:
        isClosed in class AbstractConnectionPool
        Returns:
        true if this connection pool has been closed, or false if not.
      • bindAndRevertAuthentication

        @NotNull
        public BindResult bindAndRevertAuthentication​(@Nullable
                                                      java.lang.String bindDN,
                                                      @Nullable
                                                      java.lang.String password,
                                                      @Nullable
                                                      Control... controls)
                                               throws LDAPException
        Processes a simple bind using a connection from this connection pool, and then reverts that authentication by re-binding as the same user used to authenticate new connections. If new connections are unauthenticated, then the subsequent bind will be an anonymous simple bind. This method attempts to ensure that processing the provided bind operation does not have a lasting impact the authentication state of the connection used to process it.

        If the second bind attempt (the one used to restore the authentication identity) fails, the connection will be closed as defunct so that a new connection will be created to take its place.
        Parameters:
        bindDN - The bind DN for the simple bind request.
        password - The password for the simple bind request.
        controls - The optional set of controls for the simple bind request.
        Returns:
        The result of processing the provided bind operation.
        Throws:
        LDAPException - If the server rejects the bind request, or if a problem occurs while sending the request or reading the response.
      • bindAndRevertAuthentication

        @NotNull
        public BindResult bindAndRevertAuthentication​(@NotNull
                                                      BindRequest bindRequest)
                                               throws LDAPException
        Processes the provided bind request using a connection from this connection pool, and then reverts that authentication by re-binding as the same user used to authenticate new connections. If new connections are unauthenticated, then the subsequent bind will be an anonymous simple bind. This method attempts to ensure that processing the provided bind operation does not have a lasting impact the authentication state of the connection used to process it.

        If the second bind attempt (the one used to restore the authentication identity) fails, the connection will be closed as defunct so that a new connection will be created to take its place.
        Parameters:
        bindRequest - The bind request to be processed. It must not be null.
        Returns:
        The result of processing the provided bind operation.
        Throws:
        LDAPException - If the server rejects the bind request, or if a problem occurs while sending the request or reading the response.
      • getConnection

        @Nullable
        public LDAPConnection getConnection​(@NotNull
                                            java.lang.String host,
                                            int port)
        Attempts to retrieve a connection from the pool that is established to the specified server. Note that this method will only attempt to return an existing connection that is currently available, and will not create a connection or wait for any checked-out connections to be returned.
        Parameters:
        host - The address of the server to which the desired connection should be established. This must not be null, and this must exactly match the address provided for the initial connection or the ServerSet used to create the pool.
        port - The port of the server to which the desired connection should be established.
        Returns:
        A connection that is established to the specified server, or null if there are no available connections established to the specified server.
      • discardConnection

        public void discardConnection​(@NotNull
                                      LDAPConnection connection)
        Indicates that the provided connection should be removed from the pool, and that no new connection should be created to take its place. This may be used to shrink the pool if such functionality is desired.
        Parameters:
        connection - The connection to be discarded.
      • releaseAndReAuthenticateConnection

        public void releaseAndReAuthenticateConnection​(@NotNull
                                                       LDAPConnection connection)
        Performs a bind on the provided connection before releasing it back to the pool, so that it will be authenticated as the same user as newly-established connections. If newly-established connections are unauthenticated, then this method will perform an anonymous simple bind to ensure that the resulting connection is unauthenticated. Releases the provided connection back to this pool.
        Parameters:
        connection - The connection to be released back to the pool after being re-authenticated.
      • replaceDefunctConnection

        @NotNull
        public LDAPConnection replaceDefunctConnection​(@NotNull
                                                       LDAPConnection connection)
                                                throws LDAPException
        Releases the provided connection as defunct and creates a new connection to replace it, if possible, optionally connected to a different directory server instance than the instance with which the original connection was established.
        Specified by:
        replaceDefunctConnection in class AbstractConnectionPool
        Parameters:
        connection - The defunct connection to be replaced.
        Returns:
        The newly-created connection intended to replace the provided connection.
        Throws:
        LDAPException - If a problem is encountered while trying to create the new connection. Note that even if an exception is thrown, then the provided connection must have been properly released as defunct.
      • getOperationTypesToRetryDueToInvalidConnections

        @NotNull
        public java.util.Set<OperationTypegetOperationTypesToRetryDueToInvalidConnections()
        Retrieves the set of operation types for which operations should be retried if the initial attempt fails in a manner that indicates that the connection used to process the request may no longer be valid.
        Specified by:
        getOperationTypesToRetryDueToInvalidConnections in class AbstractConnectionPool
        Returns:
        The set of operation types for which operations should be retried if the initial attempt fails in a manner that indicates that the connection used to process the request may no longer be valid, or an empty set if retries should not be performed for any type of operation.
      • setRetryFailedOperationsDueToInvalidConnections

        public void setRetryFailedOperationsDueToInvalidConnections​(@Nullable
                                                                    java.util.Set<OperationType> operationTypes)
        Specifies the types of operations that should be retried on a newly-created connection if the initial attempt fails in a manner that indicates that the connection used to process the request may no longer be valid. Only a single retry will be attempted for any operation.

        Note that this only applies to methods used to process operations in the context pool (e.g., using methods that are part of LDAPInterface), and will not automatically be used for operations processed on connections checked out of the pool.
        Specified by:
        setRetryFailedOperationsDueToInvalidConnections in class AbstractConnectionPool
        Parameters:
        operationTypes - The types of operations for which to retry failed operations if they fail in a way that indicates the associated connection may no longer be usable. It may be null or empty to indicate that no types of operations should be retried.
      • setBindRequest

        public void setBindRequest​(@Nullable
                                   BindRequest bindRequest)
        Specifies the bind request that will be used to authenticate subsequent new connections that are established by this connection pool. The authentication state for existing connections will not be altered unless one of the bindAndRevertAuthentication or releaseAndReAuthenticateConnection methods are invoked on those connections.
        Parameters:
        bindRequest - The bind request that will be used to authenticate new connections that are established by this pool, or that will be applied to existing connections via the bindAndRevertAuthentication or releaseAndReAuthenticateConnection method. It may be null if new connections should be unauthenticated.
      • getServerSet

        @NotNull
        public ServerSet getServerSet()
        Retrieves the server set that should be used to establish new connections for use in this connection pool.
        Returns:
        The server set that should be used to establish new connections for use in this connection pool.
      • setServerSet

        public void setServerSet​(@Nullable
                                 ServerSet serverSet)
        Specifies the server set that should be used to establish new connections for use in this connection pool. Existing connections will not be affected.
        Parameters:
        serverSet - The server set that should be used to establish new connections for use in this connection pool. It must not be null.
      • setConnectionPoolName

        public void setConnectionPoolName​(@Nullable
                                          java.lang.String connectionPoolName)
        Specifies the user-friendly name that should be used for this connection pool. This name may be used in debugging to help identify the purpose of this connection pool. It will also be assigned to all connections associated with this connection pool.
        Specified by:
        setConnectionPoolName in class AbstractConnectionPool
        Parameters:
        connectionPoolName - The user-friendly name that should be used for this connection pool.
      • getCreateIfNecessary

        public boolean getCreateIfNecessary()
        Indicates whether the connection pool should create a new connection if one is requested when there are none available.
        Returns:
        true if a new connection should be created if none are available when a request is received, or false if an exception should be thrown to indicate that no connection is available.
      • setCreateIfNecessary

        public void setCreateIfNecessary​(boolean createIfNecessary)
        Specifies whether the connection pool should create a new connection if one is requested when there are none available.
        Parameters:
        createIfNecessary - Specifies whether the connection pool should create a new connection if one is requested when there are none available.
      • getMaxWaitTimeMillis

        public long getMaxWaitTimeMillis()
        Retrieves the maximum length of time in milliseconds to wait for a connection to become available when trying to obtain a connection from the pool.
        Returns:
        The maximum length of time in milliseconds to wait for a connection to become available when trying to obtain a connection from the pool, or zero to indicate that the pool should not block at all if no connections are available and that it should either create a new connection or throw an exception.
      • setMaxWaitTimeMillis

        public void setMaxWaitTimeMillis​(long maxWaitTime)
        Specifies the maximum length of time in milliseconds to wait for a connection to become available when trying to obtain a connection from the pool.
        Parameters:
        maxWaitTime - The maximum length of time in milliseconds to wait for a connection to become available when trying to obtain a connection from the pool. A value of zero should be used to indicate that the pool should not block at all if no connections are available and that it should either create a new connection or throw an exception.
      • getMaxConnectionAgeMillis

        public long getMaxConnectionAgeMillis()
        Retrieves the maximum length of time in milliseconds that a connection in this pool may be established before it is closed and replaced with another connection.
        Returns:
        The maximum length of time in milliseconds that a connection in this pool may be established before it is closed and replaced with another connection, or 0L if no maximum age should be enforced.
      • setMaxConnectionAgeMillis

        public void setMaxConnectionAgeMillis​(long maxConnectionAge)
        Specifies the maximum length of time in milliseconds that a connection in this pool may be established before it should be closed and replaced with another connection.
        Parameters:
        maxConnectionAge - The maximum length of time in milliseconds that a connection in this pool may be established before it should be closed and replaced with another connection. A value of zero indicates that no maximum age should be enforced.
      • getMaxDefunctReplacementConnectionAgeMillis

        @Nullable
        public java.lang.Long getMaxDefunctReplacementConnectionAgeMillis()
        Retrieves the maximum connection age that should be used for connections that were created in order to replace defunct connections. It is possible to define a custom maximum connection age for these connections to allow them to be closed and re-established more quickly to allow for a potentially quicker fail-back to a normal state. Note, that if this capability is to be used, then the maximum age for these connections should be long enough to allow the problematic server to become available again under normal circumstances (e.g., it should be long enough for at least a shutdown and restart of the server, plus some overhead for potentially performing routine maintenance while the server is offline, or a chance for an administrator to be made available that a server has gone down).
        Returns:
        The maximum connection age that should be used for connections that were created in order to replace defunct connections, a value of zero to indicate that no maximum age should be enforced, or null if the value returned by the getMaxConnectionAgeMillis() method should be used.
      • setMaxDefunctReplacementConnectionAgeMillis

        public void setMaxDefunctReplacementConnectionAgeMillis​(@Nullable
                                                                java.lang.Long maxDefunctReplacementConnectionAge)
        Specifies the maximum connection age that should be used for connections that were created in order to replace defunct connections. It is possible to define a custom maximum connection age for these connections to allow them to be closed and re-established more quickly to allow for a potentially quicker fail-back to a normal state. Note, that if this capability is to be used, then the maximum age for these connections should be long enough to allow the problematic server to become available again under normal circumstances (e.g., it should be long enough for at least a shutdown and restart of the server, plus some overhead for potentially performing routine maintenance while the server is offline, or a chance for an administrator to be made available that a server has gone down).
        Parameters:
        maxDefunctReplacementConnectionAge - The maximum connection age that should be used for connections that were created in order to replace defunct connections. It may be zero if no maximum age should be enforced for such connections, or it may be null if the value returned by the getMaxConnectionAgeMillis() method should be used.
      • checkConnectionAgeOnRelease

        public boolean checkConnectionAgeOnRelease()
        Indicates whether to check the age of a connection against the configured maximum connection age whenever it is released to the pool. By default, connection age is evaluated in the background using the health check thread, but it is also possible to configure the pool to additionally examine the age of a connection when it is returned to the pool.

        Performing connection age evaluation only in the background will ensure that connections are only closed and re-established in a single-threaded manner, which helps minimize the load against the target server, but only checks connections that are not in use when the health check thread is active. If the pool is configured to also evaluate the connection age when connections are returned to the pool, then it may help ensure that the maximum connection age is honored more strictly for all connections, but in busy applications may lead to cases in which multiple connections are closed and re-established simultaneously, which may increase load against the directory server. The setMinDisconnectIntervalMillis(long) method may be used to help mitigate the potential performance impact of closing and re-establishing multiple connections simultaneously.
        Returns:
        true if the connection pool should check connection age in both the background health check thread and when connections are released to the pool, or false if the connection age should only be checked by the background health check thread.
      • setCheckConnectionAgeOnRelease

        public void setCheckConnectionAgeOnRelease​(boolean checkConnectionAgeOnRelease)
        Specifies whether to check the age of a connection against the configured maximum connection age whenever it is released to the pool. By default, connection age is evaluated in the background using the health check thread, but it is also possible to configure the pool to additionally examine the age of a connection when it is returned to the pool.

        Performing connection age evaluation only in the background will ensure that connections are only closed and re-established in a single-threaded manner, which helps minimize the load against the target server, but only checks connections that are not in use when the health check thread is active. If the pool is configured to also evaluate the connection age when connections are returned to the pool, then it may help ensure that the maximum connection age is honored more strictly for all connections, but in busy applications may lead to cases in which multiple connections are closed and re-established simultaneously, which may increase load against the directory server. The setMinDisconnectIntervalMillis(long) method may be used to help mitigate the potential performance impact of closing and re-establishing multiple connections simultaneously.
        Parameters:
        checkConnectionAgeOnRelease - If true, this indicates that the connection pool should check connection age in both the background health check thread and when connections are released to the pool. If false, this indicates that the connection pool should check connection age only in the background health check thread.
      • getMinDisconnectIntervalMillis

        public long getMinDisconnectIntervalMillis()
        Retrieves the minimum length of time in milliseconds that should pass between connections closed because they have been established for longer than the maximum connection age.
        Returns:
        The minimum length of time in milliseconds that should pass between connections closed because they have been established for longer than the maximum connection age, or 0L if expired connections may be closed as quickly as they are identified.
      • setMinDisconnectIntervalMillis

        public void setMinDisconnectIntervalMillis​(long minDisconnectInterval)
        Specifies the minimum length of time in milliseconds that should pass between connections closed because they have been established for longer than the maximum connection age.
        Parameters:
        minDisconnectInterval - The minimum length of time in milliseconds that should pass between connections closed because they have been established for longer than the maximum connection age. A value less than or equal to zero indicates that no minimum time should be enforced.
      • setHealthCheck

        public void setHealthCheck​(@NotNull
                                   LDAPConnectionPoolHealthCheck healthCheck)
        Sets the health check implementation for this connection pool.
        Parameters:
        healthCheck - The health check implementation for this connection pool. It must not be null.
      • getHealthCheckIntervalMillis

        public long getHealthCheckIntervalMillis()
        Retrieves the length of time in milliseconds between periodic background health checks against the available connections in this pool.
        Specified by:
        getHealthCheckIntervalMillis in class AbstractConnectionPool
        Returns:
        The length of time in milliseconds between the periodic background health checks against the available connections in this pool.
      • setHealthCheckIntervalMillis

        public void setHealthCheckIntervalMillis​(long healthCheckInterval)
        Specifies the length of time in milliseconds between periodic background health checks against the available connections in this pool.
        Specified by:
        setHealthCheckIntervalMillis in class AbstractConnectionPool
        Parameters:
        healthCheckInterval - The length of time in milliseconds between periodic background health checks against the available connections in this pool. The provided value must be greater than zero.
      • trySynchronousReadDuringHealthCheck

        public boolean trySynchronousReadDuringHealthCheck()
        Indicates whether health check processing for connections operating in synchronous mode should include attempting to perform a read from each connection with a very short timeout. This can help detect unsolicited responses and unexpected connection closures in a more timely manner. This will be ignored for connections not operating in synchronous mode.
        Returns:
        true if health check processing for connections operating in synchronous mode should include a read attempt with a very short timeout, or false if not.
      • setTrySynchronousReadDuringHealthCheck

        public void setTrySynchronousReadDuringHealthCheck​(boolean trySynchronousReadDuringHealthCheck)
        Specifies whether health check processing for connections operating in synchronous mode should include attempting to perform a read from each connection with a very short timeout.
        Parameters:
        trySynchronousReadDuringHealthCheck - Indicates whether health check processing for connections operating in synchronous mode should include attempting to perform a read from each connection with a very short timeout.
      • doHealthCheck

        protected void doHealthCheck()
        Performs a health check against all connections currently available in this connection pool. This should only be invoked by the connection pool health check thread.
        Specified by:
        doHealthCheck in class AbstractConnectionPool
      • invokeHealthCheck

        @NotNull
        public LDAPConnectionPoolHealthCheckResult invokeHealthCheck​(@Nullable
                                                                     LDAPConnectionPoolHealthCheck healthCheck,
                                                                     boolean checkForExpiration)
        Invokes a synchronous one-time health-check against the connections in this pool that are not currently in use. This will be independent of any background health checking that may be automatically performed by the pool.
        Parameters:
        healthCheck - The health check to use. If this is null, then the pool's currently-configured health check (if any) will be used. If this is null and there is no health check configured for the pool, then only a basic set of checks.
        checkForExpiration - Indicates whether to check to see if any connections have been established for longer than the maximum connection age. If this is true then any expired connections will be closed and replaced with newly-established connections.
        Returns:
        An object with information about the result of the health check processing.
      • invokeHealthCheck

        @NotNull
        public LDAPConnectionPoolHealthCheckResult invokeHealthCheck​(@Nullable
                                                                     LDAPConnectionPoolHealthCheck healthCheck,
                                                                     boolean checkForExpiration,
                                                                     boolean checkMinConnectionGoal)
        Invokes a synchronous one-time health-check against the connections in this pool that are not currently in use. This will be independent of any background health checking that may be automatically performed by the pool.
        Parameters:
        healthCheck - The health check to use. If this is null, then the pool's currently-configured health check (if any) will be used. If this is null and there is no health check configured for the pool, then only a basic set of checks.
        checkForExpiration - Indicates whether to check to see if any connections have been established for longer than the maximum connection age. If this is true then any expired connections will be closed and replaced with newly-established connections.
        checkMinConnectionGoal - Indicates whether to check to see if the currently-available number of connections is less than the minimum available connection goal. If this is true the minimum available connection goal is greater than zero, and the number of currently-available connections is less than the goal, then this method will attempt to create enough new connections to reach the goal.
        Returns:
        An object with information about the result of the health check processing.
      • getCurrentAvailableConnections

        public int getCurrentAvailableConnections()
        Retrieves the number of connections that are currently available for use in this connection pool, if applicable.
        Specified by:
        getCurrentAvailableConnections in class AbstractConnectionPool
        Returns:
        The number of connections that are currently available for use in this connection pool, or -1 if that is not applicable for this type of connection pool.
      • getMaximumAvailableConnections

        public int getMaximumAvailableConnections()
        Retrieves the maximum number of connections to be maintained in this connection pool, which is the maximum number of available connections that should be available at any time, if applicable.
        Specified by:
        getMaximumAvailableConnections in class AbstractConnectionPool
        Returns:
        The number of connections to be maintained in this connection pool, or -1 if that is not applicable for this type of connection pool.
      • getMinimumAvailableConnectionGoal

        public int getMinimumAvailableConnectionGoal()
        Retrieves the goal for the minimum number of available connections that the pool should try to maintain for immediate use. If this goal is greater than zero, then the health checking process will attempt to create enough new connections to achieve this goal.
        Returns:
        The goal for the minimum number of available connections that the pool should try to maintain for immediate use, or zero if it will not try to maintain a minimum number of available connections.
      • setMinimumAvailableConnectionGoal

        public void setMinimumAvailableConnectionGoal​(int goal)
        Specifies the goal for the minimum number of available connections that the pool should try to maintain for immediate use. If this goal is greater than zero, then the health checking process will attempt to create enough new connections to achieve this goal.
        Parameters:
        goal - The goal for the minimum number of available connections that the pool should try to maintain for immediate use. A value less than or equal to zero indicates that the pool should not try to maintain a minimum number of available connections.
      • shrinkPool

        public void shrinkPool​(int connectionsToRetain)
        Attempts to reduce the number of connections available for use in the pool. Note that this will be a best-effort attempt to reach the desired number of connections, as other threads interacting with the connection pool may check out and/or release connections that cause the number of available connections to fluctuate.
        Parameters:
        connectionsToRetain - The number of connections that should be retained for use in the connection pool.
      • finalize

        protected void finalize()
                         throws java.lang.Throwable
        Closes this connection pool in the event that it becomes unreferenced.
        Overrides:
        finalize in class java.lang.Object
        Throws:
        java.lang.Throwable - If an unexpected problem occurs.
      • toString

        public void toString​(@NotNull
                             java.lang.StringBuilder buffer)
        Appends a string representation of this connection pool to the provided buffer.
        Specified by:
        toString in class AbstractConnectionPool
        Parameters:
        buffer - The buffer to which the string representation should be appended.