Class LDAPThreadLocalConnectionPool

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

    @ThreadSafety(level=COMPLETELY_THREADSAFE)
    public final class LDAPThreadLocalConnectionPool
    extends AbstractConnectionPool
    This class provides an implementation of an LDAP connection pool which maintains a dedicated connection for each thread using the connection pool. Connections will be created on an on-demand basis, so that if a thread attempts to use this connection pool for the first time then a new connection will be created by that thread. This implementation eliminates the need to determine how best to size the connection pool, and it can eliminate contention among threads when trying to access a shared set of connections. All connections will be properly closed when the connection pool itself is closed, but if any thread which had previously used the connection pool stops running before the connection pool is closed, then the connection associated with that thread will also be closed by the Java finalizer.

    If a thread obtains a connection to this connection pool, then that connection should not be made available to any other thread. Similarly, if a thread attempts to check out multiple connections from the pool, then the same connection instance will be returned each time.

    The capabilities offered by this class are generally the same as those provided by the LDAPConnectionPool class, as is the manner in which applications should interact with it. See the class-level documentation for the LDAPConnectionPool class for additional information and examples.

    One difference between this connection pool implementation and that provided by the LDAPConnectionPool class is that this implementation does not currently support periodic background health checks. You can define health checks that will be invoked when a new connection is created, just before it is checked out for use, just after it is released, and if an error occurs while using the connection, but it will not maintain a separate background thread
    • Constructor Detail

      • LDAPThreadLocalConnectionPool

        public LDAPThreadLocalConnectionPool​(@NotNull
                                             LDAPConnection connection)
                                      throws LDAPException
        Creates a new LDAP thread-local connection pool in which all connections will be 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.
        Throws:
        LDAPException - If the provided connection cannot be used to initialize the pool. If this is thrown, then all connections associated with the pool (including the one provided as an argument) will be closed.
      • LDAPThreadLocalConnectionPool

        public LDAPThreadLocalConnectionPool​(@NotNull
                                             LDAPConnection connection,
                                             @Nullable
                                             PostConnectProcessor postConnectProcessor)
                                      throws LDAPException
        Creates a new LDAP thread-local connection pool in which all connections will be 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.
        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. If this is thrown, then all connections associated with the pool (including the one provided as an argument) will be closed.
      • LDAPThreadLocalConnectionPool

        public LDAPThreadLocalConnectionPool​(@NotNull
                                             ServerSet serverSet,
                                             @Nullable
                                             BindRequest bindRequest)
        Creates a new LDAP thread-local connection pool which will use the provided server set and bind request for creating new connections.
        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.
      • LDAPThreadLocalConnectionPool

        public LDAPThreadLocalConnectionPool​(@NotNull
                                             ServerSet serverSet,
                                             @Nullable
                                             BindRequest bindRequest,
                                             @Nullable
                                             PostConnectProcessor postConnectProcessor)
        Creates a new LDAP thread-local connection pool which will use the provided server set and bind request for creating new connections.
        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.
        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.
    • 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.
      • 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.
      • setServerSet

        public void setServerSet​(@NotNull
                                 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.
      • 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.
      • 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.
      • 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
      • 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.
      • 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.