com.unboundid.ldap.sdk

Class DNSSRVRecordServerSet

java.lang.Object

com.unboundid.ldap.sdk.ServerSet

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:

• The address of the system providing the service.
• The port to which connections should be established to access the service.
• The priority assigned to the service record. If there are multiple servers that provide the associated service, then the priority can be used to specify the order in which they should be contacted. Records with a lower priority value wil be used before those with a higher priority value.
• The weight assigned to the service record. The weight will be used if there are multiple service records with the same priority, and it controls how likely each record is to be chosen. A record with a weight of 2 is twice as likely to be chosen as a record with the same priority and a weight of 1.

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

Constructors

Constructor and Description
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.
DNSSRVRecordServerSet(java.lang.String recordName, java.lang.String providerURL, java.util.Properties jndiProperties, long ttlMillis, javax.net.SocketFactory socketFactory, LDAPConnectionOptions connectionOptions, BindRequest bindRequest, PostConnectProcessor postConnectProcessor) Creates a new instance of this server set that will use the provided settings.

Method Summary

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

DNSSRVRecordServerSet

public DNSSRVRecordServerSet(@Nullable
                             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(@Nullable
                             java.lang.String recordName,
                             @Nullable
                             java.lang.String providerURL,
                             long ttlMillis,
                             @Nullable
                             javax.net.SocketFactory socketFactory,
                             @Nullable
                             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(@Nullable
                             java.lang.String recordName,
                             @Nullable
                             java.lang.String providerURL,
                             @Nullable
                             java.util.Properties jndiProperties,
                             long ttlMillis,
                             @Nullable
                             javax.net.SocketFactory socketFactory,
                             @Nullable
                             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.

DNSSRVRecordServerSet

public DNSSRVRecordServerSet(@Nullable
                             java.lang.String recordName,
                             @Nullable
                             java.lang.String providerURL,
                             @Nullable
                             java.util.Properties jndiProperties,
                             long ttlMillis,
                             @Nullable
                             javax.net.SocketFactory socketFactory,
                             @Nullable
                             LDAPConnectionOptions connectionOptions,
                             @Nullable
                             BindRequest bindRequest,
                             @Nullable
                             PostConnectProcessor postConnectProcessor)

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.

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

getRecordName

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

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

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

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

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

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.