Package com.unboundid.ldap.sdk
Class LDAPConnectionPoolHealthCheck
- java.lang.Object
-
- com.unboundid.ldap.sdk.LDAPConnectionPoolHealthCheck
-
- Direct Known Subclasses:
AggregateLDAPConnectionPoolHealthCheck
,GetEntryLDAPConnectionPoolHealthCheck
,PasswordExpirationLDAPConnectionPoolHealthCheck
,PruneUnneededConnectionsLDAPConnectionPoolHealthCheck
,ReportBindResultLDAPConnectionPoolHealthCheck
@Extensible @ThreadSafety(level=INTERFACE_THREADSAFE) public class LDAPConnectionPoolHealthCheck extends java.lang.Object
This class provides an API that may be used to determine whether connections associated with a connection pool are valid and suitable for use. It provides the ability to check the validity of a connection at the following times:- Whenever a new connection is created for use in the pool, the
ensureNewConnectionValid(LDAPConnection)
method will be called before making that connection available. The default implementation provided in this class does not perform any kind of processing, but subclasses may override this behavior if desired. - Whenever a connection is checked out from the pool (including
connections checked out internally for operations performed in the
pool), the
ensureConnectionValidForCheckout(LDAPConnection)
method will be called. The default implementation provided in this class does not perform any kind of processing, but subclasses may override this behavior if desired. - Whenever a connection is released back to the pool (including
connections checked out internally for operations performed in the
pool), the
ensureConnectionValidForRelease(LDAPConnection)
method will be called. The default implementation provided in this class does not perform any kind of processing, but subclasses may override this behavior if desired. - The
ensureConnectionValidForContinuedUse(LDAPConnection)
method will be invoked periodically by a background thread created by the connection pool to determine whether available connections within the pool are still valid. The default implementation provided in this class does not perform any kind of processing, but subclasses may override this behavior if desired. - The
ensureConnectionValidAfterException(com.unboundid.ldap.sdk.LDAPConnection, com.unboundid.ldap.sdk.LDAPException)
method may be invoked if an exception is caught while processing an operation with a connection that is part of a connection pool. The default implementation provided in this class only examines the result code of the provided exception and uses theResultCode.isConnectionUsable(ResultCode)
method to make the determination, but subclasses may override this behavior if desired.
ensureNewConnectionValid(LDAPConnection)
method will be invoked on unauthenticated connections, and the remaining health check methods will be invoked using whatever credentials are assigned to connections in the associated connection pool.
-
-
Constructor Summary
Constructors Constructor Description LDAPConnectionPoolHealthCheck()
Creates a new instance of this LDAP connection pool health check.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description void
ensureConnectionValidAfterAuthentication(LDAPConnection connection, BindResult bindResult)
Performs any desired processing to determine whether the provided connection is valid after processing a bind operation with the provided result.void
ensureConnectionValidAfterException(LDAPConnection connection, LDAPException exception)
Indicates whether the provided connection may still be considered valid after an attempt to process an operation yielded the given exception.void
ensureConnectionValidForCheckout(LDAPConnection connection)
Performs any desired processing to determine whether the provided connection is available to be checked out and used for processing operations.void
ensureConnectionValidForContinuedUse(LDAPConnection connection)
Performs any desired processing to determine whether the provided connection is valid and should continue to be made available for processing operations.void
ensureConnectionValidForRelease(LDAPConnection connection)
Performs any desired processing to determine whether the provided connection is valid and should be released back to the pool to be used for processing other operations.void
ensureNewConnectionValid(LDAPConnection connection)
Performs any desired processing to determine whether the provided new connection is available to be checked out and used for processing operations.void
performPoolMaintenance(AbstractConnectionPool pool)
Performs any processing that may be appropriate on an ongoing basis for the connection pool that is not related to the pool itself rather than any individual connection.java.lang.String
toString()
Retrieves a string representation of this LDAP connection pool health check.void
toString(java.lang.StringBuilder buffer)
Appends a string representation of this LDAP connection pool health check to the provided buffer.
-
-
-
Constructor Detail
-
LDAPConnectionPoolHealthCheck
public LDAPConnectionPoolHealthCheck()
Creates a new instance of this LDAP connection pool health check.
-
-
Method Detail
-
ensureNewConnectionValid
public void ensureNewConnectionValid(LDAPConnection connection) throws LDAPException
Performs any desired processing to determine whether the provided new connection is available to be checked out and used for processing operations. This method will be invoked by eitherServerSet
used by the connection pool (if it supports enhanced health checking) or by the connection pool itself at the time that a new connection is created. No authentication will have been performed on this connection at the time the health check is invoked.- Parameters:
connection
- The connection to be examined.- Throws:
LDAPException
- If a problem is detected that suggests that the provided connection is not suitable for use.
-
ensureConnectionValidAfterAuthentication
public void ensureConnectionValidAfterAuthentication(LDAPConnection connection, BindResult bindResult) throws LDAPException
Performs any desired processing to determine whether the provided connection is valid after processing a bind operation with the provided result.
This method will be invoked under the following circumstances:-
If you create a connection pool with a
ServerSet
and a non-null
BindRequest
, then this health check method will be invoked for every new connection created by the pool after processing thatBindRequest
on the connection. If you create a connection pool with aServerSet
but anull
BindRequest
, then no authentication will be attempted (and therefore this health check method will not be invoked for) newly-created connections. -
If you create a connection pool with an
LDAPConnection
after having performed a bind operation on that connection, then every new connection created by the pool will attempt to perform the same type of bind operation and this health check method will be invoked after that bind attempt has completed. If you create a connection pool with anLDAPConnection
that has not been authenticated, then no authentication will be attempted (and therefore this health check method will not be invoked for) newly-created connections. -
If you call a connection pool's
bindAndRevertAuthentication
method, then this health check method will be called after the second bind operation (the one used to revert authentication) has completed. In this case, this health check method will be called even if the connection pool was created with anull
BindRequest
or with an unauthenticatedLDAPConnection
. In that case, the bind operation used to revert authentication will be aSimpleBindRequest
with an empty DN and password. -
If you call a connection pool's
releaseAndReAuthenticateConnection
method, then this health check method will be called after the bind operation has completed. As withbindAndRevertAuthentication
, this health check method will be called even if the connection pool was created with anull
BindRequest
or with an unauthenticatedLDAPConnection
.
Note that this health check method may be invoked even if the bind attempt was not successful. This is useful because it allows the health check to intercept a failed authentication attempt and differentiate it from other types of failures in the course of trying to create or check out a connection. In the event that it is invoked with aBindResult
that has a result code other thanResultCode.SUCCESS
, if this method throws an exception then that exception will be propagated to the caller. If this method does not throw an exception when provided with a non-SUCCESS
result, then the connection pool itself will throw an exception using the information in the bind result.- Parameters:
connection
- The connection to be examined.bindResult
- The bind result obtained from the authentication process.- Throws:
LDAPException
- If a problem is detected that suggests that the provided connection is not suitable for use.
-
If you create a connection pool with a
-
ensureConnectionValidForCheckout
public void ensureConnectionValidForCheckout(LDAPConnection connection) throws LDAPException
Performs any desired processing to determine whether the provided connection is available to be checked out and used for processing operations. This method will be invoked by theLDAPConnectionPool.getConnection()
method before handing out a connection. This method should return normally if the connection is believed to be valid, or should throw anLDAPException
if a problem is detected.- Parameters:
connection
- The connection to be examined.- Throws:
LDAPException
- If a problem is detected that suggests that the provided connection is not suitable for use.
-
ensureConnectionValidForRelease
public void ensureConnectionValidForRelease(LDAPConnection connection) throws LDAPException
Performs any desired processing to determine whether the provided connection is valid and should be released back to the pool to be used for processing other operations. This method will be invoked by theLDAPConnectionPool.releaseConnection(LDAPConnection)
method before making the connection available for use in processing other operations. This method should return normally if the connection is believed to be valid, or should throw anLDAPException
if a problem is detected.- Parameters:
connection
- The connection to be examined.- Throws:
LDAPException
- If a problem is detected that suggests that the provided connection is not suitable for use.
-
ensureConnectionValidForContinuedUse
public void ensureConnectionValidForContinuedUse(LDAPConnection connection) throws LDAPException
Performs any desired processing to determine whether the provided connection is valid and should continue to be made available for processing operations. This method will be periodically invoked by a background thread used to test availability of connections within the pool. This method should return normally if the connection is believed to be valid, or should throw anLDAPException
if a problem is detected.- Parameters:
connection
- The connection to be examined.- Throws:
LDAPException
- If a problem is detected that suggests that the provided connection is not suitable for use.
-
performPoolMaintenance
public void performPoolMaintenance(AbstractConnectionPool pool)
Performs any processing that may be appropriate on an ongoing basis for the connection pool that is not related to the pool itself rather than any individual connection. This method will be invoked by the pool'sLDAPConnectionPoolHealthCheckThread
at an interval specified by the pool'sAbstractConnectionPool.getHealthCheckIntervalMillis()
method. This method will be invoked after all other periodic processing (for example, after callingensureConnectionValidForContinuedUse(com.unboundid.ldap.sdk.LDAPConnection)
on each available connection, if appropriate for the pool implementation) has been performed during the interval.- Parameters:
pool
- The connection pool on which to perform maintenance.
-
ensureConnectionValidAfterException
public void ensureConnectionValidAfterException(LDAPConnection connection, LDAPException exception) throws LDAPException
Indicates whether the provided connection may still be considered valid after an attempt to process an operation yielded the given exception. This method will be invoked by theAbstractConnectionPool.releaseConnectionAfterException(com.unboundid.ldap.sdk.LDAPConnection, com.unboundid.ldap.sdk.LDAPException)
method, and it may also be manually invoked by external callers if an exception is encountered while processing an operation on a connection checked out from the pool. It may make a determination based solely on the provided exception, or it may also attempt to use the provided connection to further test its validity. This method should return normally if the connection is believed to be valid, or should throw anLDAPException
if a problem is detected.- Parameters:
connection
- The connection to be examined.exception
- The exception that was caught while processing an operation on the connection.- Throws:
LDAPException
- If a problem is detected that suggests that the provided connection is not suitable for use.
-
toString
public final java.lang.String toString()
Retrieves a string representation of this LDAP connection pool health check.- Overrides:
toString
in classjava.lang.Object
- Returns:
- A string representation of this LDAP connection pool health check.
-
toString
public void toString(java.lang.StringBuilder buffer)
Appends a string representation of this LDAP connection pool health check to the provided buffer.- Parameters:
buffer
- The buffer to which the information should be appended.
-
-