Class ReplicationBacklogLDAPConnectionPoolHealthCheck
- java.lang.Object
-
- com.unboundid.ldap.sdk.LDAPConnectionPoolHealthCheck
-
- com.unboundid.ldap.sdk.unboundidds.ReplicationBacklogLDAPConnectionPoolHealthCheck
-
- All Implemented Interfaces:
java.io.Serializable
@NotMutable @ThreadSafety(level=COMPLETELY_THREADSAFE) public final class ReplicationBacklogLDAPConnectionPoolHealthCheck extends LDAPConnectionPoolHealthCheck implements java.io.Serializable
This class provides an LDAP connection pool health check implementation that can be used to examine the replication backlog (reflecting changes that have been made in other replicas but have not yet been applied in the local instance) of a Ping Identity Directory Server instance. It can consider both the number of changes in the replication backlog and the age of the oldest outstanding change.
NOTE: This class, and other classes within the
com.unboundid.ldap.sdk.unboundidds
package structure, are only supported for use against Ping Identity, UnboundID, and Nokia/Alcatel-Lucent 8661 server products. These classes provide support for proprietary functionality or for external specifications that are not considered stable or mature enough to be guaranteed to work in an interoperable way with other types of LDAP servers.- See Also:
- Serialized Form
-
-
Constructor Summary
Constructors Constructor Description ReplicationBacklogLDAPConnectionPoolHealthCheck(boolean invokeOnCreate, boolean invokeAfterAuthentication, boolean invokeOnCheckout, boolean invokeOnRelease, boolean invokeForBackgroundChecks, boolean invokeOnException, long maxResponseTimeMillis, java.lang.String baseDN, java.lang.Long maxAllowedBacklogCount, java.lang.Long maxAllowedBacklogAgeMillis)
Creates a new instance of this LDAP connection pool health check with the provided information.
-
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.java.lang.String
getBaseDN()
Retrieves the base DN for the target replication domain.java.lang.Long
getMaxAllowedBacklogAgeMillis()
Retrieves the maximum length of time, in milliseconds, that a change may be contained in the replication backlog before a server will be considered unavailable.java.lang.Long
getMaxAllowedBacklogCount()
Retrieves the maximum number of changes that may be contained in the replication backlog before a server will be considered unavailable.long
getMaxResponseTimeMillis()
Retrieves the maximum length of time in milliseconds that this health check should wait for the target monitor entry to be returned.boolean
invokeAfterAuthentication()
Indicates whether this health check will check the replication backlog after a connection has been authenticated, including after authenticating a newly-created connection, as well as after calls to the connection pool'sbindAndRevertAuthentication
andreleaseAndReAuthenticateConnection
methods.boolean
invokeForBackgroundChecks()
Indicates whether this health check will check the replication backlog during periodic background health checks.boolean
invokeOnCheckout()
Indicates whether this health check will check the replication backlog whenever a connection is to be checked out for use.boolean
invokeOnCreate()
Indicates whether this health check will check the replication backlog whenever a new connection is created.boolean
invokeOnException()
Indicates whether this health check will check the replication backlog if an exception is caught while processing an operation on a connection.boolean
invokeOnRelease()
Indicates whether this health check will check the replication backlog whenever a connection is to be released back to the pool.void
toString(java.lang.StringBuilder buffer)
Appends a string representation of this LDAP connection pool health check to the provided buffer.-
Methods inherited from class com.unboundid.ldap.sdk.LDAPConnectionPoolHealthCheck
performPoolMaintenance, toString
-
-
-
-
Constructor Detail
-
ReplicationBacklogLDAPConnectionPoolHealthCheck
public ReplicationBacklogLDAPConnectionPoolHealthCheck(boolean invokeOnCreate, boolean invokeAfterAuthentication, boolean invokeOnCheckout, boolean invokeOnRelease, boolean invokeForBackgroundChecks, boolean invokeOnException, long maxResponseTimeMillis, @NotNull java.lang.String baseDN, @Nullable java.lang.Long maxAllowedBacklogCount, @Nullable java.lang.Long maxAllowedBacklogAgeMillis)
Creates a new instance of this LDAP connection pool health check with the provided information.- Parameters:
invokeOnCreate
- Indicates whether to test for the existence of the target entry whenever a new connection is created for use in the pool. Note that this check will be performed immediately after the connection has been established and before any attempt has been made to authenticate that connection.invokeAfterAuthentication
- Indicates whether to test for the existence of the target entry immediately after a connection has been authenticated. This includes immediately after a newly-created connection has been authenticated, after a call to the connection pool'sbindAndRevertAuthentication
method, and after a call to the connection pool'sreleaseAndReAuthenticateConnection
method. Note that even if this istrue
, the health check will only be performed if the provided bind result indicates that the bind was successful.invokeOnCheckout
- Indicates whether to test for the existence of the target entry immediately before a connection is checked out of the pool.invokeOnRelease
- Indicates whether to test for the existence of the target entry immediately after a connection has been released back to the pool.invokeForBackgroundChecks
- Indicates whether to test for the existence of the target entry during periodic background health checks.invokeOnException
- Indicates whether to test for the existence of the target entry if an exception is encountered when using the connection.maxResponseTimeMillis
- The maximum length of time, in milliseconds, to wait for the monitor entry to be retrieved. If the monitor entry cannot be retrieved within this length of time, the health check will fail. If the provided value is less than or equal to zero, then a default timeout of 5,000 milliseconds (5 seconds) will be used.baseDN
- The base DN for the target replication domain. This is typically the base DN for the backend containing the replicated data. It must not benull
.maxAllowedBacklogCount
- The maximum number of changes that may be contained in the replication backlog before a server will be considered unavailable. This may benull
if the backlog is to be evaluated only based on the age of the oldest outstanding change, but at least one ofmaxAllowedBacklogCount
andmaxAllowedBacklogAgeMillis
must be specified.maxAllowedBacklogAgeMillis
- The maximum length of time, in milliseconds, that a change may be contained in the replication backlog before a server will be considered unavailable. This may benull
if the backlog is to be evaluated only based on the number of outstanding changes, but at least one ofmaxAllowedBacklogCount
andmaxAllowedBacklogAgeMillis
must be specified.
-
-
Method Detail
-
ensureNewConnectionValid
public void ensureNewConnectionValid(@NotNull 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.- Overrides:
ensureNewConnectionValid
in classLDAPConnectionPoolHealthCheck
- 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(@NotNull LDAPConnection connection, @NotNull 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.- Overrides:
ensureConnectionValidAfterAuthentication
in classLDAPConnectionPoolHealthCheck
- 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(@NotNull 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.- Overrides:
ensureConnectionValidForCheckout
in classLDAPConnectionPoolHealthCheck
- 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(@NotNull 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.- Overrides:
ensureConnectionValidForRelease
in classLDAPConnectionPoolHealthCheck
- 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(@NotNull 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.- Overrides:
ensureConnectionValidForContinuedUse
in classLDAPConnectionPoolHealthCheck
- 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.
-
ensureConnectionValidAfterException
public void ensureConnectionValidAfterException(@NotNull LDAPConnection connection, @NotNull 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.- Overrides:
ensureConnectionValidAfterException
in classLDAPConnectionPoolHealthCheck
- 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.
-
invokeOnCreate
public boolean invokeOnCreate()
Indicates whether this health check will check the replication backlog whenever a new connection is created.- Returns:
true
if this health check will check the replication backlog whenever a new connection is created, orfalse
if not.
-
invokeAfterAuthentication
public boolean invokeAfterAuthentication()
Indicates whether this health check will check the replication backlog after a connection has been authenticated, including after authenticating a newly-created connection, as well as after calls to the connection pool'sbindAndRevertAuthentication
andreleaseAndReAuthenticateConnection
methods.- Returns:
true
if this health check will check the replication backlog whenever a connection has been authenticated, orfalse
if not.
-
invokeOnCheckout
public boolean invokeOnCheckout()
Indicates whether this health check will check the replication backlog whenever a connection is to be checked out for use.- Returns:
true
if this health check will check the replication backlog whenever a connection is to be checked out, orfalse
if not.
-
invokeOnRelease
public boolean invokeOnRelease()
Indicates whether this health check will check the replication backlog whenever a connection is to be released back to the pool.- Returns:
true
if this health check will check the replication backlog whenever a connection is to be released, orfalse
if not.
-
invokeForBackgroundChecks
public boolean invokeForBackgroundChecks()
Indicates whether this health check will check the replication backlog during periodic background health checks.- Returns:
true
if this health check will check the replication backlog during periodic background health checks, orfalse
if not.
-
invokeOnException
public boolean invokeOnException()
Indicates whether this health check will check the replication backlog if an exception is caught while processing an operation on a connection.- Returns:
true
if this health check will check the replication backlog whenever an exception is caught, orfalse
if not.
-
getMaxResponseTimeMillis
public long getMaxResponseTimeMillis()
Retrieves the maximum length of time in milliseconds that this health check should wait for the target monitor entry to be returned.- Returns:
- The maximum length of time in milliseconds that this health check should wait for the target monitor entry to be returned.
-
getBaseDN
@NotNull public java.lang.String getBaseDN()
Retrieves the base DN for the target replication domain.- Returns:
- The base DN for the target replication domain.
-
getMaxAllowedBacklogCount
@Nullable public java.lang.Long getMaxAllowedBacklogCount()
Retrieves the maximum number of changes that may be contained in the replication backlog before a server will be considered unavailable.- Returns:
- The maximum number of changes that may be contained in the
replication backlog before a server will be considered
unavailable, or
null
if the backlog will be evaluated only based on the age of the oldest outstanding change.
-
getMaxAllowedBacklogAgeMillis
@Nullable public java.lang.Long getMaxAllowedBacklogAgeMillis()
Retrieves the maximum length of time, in milliseconds, that a change may be contained in the replication backlog before a server will be considered unavailable.- Returns:
- The maximum length of time, in milliseconds, that a change may be
contained in the replication backlog before a server will be
considered unavailable, or
null
if the backlog will be evaluated only based on the number of outstanding changes.
-
toString
public void toString(@NotNull java.lang.StringBuilder buffer)
Appends a string representation of this LDAP connection pool health check to the provided buffer.- Overrides:
toString
in classLDAPConnectionPoolHealthCheck
- Parameters:
buffer
- The buffer to which the information should be appended.
-
-