com.unboundid.ldap.sdk

Class RoundRobinServerSet

java.lang.Object

com.unboundid.ldap.sdk.ServerSet

com.unboundid.ldap.sdk.RoundRobinServerSet

@NotMutable
 @ThreadSafety(level=COMPLETELY_THREADSAFE)
public final class RoundRobinServerSet
extends ServerSet

This class provides a server set implementation that will use a round-robin algorithm to select the server to which the connection should be established. Any number of servers may be included in this server set, and each request will attempt to retrieve a connection to the next server in the list, circling back to the beginning of the list as necessary. If a server is unavailable when an attempt is made to establish a connection to it, then the connection will be established to the next available server in the set.

This server set implementation has the ability to maintain a temporary blacklist of servers that have been recently found to be unavailable or unsuitable for use. If an attempt to establish or authenticate a connection fails, if post-connect processing fails for that connection, or if health checking indicates that the connection is not suitable, then that server may be placed on the blacklist so that it will only be tried as a last resort after all non-blacklisted servers have been attempted. The blacklist will be checked at regular intervals to determine whether a server should be re-instated to availability.

Example

The following example demonstrates the process for creating a round-robin server set that may be used to establish connections to either of two servers. When using the server set to attempt to create a connection, it will first try one of the servers, but will fail over to the other if the first one attempted is not available:

 // Create arrays with the addresses and ports of the directory server
 // instances.
 String[] addresses =
 {
   server1Address,
   server2Address
 };
 int[] ports =
 {
   server1Port,
   server2Port
 };

 // Create the server set using the address and port arrays.
 RoundRobinServerSet roundRobinSet =
      new RoundRobinServerSet(addresses, ports);

 // Verify that we can establish a single connection using the server set.
 LDAPConnection connection = roundRobinSet.getConnection();
 RootDSE rootDSEFromConnection = connection.getRootDSE();
 connection.close();

 // Verify that we can establish a connection pool using the server set.
 SimpleBindRequest bindRequest =
      new SimpleBindRequest("uid=pool.user,dc=example,dc=com", "password");
 LDAPConnectionPool pool =
      new LDAPConnectionPool(roundRobinSet, bindRequest, 10);
 RootDSE rootDSEFromPool = pool.getRootDSE();
 pool.close();
 

Constructor Summary

Constructors

Constructor and Description
RoundRobinServerSet(java.lang.String[] addresses, int[] ports) Creates a new round robin server set with the specified set of directory server addresses and port numbers.
RoundRobinServerSet(java.lang.String[] addresses, int[] ports, LDAPConnectionOptions connectionOptions) Creates a new round robin server set with the specified set of directory server addresses and port numbers.
RoundRobinServerSet(java.lang.String[] addresses, int[] ports, javax.net.SocketFactory socketFactory) Creates a new round robin server set with the specified set of directory server addresses and port numbers.
RoundRobinServerSet(java.lang.String[] addresses, int[] ports, javax.net.SocketFactory socketFactory, LDAPConnectionOptions connectionOptions) Creates a new round robin server set with the specified set of directory server addresses and port numbers.
RoundRobinServerSet(java.lang.String[] addresses, int[] ports, javax.net.SocketFactory socketFactory, LDAPConnectionOptions connectionOptions, BindRequest bindRequest, PostConnectProcessor postConnectProcessor) Creates a new round robin server set with the specified set of directory server addresses and port numbers.
RoundRobinServerSet(java.lang.String[] addresses, int[] ports, javax.net.SocketFactory socketFactory, LDAPConnectionOptions connectionOptions, BindRequest bindRequest, PostConnectProcessor postConnectProcessor, long blacklistCheckIntervalMillis) Creates a new round robin server set with the specified set of directory server addresses and port numbers.

Method Summary

