com.unboundid.ldap.sdk
Class RoundRobinDNSServerSet

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


Nested Class Summary
static class RoundRobinDNSServerSet.AddressSelectionMode
          An enum that defines the modes that may be used to select the order in which addresses should be used in attempts to establish connections.
 
Constructor Summary
RoundRobinDNSServerSet(java.lang.String hostname, int port, RoundRobinDNSServerSet.AddressSelectionMode selectionMode, long cacheTimeoutMillis, java.lang.String providerURL, java.util.Properties jndiProperties, java.lang.String[] dnsRecordTypes, javax.net.SocketFactory socketFactory, LDAPConnectionOptions connectionOptions)
          Creates a new round-robin DNS server set with the provided information.
RoundRobinDNSServerSet(java.lang.String hostname, int port, RoundRobinDNSServerSet.AddressSelectionMode selectionMode, long cacheTimeoutMillis, java.lang.String providerURL, javax.net.SocketFactory socketFactory, LDAPConnectionOptions connectionOptions)
          Creates a new round-robin DNS server set with the provided information.
 
Method Summary
 RoundRobinDNSServerSet.AddressSelectionMode getAddressSelectionMode()
          Retrieves the address selection mode that should be used if the provided hostname resolves to multiple addresses.
 long getCacheTimeoutMillis()
          Retrieves the length of time in milliseconds that resolved addresses may be cached.
 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.
 java.lang.String[] getDNSRecordTypes()
          Retrieves an array of record types that will be requested if JNDI will be used to interact with DNS.
 java.lang.String getHostname()
          Retrieves the hostname to be resolved.
 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.
 int getPort()
          Retrieves the port to use to connect to the server.
 java.lang.String getProviderURL()
          Retrieves the provider URL that should be used when interacting with DNS to resolve the hostname to its corresponding addresses.
 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

RoundRobinDNSServerSet

public RoundRobinDNSServerSet(java.lang.String hostname,
                              int port,
                              RoundRobinDNSServerSet.AddressSelectionMode selectionMode,
                              long cacheTimeoutMillis,
                              java.lang.String providerURL,
                              javax.net.SocketFactory socketFactory,
                              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(java.lang.String hostname,
                              int port,
                              RoundRobinDNSServerSet.AddressSelectionMode selectionMode,
                              long cacheTimeoutMillis,
                              java.lang.String providerURL,
                              java.util.Properties jndiProperties,
                              java.lang.String[] dnsRecordTypes,
                              javax.net.SocketFactory socketFactory,
                              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.
Method Detail

getHostname

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.

getAddressSelectionMode

public RoundRobinDNSServerSet.AddressSelectionMode getAddressSelectionMode()
Retrieves the address selection mode that should be used if the provided hostname resolves to multiple addresses.

Returns:
The address selection

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

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

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

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

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

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.

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.