@NotMutable @ThreadSafety(level=COMPLETELY_THREADSAFE) public final class FailoverServerSet extends ServerSet
// 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 and Description |
|---|
FailoverServerSet(java.util.List<ServerSet> serverSets)
Creates a new failover server set that will fail over between the provided
server sets.
|
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.
|
| Modifier and Type | Method and 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.
|
associateConnectionWithThisServerSet, doBindPostConnectAndHealthCheckProcessing, handleConnectionClosed, shutDown, toStringpublic FailoverServerSet(@NotNull java.lang.String[] addresses, @NotNull int[] ports)
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.public FailoverServerSet(@NotNull java.lang.String[] addresses, @NotNull int[] ports, @Nullable LDAPConnectionOptions connectionOptions)
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.public FailoverServerSet(@NotNull java.lang.String[] addresses, @NotNull int[] ports, @Nullable javax.net.SocketFactory socketFactory)
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.public FailoverServerSet(@NotNull java.lang.String[] addresses, @NotNull int[] ports, @Nullable javax.net.SocketFactory socketFactory, @Nullable LDAPConnectionOptions connectionOptions)
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.public FailoverServerSet(@NotNull java.lang.String[] addresses, @NotNull int[] ports, @Nullable javax.net.SocketFactory socketFactory, @Nullable LDAPConnectionOptions connectionOptions, @Nullable BindRequest bindRequest, @Nullable PostConnectProcessor postConnectProcessor)
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.public FailoverServerSet(@NotNull ServerSet... serverSets)
serverSets - The server sets between which failover should occur.
It must not be null or empty. All of the
provided sets must have the same return value for their
includesAuthentication() method, and all of
the provided sets must have the same return value for
their includesPostConnectProcessing()
method.public FailoverServerSet(@NotNull java.util.List<ServerSet> serverSets)
serverSets - The server sets between which failover should occur.
It must not be null or empty. All of the
provided sets must have the same return value for their
includesAuthentication() method, and all of
the provided sets must have the same return value for
their includesPostConnectProcessing()
method.@NotNull public ServerSet[] getServerSets()
SingleServerSet instances.public boolean reOrderOnFailover()
true, 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.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, or false if the
original order should be preserved.public void setReOrderOnFailover(boolean reOrderOnFailover)
true, 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.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.@Nullable public java.lang.Long getMaxFailoverConnectionAgeMillis()
LDAPConnectionPool, for connections
within that pool.null if the maximum
connection age should be determined by the associated connection
pool.public void setMaxFailoverConnectionAgeMillis(@Nullable java.lang.Long maxFailoverConnectionAge)
LDAPConnectionPool, for connections
within that pool.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, or null to indicate
that the maximum connection age should be
determined by the associated connection
pool.public boolean includesAuthentication()
includesAuthentication in class ServerSettrue if connections created by this server set will be
authenticated, or false if not.public boolean includesPostConnectProcessing()
includesPostConnectProcessing in class ServerSettrue if connections created by this server set will have
post-connect processing performed, or false if not.@NotNull public LDAPConnection getConnection() throws LDAPException
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.getConnection in class ServerSetLDAPConnection object that is established to one of the
servers in this server set.LDAPException - If it is not possible to establish a connection to
any of the servers in this server set.@NotNull public LDAPConnection getConnection(@Nullable LDAPConnectionPoolHealthCheck healthCheck) throws LDAPException
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.getConnection in class ServerSethealthCheck - 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.LDAPConnection object that is established to one of the
servers in this server set.LDAPException - If it is not possible to establish a connection to
any of the servers in this server set.