Modifier and Type	Method and Description
java.lang.String[]	getAddresses() Retrieves the addresses of the directory servers to which the connections should be established.
ServerSetBlacklistManager	getBlacklistManager() Retrieves the blacklist manager for this server set.
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.
LDAPConnectionOptions	getConnectionOptions() Retrieves the set of connection options that will be used for underlying connections.
int[]	getPorts() Retrieves the ports of the directory servers to which the connections should be established.
javax.net.SocketFactory	getSocketFactory() Retrieves the socket factory that will be used to establish connections.
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.
void	toString(java.lang.StringBuilder buffer) Appends a string representation of this server set to the provided buffer.

Methods inherited from class com.unboundid.ldap.sdk.ServerSet

associateConnectionWithThisServerSet, doBindPostConnectAndHealthCheckProcessing, handleConnectionClosed, toString

Methods inherited from class java.lang.Object

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

Constructor Detail

RoundRobinServerSet

public RoundRobinServerSet(@NotNull
                           java.lang.String[] addresses,
                           @NotNull
                           int[] ports)

Creates a new round robin server set with the specified set of directory server addresses and port numbers. It will use the default socket factory provided by the JVM to create the underlying sockets.

Parameters:

addresses - The addresses of the directory servers to which the connections should be established. It must not be null or empty.

ports - The ports of the directory servers to which the connections should be established. It must not be null, and it must have the same number of elements as the addresses array. The order of elements in the addresses array must correspond to the order of elements in the ports array.

RoundRobinServerSet

public RoundRobinServerSet(@NotNull
                           java.lang.String[] addresses,
                           @NotNull
                           int[] ports,
                           @Nullable
                           LDAPConnectionOptions connectionOptions)

Creates a new round robin server set with the specified set of directory server addresses and port numbers. It will use the default socket factory provided by the JVM to create the underlying sockets.

Parameters:

addresses - The addresses of the directory servers to which the connections should be established. It must not be null or empty.

ports - The ports of the directory servers to which the connections should be established. It must not be null, and it must have the same number of elements as the addresses array. The order of elements in the addresses array must correspond to the order of elements in the ports array.

connectionOptions - The set of connection options to use for the underlying connections.

RoundRobinServerSet

public RoundRobinServerSet(@NotNull
                           java.lang.String[] addresses,
                           @NotNull
                           int[] ports,
                           @Nullable
                           javax.net.SocketFactory socketFactory)

Creates a new round robin server set with the specified set of directory server addresses and port numbers. It will use the provided socket factory to create the underlying sockets.

Parameters:

addresses - The addresses of the directory servers to which the connections should be established. It must not be null or empty.

ports - The ports of the directory servers to which the connections should be established. It must not be null, and it must have the same number of elements as the addresses array. The order of elements in the addresses array must correspond to the order of elements in the ports array.

socketFactory - The socket factory to use to create the underlying connections.

RoundRobinServerSet

public RoundRobinServerSet(@NotNull
                           java.lang.String[] addresses,
                           @NotNull
                           int[] ports,
                           @Nullable
                           javax.net.SocketFactory socketFactory,
                           @Nullable
                           LDAPConnectionOptions connectionOptions)

Creates a new round robin server set with the specified set of directory server addresses and port numbers. It will use the provided socket factory to create the underlying sockets.

Parameters:

addresses - The addresses of the directory servers to which the connections should be established. It must not be null or empty.

ports - The ports of the directory servers to which the connections should be established. It must not be null, and it must have the same number of elements as the addresses array. The order of elements in the addresses array must correspond to the order of elements in the ports array.

socketFactory - The socket factory to use to create the underlying connections.

connectionOptions - The set of connection options to use for the underlying connections.

RoundRobinServerSet

public RoundRobinServerSet(@NotNull
                           java.lang.String[] addresses,
                           @NotNull
                           int[] ports,
                           @Nullable
                           javax.net.SocketFactory socketFactory,
                           @Nullable
                           LDAPConnectionOptions connectionOptions,
                           @Nullable
                           BindRequest bindRequest,
                           @Nullable
                           PostConnectProcessor postConnectProcessor)

