com.unboundid.ldap.sdk

Class RoundRobinDNSServerSet

java.lang.Object

com.unboundid.ldap.sdk.ServerSet

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

Nested Classes

Modifier and Type	Class and Description
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

Constructors

Constructor and Description
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, java.util.Properties jndiProperties, java.lang.String[] dnsRecordTypes, javax.net.SocketFactory socketFactory, LDAPConnectionOptions connectionOptions, BindRequest bindRequest, PostConnectProcessor postConnectProcessor) 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

Modifier and Type	Method and Description
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.
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, handleConnectionClosed, shutDown, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

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.

getAddressSelectionMode

@NotNull
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

@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()
                                      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. 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.

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

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