com.unboundid.ldap.sdk
Class DNSSRVRecordServerSet

java.lang.Object
  extended by com.unboundid.ldap.sdk.ServerSet
      extended by com.unboundid.ldap.sdk.DNSSRVRecordServerSet

@NotMutable
@ThreadSafety(level=COMPLETELY_THREADSAFE)
public final class DNSSRVRecordServerSet
extends ServerSet

This class provides a server set implementation that can discover information about available directory servers through DNS SRV records as described in RFC 2782. DNS SRV records make it possible for clients to use the domain name system to discover information about the systems that provide a given service, which can help avoid the need to explicitly configure clients with the addresses of the appropriate set of directory servers.

The standard service name used to reference LDAP directory servers is "_ldap._tcp". If client systems have DNS configured properly with an appropriate search domain, then this may be all that is needed to discover any available directory servers. Alternately, a record name of "_ldap._tcp.example.com" may be used to request DNS information about LDAP servers for the example.com domain. However, there is no technical requirement that "_ldap._tcp" must be used for this purpose, and it may make sense to use a different name if there is something special about the way clients should interact with the servers (e.g., "_ldaps._tcp" would be more appropriate if LDAP clients need to use SSL when communicating with the server).

DNS SRV records contain a number of components, including:

In the event that multiple SRV records exist for the target service, then the priorities and weights of those records will be used to determine the order in which the servers will be tried. Records with a lower priority value will always be tried before those with a higher priority value. For records with equal priority values and nonzero weights, then the ratio of those weight values will be used to control how likely one of those records is to be tried before another. Records with a weight of zero will always be tried after records with the same priority and nonzero weights.

This server set implementation uses JNDI to communicate with DNS servers in order to obtain the requested SRV records (although it does not use JNDI for any LDAP communication). In order to specify which DNS server(s) to query, a JNDI provider URL must be used. In many cases, a URL of "dns:", which indicates that the client should use the DNS servers configured for use by the underlying system, should be sufficient. However, if you wish to use a specific DNS server then you may explicitly specify it in the URL (e.g., "dns://1.2.3.4:53" would attempt to communicate with the DNS server listening on IP address 1.2.3.4 and port 53). If you wish to specify multiple DNS servers, you may provide multiple URLs separated with spaces and they will be tried in the order in which they were included in the list until a response can be retrieved (e.g., for a provider URL of "dns://1.2.3.4 dns://1.2.3.5", it will first try to use the DNS server running on system with IP address "1.2.3.4", but if that is not successful then it will try the DNS server running on the system with IP address "1.2.3.5"). See the JNDI DNS service provider documentation for more details on acceptable formats for the provider URL.


Constructor Summary
DNSSRVRecordServerSet(java.lang.String recordName)
          Creates a new instance of this server set that will use the specified DNS record name, a default DNS provider URL that will attempt to determine DNS servers from the underlying system configuration, a default TTL of one hour, round-robin ordering for servers with the same priority, and default socket factory and connection options.
DNSSRVRecordServerSet(java.lang.String recordName, java.lang.String providerURL, long ttlMillis, javax.net.SocketFactory socketFactory, LDAPConnectionOptions connectionOptions)
          Creates a new instance of this server set that will use the provided settings.
DNSSRVRecordServerSet(java.lang.String recordName, java.lang.String providerURL, java.util.Properties jndiProperties, long ttlMillis, javax.net.SocketFactory socketFactory, LDAPConnectionOptions connectionOptions)
          Creates a new instance of this server set that will use the provided settings.
 
Method Summary
 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 to use for connections that are created, if any.
 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.
 java.lang.String getProviderURL()
          Retrieves the JNDI provider URL that specifies the DNS server(s) to use.
 java.lang.String getRecordName()
          Retrieves the name of the DNS SRV record to retrieve.
 javax.net.SocketFactory getSocketFactory()
          Retrieves the socket factory that will be used when creating connections, if any.
 long getTTLMillis()
          Retrieves the maximum length of time in milliseconds that previously-retrieved DNS information should be cached before it needs to be refreshed.
 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

DNSSRVRecordServerSet

public DNSSRVRecordServerSet(java.lang.String recordName)
Creates a new instance of this server set that will use the specified DNS record name, a default DNS provider URL that will attempt to determine DNS servers from the underlying system configuration, a default TTL of one hour, round-robin ordering for servers with the same priority, and default socket factory and connection options.

Parameters:
recordName - The name of the DNS SRV record to retrieve. If this is null, then a default record name of "_ldap._tcp" will be used.

DNSSRVRecordServerSet

public DNSSRVRecordServerSet(java.lang.String recordName,
                             java.lang.String providerURL,
                             long ttlMillis,
                             javax.net.SocketFactory socketFactory,
                             LDAPConnectionOptions connectionOptions)
Creates a new instance of this server set that will use the provided settings.

Parameters:
recordName - The name of the DNS SRV record to retrieve. If this is null, then a default record name of "_ldap._tcp" will be used.
providerURL - The JNDI provider URL that may be used to specify the DNS server(s) to use. If this is not specified, then a default URL of "dns:" will be used, which will attempt to determine the appropriate servers from the underlying system configuration.
ttlMillis - Specifies the maximum length of time in milliseconds that DNS information should be cached before it needs to be retrieved again. A value less than or equal to zero will use the default TTL of one hour.
socketFactory - The socket factory that will be used when creating 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 that are created. It may be null if the default connection options should be used.

DNSSRVRecordServerSet

public DNSSRVRecordServerSet(java.lang.String recordName,
                             java.lang.String providerURL,
                             java.util.Properties jndiProperties,
                             long ttlMillis,
                             javax.net.SocketFactory socketFactory,
                             LDAPConnectionOptions connectionOptions)
Creates a new instance of this server set that will use the provided settings.

Parameters:
recordName - The name of the DNS SRV record to retrieve. If this is null, then a default record name of "_ldap._tcp" will be used.
providerURL - The JNDI provider URL that may be used to specify the DNS server(s) to use. If this is not specified, then a default URL of "dns:" will be used, which will attempt to determine the appropriate servers from the underlying system configuration.
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 this is null, then a default set of properties will be used.
ttlMillis - Specifies the maximum length of time in milliseconds that DNS information should be cached before it needs to be retrieved again. A value less than or equal to zero will use the default TTL of one hour.
socketFactory - The socket factory that will be used when creating 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 that are created. It may be null if the default connection options should be used.
Method Detail

getRecordName

public java.lang.String getRecordName()
Retrieves the name of the DNS SRV record to retrieve.

Returns:
The name of the DNS SRV record to retrieve.

getProviderURL

public java.lang.String getProviderURL()
Retrieves the JNDI provider URL that specifies the DNS server(s) to use.

Returns:
The JNDI provider URL that specifies the DNS server(s) to use.

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.

getTTLMillis

public long getTTLMillis()
Retrieves the maximum length of time in milliseconds that previously-retrieved DNS information should be cached before it needs to be refreshed.

Returns:
The maximum length of time in milliseconds that previously-retrieved DNS information should be cached before it needs to be refreshed.

getSocketFactory

public javax.net.SocketFactory getSocketFactory()
Retrieves the socket factory that will be used when creating connections, if any.

Returns:
The socket factory that will be used when creating connections, or null if the JVM-default socket factory will be used.

getConnectionOptions

public LDAPConnectionOptions getConnectionOptions()
Retrieves the set of connection options to use for connections that are created, if any.

Returns:
The set of connection options to use for connections that are created, or null if a default set of options should be used.

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.