Class RoundRobinDNSServerSet


  • @NotMutable
    @ThreadSafety(level=COMPLETELY_THREADSAFE)
    public final class RoundRobinDNSServerSet
    extends ServerSet
    This class provides a server set implementation that handles the case in which a given host name may resolve to multiple IP addresses. Note that while a setup like this is typically referred to as "round-robin DNS", this server set implementation does not strictly require DNS (as names may be resolved through alternate mechanisms like a hosts file or an alternate name service), and it does not strictly require round-robin use of those addresses (as alternate ordering mechanisms, like randomized or failover, may be used).

    Example

    The following example demonstrates the process for creating a round-robin DNS server set for the case in which the hostname "directory.example.com" may be associated with multiple IP addresses, and the LDAP SDK should attempt to use them in a round robin manner.
       // Define a number of variables that will be used by the server set.
       String                hostname           = "directory.example.com";
       int                   port               = 389;
       AddressSelectionMode  selectionMode      =
            AddressSelectionMode.ROUND_ROBIN;
       long                  cacheTimeoutMillis = 3600000L; // 1 hour
       String                providerURL        = "dns:"; // Default DNS config.
       SocketFactory         socketFactory      = null; // Default socket factory.
       LDAPConnectionOptions connectionOptions  = null; // Default options.
    
       // Create the server set using the settings defined above.
       RoundRobinDNSServerSet serverSet = new RoundRobinDNSServerSet(hostname,
            port, selectionMode, cacheTimeoutMillis, providerURL, socketFactory,
            connectionOptions);
    
       // Verify that we can establish a single connection using the server set.
       LDAPConnection connection = serverSet.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(serverSet, bindRequest, 10);
       RootDSE rootDSEFromPool = pool.getRootDSE();
       pool.close();
     
    • Constructor Detail

      • RoundRobinDNSServerSet

        public RoundRobinDNSServerSet​(@NotNull
                                      java.lang.String hostname,
                                      int port,
                                      @NotNull
                                      RoundRobinDNSServerSet.AddressSelectionMode selectionMode,
                                      long cacheTimeoutMillis,
                                      @Nullable
                                      java.lang.String providerURL,
                                      @Nullable
                                      javax.net.SocketFactory socketFactory,
                                      @Nullable
                                      LDAPConnectionOptions connectionOptions)
        Creates a new round-robin DNS server set with the provided information.
        Parameters:
        hostname - The hostname to be resolved to one or more addresses. It must not be null.
        port - The port to use to connect to the server. Note that even if the provided hostname resolves to multiple addresses, the same port must be used for all addresses.
        selectionMode - The selection mode that should be used if the hostname resolves to multiple addresses. It must not be null.
        cacheTimeoutMillis - The maximum length of time in milliseconds to cache addresses resolved from the provided hostname. Caching resolved addresses can result in better performance and can reduce the number of requests to the name service. A that is less than or equal to zero indicates that no caching should be used.
        providerURL - The JNDI provider URL that should be used when communicating with the DNS server. If this is null, then the underlying system's name service mechanism will be used (which may make use of other services instead of or in addition to DNS). If this is non-null, then only DNS will be used to perform the name resolution. A value of "dns:" indicates that the underlying system's DNS configuration should be used.
        socketFactory - The socket factory to use to establish the connections. It may be null if the JVM-default socket factory should be used.
        connectionOptions - The set of connection options that should be used for the connections. It may be null if a default set of connection options should be used.
      • RoundRobinDNSServerSet

        public RoundRobinDNSServerSet​(@NotNull
                                      java.lang.String hostname,
                                      int port,
                                      @NotNull
                                      RoundRobinDNSServerSet.AddressSelectionMode selectionMode,
                                      long cacheTimeoutMillis,
                                      @Nullable
                                      java.lang.String providerURL,
                                      @Nullable
                                      java.util.Properties jndiProperties,
                                      @Nullable
                                      java.lang.String[] dnsRecordTypes,
                                      @Nullable
                                      javax.net.SocketFactory socketFactory,
                                      @Nullable
                                      LDAPConnectionOptions connectionOptions)
        Creates a new round-robin DNS server set with the provided information.
        Parameters:
        hostname - The hostname to be resolved to one or more addresses. It must not be null.
        port - The port to use to connect to the server. Note that even if the provided hostname resolves to multiple addresses, the same port must be used for all addresses.
        selectionMode - The selection mode that should be used if the hostname resolves to multiple addresses. It must not be null.
        cacheTimeoutMillis - The maximum length of time in milliseconds to cache addresses resolved from the provided hostname. Caching resolved addresses can result in better performance and can reduce the number of requests to the name service. A that is less than or equal to zero indicates that no caching should be used.
        providerURL - The JNDI provider URL that should be used when communicating with the DNS server.If both providerURL and jndiProperties are null, then then JNDI will not be used to interact with DNS and the hostname resolution will be performed via the underlying system's name service mechanism (which may make use of other services instead of or in addition to DNS). If this is non-null, then only DNS will be used to perform the name resolution. A value of "dns:" indicates that the underlying system's DNS configuration should be used.
        jndiProperties - A set of JNDI-related properties that should be be used when initializing the context for interacting with the DNS server via JNDI. If both providerURL and jndiProperties are null, then then JNDI will not be used to interact with DNS and the hostname resolution will be performed via the underlying system's name service mechanism (which may make use of other services instead of or in addition to DNS). If providerURL is null and jndiProperties is non-null, then the provided properties must specify the URL.
        dnsRecordTypes - Specifies the types of DNS records that will be used to obtain the addresses for the specified hostname. This will only be used if at least one of providerURL and jndiProperties is non-null. If this is null or empty, then a default record type of "A" (indicating IPv4 addresses) will be used.
        socketFactory - The socket factory to use to establish the connections. It may be null if the JVM-default socket factory should be used.
        connectionOptions - The set of connection options that should be used for the connections. It may be null if a default set of connection options should be used.
      • RoundRobinDNSServerSet

        public RoundRobinDNSServerSet​(@NotNull
                                      java.lang.String hostname,
                                      int port,
                                      @NotNull
                                      RoundRobinDNSServerSet.AddressSelectionMode selectionMode,
                                      long cacheTimeoutMillis,
                                      @Nullable
                                      java.lang.String providerURL,
                                      @Nullable
                                      java.util.Properties jndiProperties,
                                      @Nullable
                                      java.lang.String[] dnsRecordTypes,
                                      @Nullable
                                      javax.net.SocketFactory socketFactory,
                                      @Nullable
                                      LDAPConnectionOptions connectionOptions,
                                      @Nullable
                                      BindRequest bindRequest,
                                      @Nullable
                                      PostConnectProcessor postConnectProcessor)
        Creates a new round-robin DNS server set with the provided information.
        Parameters:
        hostname - The hostname to be resolved to one or more addresses. It must not be null.
        port - The port to use to connect to the server. Note that even if the provided hostname resolves to multiple addresses, the same port must be used for all addresses.
        selectionMode - The selection mode that should be used if the hostname resolves to multiple addresses. It must not be null.
        cacheTimeoutMillis - The maximum length of time in milliseconds to cache addresses resolved from the provided hostname. Caching resolved addresses can result in better performance and can reduce the number of requests to the name service. A that is less than or equal to zero indicates that no caching should be used.
        providerURL - The JNDI provider URL that should be used when communicating with the DNS server. If both providerURL and jndiProperties are null, then then JNDI will not be used to interact with DNS and the hostname resolution will be performed via the underlying system's name service mechanism (which may make use of other services instead of or in addition to DNS). If this is non-null, then only DNS will be used to perform the name resolution. A value of "dns:" indicates that the underlying system's DNS configuration should be used.
        jndiProperties - A set of JNDI-related properties that should be used when initializing the context for interacting with the DNS server via JNDI. If both providerURL and jndiProperties are null, then JNDI will not be used to interact with DNS and the hostname resolution will be performed via the underlying system's name service mechanism (which may make use of other services instead of or in addition to DNS). If providerURL is null and jndiProperties is non-null, then the provided properties must specify the URL.
        dnsRecordTypes - Specifies the types of DNS records that will be used to obtain the addresses for the specified hostname. This will only be used if at least one of providerURL and jndiProperties is non-null. If this is null or empty, then a default record type of "A" (indicating IPv4 addresses) will be used.
        socketFactory - The socket factory to use to establish the connections. It may be null if the JVM-default socket factory should be used.
        connectionOptions - The set of connection options that should be used for the connections. It may be null if a default set of connection options should be used.
        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

      • getHostname

        @NotNull
        public java.lang.String getHostname()
        Retrieves the hostname to be resolved.
        Returns:
        The hostname to be resolved.
      • getPort

        public int getPort()
        Retrieves the port to use to connect to the server.
        Returns:
        The port to use to connect to the server.
      • getCacheTimeoutMillis

        public long getCacheTimeoutMillis()
        Retrieves the length of time in milliseconds that resolved addresses may be cached.
        Returns:
        The length of time in milliseconds that resolved addresses may be cached, or zero if no caching should be performed.
      • getProviderURL

        @Nullable
        public java.lang.String getProviderURL()
        Retrieves the provider URL that should be used when interacting with DNS to resolve the hostname to its corresponding addresses.
        Returns:
        The provider URL that should be used when interacting with DNS to resolve the hostname to its corresponding addresses, or null if the system's configured naming service should be used.
      • getJNDIProperties

        @Nullable
        public java.util.Map<java.lang.String,​java.lang.String> getJNDIProperties()
        Retrieves an unmodifiable map of properties that will be used to initialize the JNDI context used to interact with DNS. Note that the map returned will reflect the actual properties that will be used, and may not exactly match the properties provided when creating this server set.
        Returns:
        An unmodifiable map of properties that will be used to initialize the JNDI context used to interact with DNS, or null if JNDI will nto be used to interact with DNS.
      • getDNSRecordTypes

        @NotNull
        public java.lang.String[] getDNSRecordTypes()
        Retrieves an array of record types that will be requested if JNDI will be used to interact with DNS.
        Returns:
        An array of record types that will be requested if JNDI will be used to interact with DNS.
      • getSocketFactory

        @NotNull
        public javax.net.SocketFactory getSocketFactory()
        Retrieves the socket factory that will be used to establish connections. This will not be null, even if no socket factory was provided when the server set was created.
        Returns:
        The socket factory that will be used to establish connections.
      • getConnectionOptions

        @NotNull
        public LDAPConnectionOptions getConnectionOptions()
        Retrieves the set of connection options that will be used for underlying connections. This will not be null, even if no connection options object was provided when the server set was created.
        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

        @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. 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​(@NotNull
                             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.