com.unboundid.ldap.sdk

Class ServerSet

java.lang.Object

com.unboundid.ldap.sdk.ServerSet

Direct Known Subclasses:

DNSSRVRecordServerSet, FailoverServerSet, FastestConnectServerSet, FewestConnectionsServerSet, RoundRobinDNSServerSet, RoundRobinServerSet, SingleServerSet

@Extensible
 @ThreadSafety(level=INTERFACE_THREADSAFE)
public abstract class ServerSet
extends java.lang.Object

This class defines an API that can be used to select between multiple directory servers when establishing a connection. Implementations are free to use any kind of logic that they desire when selecting the server to which the connection is to be established. They may also support the use of health checks to determine whether the created connections are suitable for use.

Implementations MUST be threadsafe to allow for multiple concurrent attempts to establish new connections.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	ServerSet() Creates a new instance of this server set.

Method Summary

Modifier and Type	Method and Description
protected void	associateConnectionWithThisServerSet(LDAPConnection connection) Updates the provided connection to indicate that it was created by this server set.
protected static void	doBindPostConnectAndHealthCheckProcessing(LDAPConnection connection, BindRequest bindRequest, PostConnectProcessor postConnectProcessor, LDAPConnectionPoolHealthCheck healthCheck) Performs the appropriate bind, post-connect, and health check processing for the provided connection, in the provided order.
abstract LDAPConnection	getConnection() Attempts to establish a connection to one of the directory servers in this server set.
LDAPConnection	getConnection(LDAPConnectionPoolHealthCheck healthCheck) Attempts to establish a connection to one of the directory servers in this server set, using the provided health check to further validate the connection.
protected void	handleConnectionClosed(LDAPConnection connection, java.lang.String host, int port, DisconnectType disconnectType, java.lang.String message, java.lang.Throwable cause) Performs any processing that may be required when the provided connection is closed.
boolean	includesAuthentication() Indicates whether connections created by this server set will be authenticated.
boolean	includesPostConnectProcessing() Indicates whether connections created by this server set will have post-connect processing performed.
void	shutDown() Shuts down this server set and frees any resources associated with it.
java.lang.String	toString() Retrieves a string representation of this server set.
void	toString(java.lang.StringBuilder buffer) Appends a string representation of this server set to the provided buffer.

Methods inherited from class java.lang.Object

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

Constructor Detail

ServerSet

protected ServerSet()

Creates a new instance of this server set.

Method Detail

includesAuthentication

public boolean includesAuthentication()

Indicates whether connections created by this server set will be authenticated.

Returns:

true if connections created by this server set will be authenticated, or false if not.

includesPostConnectProcessing

public boolean includesPostConnectProcessing()

Indicates whether connections created by this server set will have post-connect processing performed.

Returns:

true if connections created by this server set will have post-connect processing performed, or false if not.

getConnection

@NotNull
public abstract LDAPConnection getConnection()
                                               throws LDAPException

Attempts to establish a connection to one of the directory servers in this server set. The connection that is returned must be established. The includesAuthentication() must return true if and only if the connection will also be authenticated, and the includesPostConnectProcessing() method must return true if and only if pre-authentication and post-authentication post-connect processing will have been performed. The caller may determine the server to which the connection is established using the LDAPConnection.getConnectedAddress() and LDAPConnection.getConnectedPort() methods.

Returns:

An LDAPConnection object that is established to one of the servers in this server set.

Throws:

LDAPException - If it is not possible to establish a connection to any of the servers in this server set.

getConnection

@NotNull
public LDAPConnection getConnection(@Nullable
                                             LDAPConnectionPoolHealthCheck healthCheck)
                                      throws LDAPException

Attempts to establish a connection to one of the directory servers in this server set, using the provided health check to further validate the connection. The connection that is returned must be established. The includesAuthentication() must return true if and only if the connection will also be authenticated, and the includesPostConnectProcessing() method must return true if and only if pre-authentication and post-authentication post-connect processing will have been performed. The caller may determine the server to which the connection is established using the LDAPConnection.getConnectedAddress() and LDAPConnection.getConnectedPort() methods.

Parameters:

