Package com.unboundid.ldap.sdk
Class FailoverServerSet
- java.lang.Object
-
- com.unboundid.ldap.sdk.ServerSet
-
- com.unboundid.ldap.sdk.FailoverServerSet
-
@NotMutable @ThreadSafety(level=COMPLETELY_THREADSAFE) public final class FailoverServerSet extends ServerSet
This class provides a server set implementation that will attempt to establish connections to servers in the order they are provided. If the first server is unavailable, then it will attempt to connect to the second, then to the third, etc. Note that this implementation also makes it possible to use failover between distinct server sets, which means that it will first attempt to obtain a connection from the first server set and if all attempts fail, it will proceed to the second set, and so on. This can provide a significant degree of flexibility in complex environments (e.g., first use a round robin server set containing servers in the local data center, but if none of those are available then fail over to a server set with servers in a remote data center).
Example
The following example demonstrates the process for creating a failover server set with information about individual servers. It will first try to connect to ds1.example.com:389, but if that fails then it will try connecting to ds2.example.com:389:// 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. FailoverServerSet failoverSet = new FailoverServerSet(addresses, ports); // Verify that we can establish a single connection using the server set. LDAPConnection connection = failoverSet.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(failoverSet, bindRequest, 10); RootDSE rootDSEFromPool = pool.getRootDSE(); pool.close();
This second example demonstrates the process for creating a failover server set which actually fails over between two different data centers (east and west), with each data center containing two servers that will be accessed in a round-robin manner. It will first try to connect to one of the servers in the east data center, and if that attempt fails then it will try to connect to the other server in the east data center. If both of them fail, then it will try to connect to one of the servers in the west data center, and finally as a last resort the other server in the west data center:// Create a round-robin server set for the servers in the "east" data // center. String[] eastAddresses = { eastServer1Address, eastServer2Address }; int[] eastPorts = { eastServer1Port, eastServer2Port }; RoundRobinServerSet eastSet = new RoundRobinServerSet(eastAddresses, eastPorts); // Create a round-robin server set for the servers in the "west" data // center. String[] westAddresses = { westServer1Address, westServer2Address }; int[] westPorts = { westServer1Port, westServer2Port }; RoundRobinServerSet westSet = new RoundRobinServerSet(westAddresses, westPorts); // Create the failover server set across the east and west round-robin sets. FailoverServerSet failoverSet = new FailoverServerSet(eastSet, westSet); // Verify that we can establish a single connection using the server set. LDAPConnection connection = failoverSet.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(failoverSet, bindRequest, 10); RootDSE rootDSEFromPool = pool.getRootDSE(); pool.close();
-
-
Constructor Summary
Constructors Constructor Description FailoverServerSet(ServerSet... serverSets)
Creates a new failover server set that will fail over between the provided server sets.FailoverServerSet(java.lang.String[] addresses, int[] ports)
Creates a new failover server set with the specified set of directory server addresses and port numbers.FailoverServerSet(java.lang.String[] addresses, int[] ports, LDAPConnectionOptions connectionOptions)
Creates a new failover server set with the specified set of directory server addresses and port numbers.FailoverServerSet(java.lang.String[] addresses, int[] ports, javax.net.SocketFactory socketFactory)
Creates a new failover server set with the specified set of directory server addresses and port numbers.FailoverServerSet(java.lang.String[] addresses, int[] ports, javax.net.SocketFactory socketFactory, LDAPConnectionOptions connectionOptions)
Creates a new failover server set with the specified set of directory server addresses and port numbers.FailoverServerSet(java.lang.String[] addresses, int[] ports, javax.net.SocketFactory socketFactory, LDAPConnectionOptions connectionOptions, BindRequest bindRequest, PostConnectProcessor postConnectProcessor)
Creates a new failover server set with the specified set of directory server addresses and port numbers.FailoverServerSet(java.util.List<ServerSet> serverSets)
Creates a new failover server set that will fail over between the provided server sets.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description 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.java.lang.Long
getMaxFailoverConnectionAgeMillis()
Retrieves the maximum connection age that should be used for "failover" connections (i.e., connections that are established to any server other than the most-preferred server, or established using any server set other than the most-preferred set).ServerSet[]
getServerSets()
Retrieves the server sets over which failover will occur.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.boolean
reOrderOnFailover()
Indicates whether the list of servers or server sets used by this failover server set should be re-ordered in the event that a failure is encountered while attempting to establish a connection.void
setMaxFailoverConnectionAgeMillis(java.lang.Long maxFailoverConnectionAge)
Specifies the maximum connection age that should be used for "failover" connections (i.e., connections that are established to any server other than the most-preferred server, or established using any server set other than the most-preferred set).void
setReOrderOnFailover(boolean reOrderOnFailover)
Specifies whether the list of servers or server sets used by this failover server set should be re-ordered in the event that a failure is encountered while attempting to establish a connection.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, shutDown, toString
-
-
-
-
Constructor Detail
-
FailoverServerSet
public FailoverServerSet(@NotNull java.lang.String[] addresses, @NotNull int[] ports)
Creates a new failover 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 benull
or empty.ports
- The ports of the directory servers to which the connections should be established. It must not benull
, and it must have the same number of elements as theaddresses
array. The order of elements in theaddresses
array must correspond to the order of elements in theports
array.
-
FailoverServerSet
public FailoverServerSet(@NotNull java.lang.String[] addresses, @NotNull int[] ports, @Nullable LDAPConnectionOptions connectionOptions)
Creates a new failover 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 benull
or empty.ports
- The ports of the directory servers to which the connections should be established. It must not benull
, and it must have the same number of elements as theaddresses
array. The order of elements in theaddresses
array must correspond to the order of elements in theports
array.connectionOptions
- The set of connection options to use for the underlying connections.
-
FailoverServerSet
public FailoverServerSet(@NotNull java.lang.String[] addresses, @NotNull int[] ports, @Nullable javax.net.SocketFactory socketFactory)
Creates a new failover 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 benull
or empty.ports
- The ports of the directory servers to which the connections should be established. It must not benull
, and it must have the same number of elements as theaddresses
array. The order of elements in theaddresses
array must correspond to the order of elements in theports
array.socketFactory
- The socket factory to use to create the underlying connections.
-
FailoverServerSet
public FailoverServerSet(@NotNull java.lang.String[] addresses, @NotNull int[] ports, @Nullable javax.net.SocketFactory socketFactory, @Nullable LDAPConnectionOptions connectionOptions)
Creates a new failover 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 benull
or empty.ports
- The ports of the directory servers to which the connections should be established. It must not benull
, and it must have the same number of elements as theaddresses
array. The order of elements in theaddresses
array must correspond to the order of elements in theports
array.socketFactory
- The socket factory to use to create the underlying connections.connectionOptions
- The set of connection options to use for the underlying connections.
-
FailoverServerSet
public FailoverServerSet(@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 failover 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 benull
or empty.ports
- The ports of the directory servers to which the connections should be established. It must not benull
, and it must have the same number of elements as theaddresses
array. The order of elements in theaddresses
array must correspond to the order of elements in theports
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 benull
if this server set should not perform any authentication.postConnectProcessor
- The post-connect processor that should be invoked on newly-established connections. It may benull
if this server set should not perform any post-connect processing.
-
FailoverServerSet
public FailoverServerSet(@NotNull ServerSet... serverSets)
Creates a new failover server set that will fail over between the provided server sets.- Parameters:
serverSets
- The server sets between which failover should occur. It must not benull
or empty. All of the provided sets must have the same return value for theirincludesAuthentication()
method, and all of the provided sets must have the same return value for theirincludesPostConnectProcessing()
method.
-
FailoverServerSet
public FailoverServerSet(@NotNull java.util.List<ServerSet> serverSets)
Creates a new failover server set that will fail over between the provided server sets.- Parameters:
serverSets
- The server sets between which failover should occur. It must not benull
or empty. All of the provided sets must have the same return value for theirincludesAuthentication()
method, and all of the provided sets must have the same return value for theirincludesPostConnectProcessing()
method.
-
-
Method Detail
-
getServerSets
@NotNull public ServerSet[] getServerSets()
Retrieves the server sets over which failover will occur. If this failover server set was created from individual servers rather than server sets, then the elements contained in the returned array will beSingleServerSet
instances.- Returns:
- The server sets over which failover will occur.
-
reOrderOnFailover
public boolean reOrderOnFailover()
Indicates whether the list of servers or server sets used by this failover server set should be re-ordered in the event that a failure is encountered while attempting to establish a connection. Iftrue
, then any failed attempt to establish a connection to a server set at the beginning of the list may cause that server/set to be moved to the end of the list so that it will be the last one tried on the next attempt.- Returns:
true
if the order of elements in the associated list of servers or server sets should be updated if a failure occurs while attempting to establish a connection, orfalse
if the original order should be preserved.
-
setReOrderOnFailover
public void setReOrderOnFailover(boolean reOrderOnFailover)
Specifies whether the list of servers or server sets used by this failover server set should be re-ordered in the event that a failure is encountered while attempting to establish a connection. By default, the original order will be preserved, but if this method is called with a value oftrue
, then a failed attempt to establish a connection to the server or server set at the beginning of the list may cause that server to be moved to the end of the list so that it will be the last server/set tried on the next attempt.- Parameters:
reOrderOnFailover
- Indicates whether the list of servers or server sets should be re-ordered in the event that a failure is encountered while attempting to establish a connection.
-
getMaxFailoverConnectionAgeMillis
@Nullable public java.lang.Long getMaxFailoverConnectionAgeMillis()
Retrieves the maximum connection age that should be used for "failover" connections (i.e., connections that are established to any server other than the most-preferred server, or established using any server set other than the most-preferred set). This will only be used if this failover server set is used to create anLDAPConnectionPool
, for connections within that pool.- Returns:
- The maximum connection age that should be used for failover
connections, a value of zero to indicate that no maximum age
should apply to those connections, or
null
if the maximum connection age should be determined by the associated connection pool.
-
setMaxFailoverConnectionAgeMillis
public void setMaxFailoverConnectionAgeMillis(@Nullable java.lang.Long maxFailoverConnectionAge)
Specifies the maximum connection age that should be used for "failover" connections (i.e., connections that are established to any server other than the most-preferred server, or established using any server set other than the most-preferred set). This will only be used if this failover server set is used to create anLDAPConnectionPool
, for connections within that pool.- Parameters:
maxFailoverConnectionAge
- The maximum connection age that should be used for failover connections. It may be less than or equal to zero to indicate that no maximum age should apply to such connections, ornull
to indicate that the maximum connection age should be determined by the associated connection pool.
-
includesAuthentication
public boolean includesAuthentication()
Indicates whether connections created by this server set will be authenticated.- Overrides:
includesAuthentication
in classServerSet
- Returns:
true
if connections created by this server set will be authenticated, orfalse
if not.
-
includesPostConnectProcessing
public boolean includesPostConnectProcessing()
Indicates whether connections created by this server set will have post-connect processing performed.- Overrides:
includesPostConnectProcessing
in classServerSet
- Returns:
true
if connections created by this server set will have post-connect processing performed, orfalse
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. TheServerSet.includesAuthentication()
must return true if and only if the connection will also be authenticated, and theServerSet.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 theLDAPConnection.getConnectedAddress()
andLDAPConnection.getConnectedPort()
methods.- Specified by:
getConnection
in classServerSet
- 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. TheServerSet.includesAuthentication()
must return true if and only if the connection will also be authenticated, and theServerSet.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 theLDAPConnection.getConnectedAddress()
andLDAPConnection.getConnectedPort()
methods.- Overrides:
getConnection
in classServerSet
- Parameters:
healthCheck
- The health check to use to verify the health of the newly-created connection. It may benull
if no additional health check should be performed. If it is non-null
and this server set performs authentication, then the health check'sensureConnectionValidAfterAuthentication
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'sensureNewConnectionValid
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.
-
-