Package com.unboundid.ldap.sdk
Class FewestConnectionsServerSet
- java.lang.Object
-
- com.unboundid.ldap.sdk.ServerSet
-
- com.unboundid.ldap.sdk.FewestConnectionsServerSet
-
@NotMutable @ThreadSafety(level=COMPLETELY_THREADSAFE) public final class FewestConnectionsServerSet extends ServerSet
This class provides a server set implementation that will establish a connection to the server with the fewest established connections previously created by the same server set instance. If there are multiple servers that share the fewest number of established connections, the first one in the list will be chosen. If a server is unavailable when an attempt is made to establish a connection to it, then the connection will be established to the available server with the next fewest number of established connections.
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.
Note that this server set implementation is primarily intended for use with connection pools, but is also suitable for cases in which standalone connections are created as long as there will not be any attempt to close the connections when they are re-established. It is not suitable for use in connections that may be re-established one or more times after being closed.
Example
The following example demonstrates the process for creating a fewest connections server set that may be used to establish connections to either of two servers.// 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. FewestConnectionsServerSet fewestConnectionsSet = new FewestConnectionsServerSet(addresses, ports); // Verify that we can establish a single connection using the server set. LDAPConnection connection = fewestConnectionsSet.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(fewestConnectionsSet, bindRequest, 10); RootDSE rootDSEFromPool = pool.getRootDSE(); pool.close();
-
-
Constructor Summary
Constructors Constructor Description FewestConnectionsServerSet(java.lang.String[] addresses, int[] ports)
Creates a new fewest connections server set with the specified set of directory server addresses and port numbers.FewestConnectionsServerSet(java.lang.String[] addresses, int[] ports, LDAPConnectionOptions connectionOptions)
Creates a new fewest connections server set with the specified set of directory server addresses and port numbers.FewestConnectionsServerSet(java.lang.String[] addresses, int[] ports, javax.net.SocketFactory socketFactory)
Creates a new fewest connections server set with the specified set of directory server addresses and port numbers.FewestConnectionsServerSet(java.lang.String[] addresses, int[] ports, javax.net.SocketFactory socketFactory, LDAPConnectionOptions connectionOptions)
Creates a new fewest connections server set with the specified set of directory server addresses and port numbers.FewestConnectionsServerSet(java.lang.String[] addresses, int[] ports, javax.net.SocketFactory socketFactory, LDAPConnectionOptions connectionOptions, BindRequest bindRequest, PostConnectProcessor postConnectProcessor)
Creates a new fewest connections server set with the specified set of directory server addresses and port numbers.FewestConnectionsServerSet(java.lang.String[] addresses, int[] ports, javax.net.SocketFactory socketFactory, LDAPConnectionOptions connectionOptions, BindRequest bindRequest, PostConnectProcessor postConnectProcessor, long blacklistCheckIntervalMillis)
Creates a new fewest connections server set with the specified set of directory server addresses and port numbers.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description java.lang.String[]
getAddresses()
Retrieves the addresses of the directory servers to which the connections should be established.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.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
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, toString
-
-
-
-
Constructor Detail
-
FewestConnectionsServerSet
public FewestConnectionsServerSet(java.lang.String[] addresses, int[] ports)
Creates a new fewest connections 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.
-
FewestConnectionsServerSet
public FewestConnectionsServerSet(java.lang.String[] addresses, int[] ports, LDAPConnectionOptions connectionOptions)
Creates a new fewest connections 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.
-
FewestConnectionsServerSet
public FewestConnectionsServerSet(java.lang.String[] addresses, int[] ports, javax.net.SocketFactory socketFactory)
Creates a new fewest connections 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.
-
FewestConnectionsServerSet
public FewestConnectionsServerSet(java.lang.String[] addresses, int[] ports, javax.net.SocketFactory socketFactory, LDAPConnectionOptions connectionOptions)
Creates a new fewest connections 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.
-
FewestConnectionsServerSet
public FewestConnectionsServerSet(java.lang.String[] addresses, int[] ports, javax.net.SocketFactory socketFactory, LDAPConnectionOptions connectionOptions, BindRequest bindRequest, PostConnectProcessor postConnectProcessor)
Creates a new fewest connections 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.
-
FewestConnectionsServerSet
public FewestConnectionsServerSet(java.lang.String[] addresses, int[] ports, javax.net.SocketFactory socketFactory, LDAPConnectionOptions connectionOptions, BindRequest bindRequest, PostConnectProcessor postConnectProcessor, long blacklistCheckIntervalMillis)
Creates a new fewest connections 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.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
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
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
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
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 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
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
public LDAPConnection getConnection(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.
-
handleConnectionClosed
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. This will only be invoked for connections created by this server set, and only if theServerSet.associateConnectionWithThisServerSet(com.unboundid.ldap.sdk.LDAPConnection)
method was called on the connection when it was created by this server set.- Overrides:
handleConnectionClosed
in classServerSet
- 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 benull
if no message is available.cause
- AThrowable
that was caught and triggered the disconnect. It may benull
if the disconnect was not triggered by a client-side exception or error.
-
-