healthCheck - The health check to use to verify the health of the newly-created connection. It may be null if no additional health check should be performed. If it is non-null and this server set performs authentication, then the health check's ensureConnectionValidAfterAuthentication method will be invoked immediately after the bind operation is processed (regardless of whether the bind was successful or not). And regardless of whether this server set performs authentication, the health check's ensureNewConnectionValid method must be invoked on the connection to ensure that it is valid immediately before it is returned.

Returns:

An LDAPConnection object that is established to one of the servers in this server set.

Throws:

LDAPException - If it is not possible to establish a connection to any of the servers in this server set.

doBindPostConnectAndHealthCheckProcessing

protected static void doBindPostConnectAndHealthCheckProcessing(@NotNull
                                                                LDAPConnection connection,
                                                                @Nullable
                                                                BindRequest bindRequest,
                                                                @Nullable
                                                                PostConnectProcessor postConnectProcessor,
                                                                @Nullable
                                                                LDAPConnectionPoolHealthCheck healthCheck)
                                                         throws LDAPException

Performs the appropriate bind, post-connect, and health check processing for the provided connection, in the provided order. The processing performed will include:

1. If the provided postConnectProcessor is not null, then invoke its processPreAuthenticatedConnection method on the provided connection. If this method throws an LDAPException, then it will propagated up to the caller of this method.
2. If the provided bindRequest is not null, then authenticate the connection using that request. If the provided healthCheck is also not null, then invoke its ensureConnectionValidAfterAuthentication method on the connection, even if the bind was not successful. If the health check throws an LDAPException, then it will be propagated up to the caller of this method. If there is no health check or if it did not throw an exception but the bind attempt did throw an exception, then propagate that exception instead.
3. If the provided postConnectProcessor is not null, then invoke its processPostAuthenticatedConnection method on the provided connection. If this method throws an LDAPException, then it will propagated up to the caller of this method.
4. If the provided healthCheck is not null, then invoke its ensureNewConnectionValid method on the provided connection. If this method throws an LDAPException, then it will be propagated up to the caller of this method.

Parameters:

connection - The connection to be processed. It must not be null, and it must be established. Note that if an LDAPException is thrown by this method or anything that it calls, then the connection will have been closed before that exception has been propagated up to the caller of this method.

bindRequest - The bind request to use to authenticate the connection. It may be null if no authentication should be performed.

postConnectProcessor - The post-connect processor to invoke on the provided connection. It may be null if no post-connect processing should be performed.

healthCheck - The health check to use to verify the health of connection. It may be null if no health check processing should be performed.

Throws:

LDAPException - If a problem is encountered during any of the processing performed by this method. If an exception is thrown, then the provided connection will have been closed.

associateConnectionWithThisServerSet

protected final void associateConnectionWithThisServerSet(@NotNull
                                                          LDAPConnection connection)

Updates the provided connection to indicate that it was created by this server set.

Parameters:

connection - The connection to be updated to indicate it was created by this server set.

handleConnectionClosed

protected void handleConnectionClosed(@NotNull
                                      LDAPConnection connection,
                                      @NotNull
                                      java.lang.String host,
                                      int port,
                                      @NotNull
                                      DisconnectType disconnectType,
                                      @Nullable
                                      java.lang.String message,
                                      @Nullable
                                      java.lang.Throwable cause)

Performs any processing that may be required when the provided connection is closed. This will only be invoked for connections created by this server set, and only if the associateConnectionWithThisServerSet(com.unboundid.ldap.sdk.LDAPConnection) method was called on the connection when it was created by this server set.

Parameters:

connection - The connection that has been closed.

host - The address of the server to which the connection had been established.

port - The port of the server to which the connection had been established.

disconnectType - The disconnect type, which provides general information about the nature of the disconnect.

message - A message that may be associated with the disconnect. It may be null if no message is available.

cause - A Throwable that was caught and triggered the disconnect. It may be null if the disconnect was not triggered by a client-side exception or error.

shutDown

public void shutDown()

Shuts down this server set and frees any resources associated with it.

toString

@NotNull
public java.lang.String toString()

Retrieves a string representation of this server set.

Overrides:

toString in class java.lang.Object

Returns:

A string representation of this server set.

toString

public void toString(@NotNull
                     java.lang.StringBuilder buffer)

Appends a string representation of this server set to the provided buffer.

Parameters:

buffer - The buffer to which the string representation should be appended.