Class FastestConnectServerSet


  • @NotMutable
    @ThreadSafety(level=COMPLETELY_THREADSAFE)
    public final class FastestConnectServerSet
    extends ServerSet
    This class provides a server set implementation that will attempt to establish connections to all associated servers in parallel, keeping the one that was first to be successfully established and closing all others.

    Note that this server set implementation may only be used in conjunction with connection options that allow the associated socket factory to create multiple connections in parallel. If the LDAPConnectionOptions.allowConcurrentSocketFactoryUse method returns false for the associated connection options, then the getConnection methods will throw an exception.

    Example

    The following example demonstrates the process for creating a fastest connect 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 try both in parallel and will return the first connection that it is able to establish:
     // 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.
     FastestConnectServerSet fastestConnectSet =
          new FastestConnectServerSet(addresses, ports);
    
     // Verify that we can establish a single connection using the server set.
     LDAPConnection connection = fastestConnectSet.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(fastestConnectSet, bindRequest, 10);
     RootDSE rootDSEFromPool = pool.getRootDSE();
     pool.close();
     
    • Constructor Summary

      Constructors 
      Constructor Description
      FastestConnectServerSet​(java.lang.String[] addresses, int[] ports)
      Creates a new fastest connect server set with the specified set of directory server addresses and port numbers.
      FastestConnectServerSet​(java.lang.String[] addresses, int[] ports, LDAPConnectionOptions connectionOptions)
      Creates a new fastest connect server set with the specified set of directory server addresses and port numbers.
      FastestConnectServerSet​(java.lang.String[] addresses, int[] ports, javax.net.SocketFactory socketFactory)
      Creates a new fastest connect server set with the specified set of directory server addresses and port numbers.
      FastestConnectServerSet​(java.lang.String[] addresses, int[] ports, javax.net.SocketFactory socketFactory, LDAPConnectionOptions connectionOptions)
      Creates a new fastest connect server set with the specified set of directory server addresses and port numbers.
      FastestConnectServerSet​(java.lang.String[] addresses, int[] ports, javax.net.SocketFactory socketFactory, LDAPConnectionOptions connectionOptions, BindRequest bindRequest, PostConnectProcessor postConnectProcessor)
      Creates a new fastest connect server set with the specified set of directory server addresses and port numbers.
    • Constructor Detail

      • FastestConnectServerSet

        public FastestConnectServerSet​(java.lang.String[] addresses,
                                       int[] ports)
        Creates a new fastest connect 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.
      • FastestConnectServerSet

        public FastestConnectServerSet​(java.lang.String[] addresses,
                                       int[] ports,
                                       LDAPConnectionOptions connectionOptions)
        Creates a new fastest connect 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.
      • FastestConnectServerSet

        public FastestConnectServerSet​(java.lang.String[] addresses,
                                       int[] ports,
                                       javax.net.SocketFactory socketFactory)
        Creates a new fastest connect 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.
      • FastestConnectServerSet

        public FastestConnectServerSet​(java.lang.String[] addresses,
                                       int[] ports,
                                       javax.net.SocketFactory socketFactory,
                                       LDAPConnectionOptions connectionOptions)
        Creates a new fastest connect 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.
      • FastestConnectServerSet

        public FastestConnectServerSet​(java.lang.String[] addresses,
                                       int[] ports,
                                       javax.net.SocketFactory socketFactory,
                                       LDAPConnectionOptions connectionOptions,
                                       BindRequest bindRequest,
                                       PostConnectProcessor postConnectProcessor)
        Creates a new fastest connect 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.
    • 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 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

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