com.unboundid.ldap.sdk
Class FewestConnectionsServerSet

java.lang.Object
  extended by com.unboundid.ldap.sdk.ServerSet
      extended by 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.

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
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.
 
Method Summary
 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.
 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
toString
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

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 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.

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 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.

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 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.

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 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.
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.

getConnection

public LDAPConnection getConnection()
                             throws LDAPException
Attempts to establish a connection to one of the directory servers in this server set. The connection should be established but unauthenticated. 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

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 should be established but unauthenticated. 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 make the determination, or null if no additional health check should be performed.
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.

toString

public void toString(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.