com.unboundid.ldap.sdk

Class LDAPThreadLocalConnectionPool

java.lang.Object

com.unboundid.ldap.sdk.AbstractConnectionPool

com.unboundid.ldap.sdk.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 Summary

Constructors

Constructor and Description
LDAPThreadLocalConnectionPool(LDAPConnection connection) Creates a new LDAP thread-local connection pool in which all connections will be clones of the provided connection.
LDAPThreadLocalConnectionPool(LDAPConnection connection, PostConnectProcessor postConnectProcessor) Creates a new LDAP thread-local connection pool in which all connections will be clones of the provided connection.
LDAPThreadLocalConnectionPool(ServerSet serverSet, BindRequest bindRequest) Creates a new LDAP thread-local connection pool which will use the provided server set and bind request for creating new connections.
LDAPThreadLocalConnectionPool(ServerSet serverSet, BindRequest bindRequest, PostConnectProcessor postConnectProcessor) Creates a new LDAP thread-local connection pool which will use the provided server set and bind request for creating new connections.

Method Summary

Modifier and Type	Method and Description
BindResult	bindAndRevertAuthentication(BindRequest bindRequest) 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.
BindResult	bindAndRevertAuthentication(java.lang.String bindDN, java.lang.String password, Control... controls) 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.
void	close() Closes this connection pool.
void	close(boolean unbind, int numThreads) Closes this connection pool, optionally using multiple threads to close the connections in parallel.
protected void	doHealthCheck() Performs a health check against all connections currently available in this connection pool.
protected void	finalize() Closes this connection pool in the event that it becomes unreferenced.
LDAPConnection	getConnection() Retrieves an LDAP connection from the pool.
java.lang.String	getConnectionPoolName() Retrieves the user-friendly name that has been assigned to this connection pool.
LDAPConnectionPoolStatistics	getConnectionPoolStatistics() Retrieves the set of statistics maintained for this LDAP connection pool.
int	getCurrentAvailableConnections() Retrieves the number of connections that are currently available for use in this connection pool, if applicable.
LDAPConnectionPoolHealthCheck	getHealthCheck() Retrieves the health check implementation for this connection pool.
long	getHealthCheckIntervalMillis() Retrieves the length of time in milliseconds between periodic background health checks against the available connections in this pool.
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.
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.
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.
java.util.Set<OperationType>	getOperationTypesToRetryDueToInvalidConnections() 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.
ServerSet	getServerSet() Retrieves the server set that should be used to establish new connections for use in this connection pool.
boolean	isClosed() Indicates whether this connection pool has been closed.
void	releaseAndReAuthenticateConnection(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.
void	releaseConnection(LDAPConnection connection) Releases the provided connection back to this pool.
void	releaseDefunctConnection(LDAPConnection connection) Indicates that the provided connection is no longer in use, but is also no longer fit for use.
LDAPConnection	replaceDefunctConnection(LDAPConnection connection) 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.
void	setBindRequest(BindRequest bindRequest) Specifies the bind request that will be used to authenticate subsequent new connections that are established by this connection pool.
void	setConnectionPoolName(java.lang.String connectionPoolName) Specifies the user-friendly name that should be used for this connection pool.
void	setHealthCheck(LDAPConnectionPoolHealthCheck healthCheck) Sets the health check implementation for this connection pool.
void	setHealthCheckIntervalMillis(long healthCheckInterval) Specifies the length of time in milliseconds between periodic background health checks against the available connections in this pool.
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.
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.
void	setRetryFailedOperationsDueToInvalidConnections(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.
void	setServerSet(ServerSet serverSet) Specifies the server set that should be used to establish new connections for use in this connection pool.
void	toString(java.lang.StringBuilder buffer) Appends a string representation of this connection pool to the provided buffer.

Methods inherited from class com.unboundid.ldap.sdk.AbstractConnectionPool

add, add, add, add, add, add, bind, bind, compare, compare, compare, delete, delete, delete, getEntry, getEntry, getRootDSE, getSchema, getSchema, modify, modify, modify, modify, modify, modify, modifyDN, modifyDN, modifyDN, modifyDN, processExtendedOperation, processExtendedOperation, processExtendedOperation, processRequests, processRequestsAsync, releaseConnectionAfterException, retryFailedOperationsDueToInvalidConnections, search, search, search, search, search, search, search, search, search, search, searchForEntry, searchForEntry, searchForEntry, searchForEntry, searchForEntry, searchForEntry, setRetryFailedOperationsDueToInvalidConnections, toString

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

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 FullLDAPInterface

Specified by:

close in interface java.io.Closeable

Specified by:

close in interface java.lang.AutoCloseable

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

@NotNull
public LDAPConnection getConnection()
                                      throws LDAPException

Retrieves an LDAP connection from the pool.

Specified by:

getConnection in class AbstractConnectionPool

Returns:

The LDAP connection taken from the pool.

Throws:

LDAPException - If no connection is available, or a problem occurs while creating a new connection to return.

releaseConnection

public void releaseConnection(@NotNull
                              LDAPConnection connection)

Releases the provided connection back to this pool.

Specified by:

releaseConnection in class AbstractConnectionPool

Parameters:

connection - The connection to be released back to the pool.

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.

releaseDefunctConnection

public void releaseDefunctConnection(@NotNull
                                     LDAPConnection connection)

Indicates that the provided connection is no longer in use, but is also no longer fit for use. The provided connection will be terminated and a new connection will be created and added to the pool in its place.

Specified by:

releaseDefunctConnection in class AbstractConnectionPool

Parameters:

connection - The defunct connection being released.

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<OperationType> getOperationTypesToRetryDueToInvalidConnections()

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(@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.

getConnectionPoolName

@Nullable
public java.lang.String getConnectionPoolName()

Retrieves the user-friendly name that has been assigned to this connection pool.

Specified by:

getConnectionPoolName in class AbstractConnectionPool

Returns:

The user-friendly name that has been assigned to this connection pool, or null if none has been assigned.

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.

getHealthCheck

@NotNull
public LDAPConnectionPoolHealthCheck getHealthCheck()

Retrieves the health check implementation for this connection pool.

Specified by:

getHealthCheck in class AbstractConnectionPool

Returns:

The health check implementation for this connection pool.

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.

getConnectionPoolStatistics

@NotNull
public LDAPConnectionPoolStatistics getConnectionPoolStatistics()

Retrieves the set of statistics maintained for this LDAP connection pool.

Specified by:

getConnectionPoolStatistics in class AbstractConnectionPool

Returns:

The set of statistics maintained for this LDAP 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.