Package 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 theLDAPConnectionPool
class, as is the manner in which applications should interact with it. See the class-level documentation for theLDAPConnectionPool
class for additional information and examples.
One difference between this connection pool implementation and that provided by theLDAPConnectionPool
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 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
All Methods Instance Methods Concrete Methods Modifier and Type Method 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.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
-
-
-
-
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 benull
, 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 benull
, 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 benull
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 benull
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 benull
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 benull
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 benull
.
-
-
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 interfacejava.lang.AutoCloseable
- Specified by:
close
in interfacejava.io.Closeable
- Specified by:
close
in interfaceFullLDAPInterface
- Specified by:
close
in classAbstractConnectionPool
-
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 classAbstractConnectionPool
- 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 classAbstractConnectionPool
- Returns:
true
if this connection pool has been closed, orfalse
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 benull
.- 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 classAbstractConnectionPool
- 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 classAbstractConnectionPool
- 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 classAbstractConnectionPool
- 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 classAbstractConnectionPool
- 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 classAbstractConnectionPool
- 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 ofLDAPInterface
), and will not automatically be used for operations processed on connections checked out of the pool.- Specified by:
setRetryFailedOperationsDueToInvalidConnections
in classAbstractConnectionPool
- 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 benull
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 thebindAndRevertAuthentication
orreleaseAndReAuthenticateConnection
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 thebindAndRevertAuthentication
orreleaseAndReAuthenticateConnection
method. It may benull
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 benull
.
-
getConnectionPoolName
@Nullable public java.lang.String getConnectionPoolName()
Retrieves the user-friendly name that has been assigned to this connection pool.- Specified by:
getConnectionPoolName
in classAbstractConnectionPool
- 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 classAbstractConnectionPool
- 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 classAbstractConnectionPool
- 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 benull
.
-
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 classAbstractConnectionPool
- 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 classAbstractConnectionPool
- 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 classAbstractConnectionPool
-
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 classAbstractConnectionPool
- 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 classAbstractConnectionPool
- 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 classAbstractConnectionPool
- 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 classjava.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 classAbstractConnectionPool
- Parameters:
buffer
- The buffer to which the string representation should be appended.
-
-