Creates a new round robin server set with the specified set of directory server addresses and port numbers. It will use the provided socket factory to create the underlying sockets.

Parameters:

addresses - The addresses of the directory servers to which the connections should be established. It must not be null or empty.

ports - The ports of the directory servers to which the connections should be established. It must not be null, and it must have the same number of elements as the addresses array. The order of elements in the addresses array must correspond to the order of elements in the ports array.

socketFactory - The socket factory to use to create the underlying connections.

connectionOptions - The set of connection options to use for the underlying connections.

bindRequest - The bind request that should be used to authenticate newly established connections. It may be null if this server set should not perform any authentication.

postConnectProcessor - The post-connect processor that should be invoked on newly established connections. It may be null if this server set should not perform any post-connect processing.

RoundRobinServerSet

public RoundRobinServerSet(@NotNull
                           java.lang.String[] addresses,
                           @NotNull
                           int[] ports,
                           @Nullable
                           javax.net.SocketFactory socketFactory,
                           @Nullable
                           LDAPConnectionOptions connectionOptions,
                           @Nullable
                           BindRequest bindRequest,
                           @Nullable
                           PostConnectProcessor postConnectProcessor,
                           long blacklistCheckIntervalMillis)

Creates a new round robin server set with the specified set of directory server addresses and port numbers. It will use the provided socket factory to create the underlying sockets.

Parameters:

addresses - The addresses of the directory servers to which the connections should be established. It must not be null or empty.

ports - The ports of the directory servers to which the connections should be established. It must not be null, and it must have the same number of elements as the addresses array. The order of elements in the addresses array must correspond to the order of elements in the ports array.

socketFactory - The socket factory to use to create the underlying connections.

connectionOptions - The set of connection options to use for the underlying connections.

bindRequest - The bind request that should be used to authenticate newly established connections. It may be null if this server set should not perform any authentication.

postConnectProcessor - The post-connect processor that should be invoked on newly established connections. It may be null if this server set should not perform any post-connect processing.

blacklistCheckIntervalMillis - The length of time in milliseconds between checks of servers on the blacklist to determine whether they are once again suitable for use. A value that is less than or equal to zero indicates that no blacklist should be maintained.

Method Detail

getAddresses

@NotNull
public java.lang.String[] getAddresses()

Retrieves the addresses of the directory servers to which the connections should be established.

Returns:

The addresses of the directory servers to which the connections should be established.

getPorts

@NotNull
public int[] getPorts()

Retrieves the ports of the directory servers to which the connections should be established.

Returns:

The ports of the directory servers to which the connections should be established.

getSocketFactory

@NotNull
public javax.net.SocketFactory getSocketFactory()

Retrieves the socket factory that will be used to establish connections.

Returns:

The socket factory that will be used to establish connections.

getConnectionOptions

@NotNull
public LDAPConnectionOptions getConnectionOptions()

Retrieves the set of connection options that will be used for underlying connections.

Returns:

The set of connection options that will be used for underlying connections.

includesAuthentication

public boolean includesAuthentication()

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

Overrides:

includesAuthentication in class ServerSet

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.

Overrides:

includesPostConnectProcessing in class ServerSet

Returns:

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

getConnection

@NotNull
public 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 ServerSet.includesAuthentication() must return true if and only if the connection will also be authenticated, and the ServerSet.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.

Specified by:

getConnection in class ServerSet

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 ServerSet.includesAuthentication() must return true if and only if the connection will also be authenticated, and the ServerSet.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.

Overrides:

getConnection in class ServerSet

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.

getBlacklistManager

@Nullable
public ServerSetBlacklistManager getBlacklistManager()

Retrieves the blacklist manager for this server set.

Returns:

The blacklist manager for this server set, or null if no blacklist will be maintained.

shutDown

public void shutDown()

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

Overrides:

shutDown in class ServerSet

toString

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

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

Overrides:

toString in class ServerSet

Parameters:

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