com.unboundid.ldap.sdk
Class GetEntryLDAPConnectionPoolHealthCheck

java.lang.Object
  extended by com.unboundid.ldap.sdk.LDAPConnectionPoolHealthCheck
      extended by com.unboundid.ldap.sdk.GetEntryLDAPConnectionPoolHealthCheck
All Implemented Interfaces:
java.io.Serializable

@NotMutable
@ThreadSafety(level=COMPLETELY_THREADSAFE)
public final class GetEntryLDAPConnectionPoolHealthCheck
extends LDAPConnectionPoolHealthCheck
implements java.io.Serializable

This class provides an LDAP connection pool health check implementation that may be used to check the health of the associated server by verifying that a specified entry can be retrieved in an acceptable period of time. If the entry cannot be retrieved (either because it does not exist, or because an error occurs while attempting to retrieve it), or if it takes too long to retrieve the entry, then the associated connection will be classified as unavailable.

It is possible to control under which conditions an attempt should be made to retrieve the target entry, and also to specify a maximum acceptable response time. For best results, the target entry should be available to be retrieved by a client with any authentication state.

See Also:
Serialized Form

Constructor Summary
GetEntryLDAPConnectionPoolHealthCheck(java.lang.String entryDN, long maxResponseTime, boolean invokeOnCreate, boolean invokeOnCheckout, boolean invokeOnRelease, boolean invokeForBackgroundChecks, boolean invokeOnException)
          Creates a new instance of this get entry LDAP connection pool health check.
 
Method Summary
 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 getEntryDN()
          Retrieves the DN of the entry that will be retrieved when performing the health checks.
 long getMaxResponseTimeMillis()
          Retrieves the maximum length of time in milliseconds that this health check should wait for the entry to be returned.
 boolean invokeForBackgroundChecks()
          Indicates whether this health check will test for the existence of the target entry during periodic background health checks.
 boolean invokeOnCheckout()
          Indicates whether this health check will test for the existence of the target entry whenever a connection is to be checked out for use.
 boolean invokeOnCreate()
          Indicates whether this health check will test for the existence of the target entry whenever a new connection is created.
 boolean invokeOnException()
          Indicates whether this health check will test for the existence of the target entry if an exception is caught while processing an operation on a connection.
 boolean invokeOnRelease()
          Indicates whether this health check will test for the existence of the target entry 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
toString
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

GetEntryLDAPConnectionPoolHealthCheck

public GetEntryLDAPConnectionPoolHealthCheck(java.lang.String entryDN,
                                             long maxResponseTime,
                                             boolean invokeOnCreate,
                                             boolean invokeOnCheckout,
                                             boolean invokeOnRelease,
                                             boolean invokeForBackgroundChecks,
                                             boolean invokeOnException)
Creates a new instance of this get entry LDAP connection pool health check.

Parameters:
entryDN - The DN of the entry to retrieve from the target server. If this is null, then the server's root DSE will be used.
maxResponseTime - The maximum length of time in milliseconds that should be allowed when attempting to retrieve the entry. If the provided value is less than or equal to zero, then the default value of 30000 milliseconds (30 seconds) will be used.
invokeOnCreate - Indicates whether to test for the existence of the target entry whenever a new connection is created for use in the pool.
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.
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 either ServerSet 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.

Overrides:
ensureNewConnectionValid in class LDAPConnectionPoolHealthCheck
Parameters:
connection - The connection to be examined.
Throws:
LDAPException - If a problem is detected which suggests that the provided connection is not suitable for use.

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 the LDAPConnectionPool.getConnection() method before handing out a connection. This method should return normally if the connection is believed to be valid, or should throw an LDAPException if a problem is detected.

Overrides:
ensureConnectionValidForCheckout in class LDAPConnectionPoolHealthCheck
Parameters:
connection - The connection to be examined.
Throws:
LDAPException - If a problem is detected which 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 the LDAPConnectionPool.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 an LDAPException if a problem is detected.

Overrides:
ensureConnectionValidForRelease in class LDAPConnectionPoolHealthCheck
Parameters:
connection - The connection to be examined.
Throws:
LDAPException - If a problem is detected which 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 an LDAPException if a problem is detected.

Overrides:
ensureConnectionValidForContinuedUse in class LDAPConnectionPoolHealthCheck
Parameters:
connection - The connection to be examined.
Throws:
LDAPException - If a problem is detected which suggests that the provided connection is not suitable for use.

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 the AbstractConnectionPool.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 an LDAPException if a problem is detected.

Overrides:
ensureConnectionValidAfterException in class LDAPConnectionPoolHealthCheck
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 which suggests that the provided connection is not suitable for use.

getEntryDN

public java.lang.String getEntryDN()
Retrieves the DN of the entry that will be retrieved when performing the health checks.

Returns:
The DN of the entry that will be retrieved when performing the health checks.

getMaxResponseTimeMillis

public long getMaxResponseTimeMillis()
Retrieves the maximum length of time in milliseconds that this health check should wait for the entry to be returned.

Returns:
The maximum length of time in milliseconds that this health check should wait for the entry to be returned.

invokeOnCreate

public boolean invokeOnCreate()
Indicates whether this health check will test for the existence of the target entry whenever a new connection is created.

Returns:
true if this health check will test for the existence of the target entry whenever a new connection is created, or false if not.

invokeOnCheckout

public boolean invokeOnCheckout()
Indicates whether this health check will test for the existence of the target entry whenever a connection is to be checked out for use.

Returns:
true if this health check will test for the existence of the target entry whenever a connection is to be checked out, or false if not.

invokeOnRelease

public boolean invokeOnRelease()
Indicates whether this health check will test for the existence of the target entry whenever a connection is to be released back to the pool.

Returns:
true if this health check will test for the existence of the target entry whenever a connection is to be released, or false if not.

invokeForBackgroundChecks

public boolean invokeForBackgroundChecks()
Indicates whether this health check will test for the existence of the target entry during periodic background health checks.

Returns:
true if this health check will test for the existence of the target entry during periodic background health checks, or false if not.

invokeOnException

public boolean invokeOnException()
Indicates whether this health check will test for the existence of the target entry if an exception is caught while processing an operation on a connection.

Returns:
true if this health check will test for the existence of the target entry whenever an exception is caught, or false if not.

toString

public void toString(java.lang.StringBuilder buffer)
Appends a string representation of this LDAP connection pool health check to the provided buffer.

Overrides:
toString in class LDAPConnectionPoolHealthCheck
Parameters:
buffer - The buffer to which the information should be appended.