Package 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.
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 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
All Methods Instance Methods Concrete Methods Modifier and Type Method 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, toString
-
-
-
-
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 isnull
, 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 isnull
, 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 benull
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 benull
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 isnull
, 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 isnull
, 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 benull
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 benull
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, BindRequest bindRequest, 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 isnull
, 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 isnull
, 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 benull
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 benull
if the default connection options should be used.bindRequest
- The bind request that should be used to authenticate newly-established connections. It may benull
if this server set should not perform any authentication.postConnectProcessor
- The post-connect processor that should be invoked on newly-established connections. It may benull
if this server set should not perform any post-connect processing.
-
-
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.
-
includesAuthentication
public boolean includesAuthentication()
Indicates whether connections created by this server set will be authenticated.- Overrides:
includesAuthentication
in classServerSet
- Returns:
true
if connections created by this server set will be authenticated, orfalse
if not.
-
includesPostConnectProcessing
public boolean includesPostConnectProcessing()
Indicates whether connections created by this server set will have post-connect processing performed.- Overrides:
includesPostConnectProcessing
in classServerSet
- Returns:
true
if connections created by this server set will have post-connect processing performed, orfalse
if not.
-
getConnection
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. TheServerSet.includesAuthentication()
must return true if and only if the connection will also be authenticated, and theServerSet.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 theLDAPConnection.getConnectedAddress()
andLDAPConnection.getConnectedPort()
methods.- Specified by:
getConnection
in classServerSet
- 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 that is returned must be established. TheServerSet.includesAuthentication()
must return true if and only if the connection will also be authenticated, and theServerSet.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 theLDAPConnection.getConnectedAddress()
andLDAPConnection.getConnectedPort()
methods.- Overrides:
getConnection
in classServerSet
- Parameters:
healthCheck
- The health check to use to verify the health of the newly-created connection. It may benull
if no additional health check should be performed. If it is non-null
and this server set performs authentication, then the health check'sensureConnectionValidAfterAuthentication
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'sensureNewConnectionValid
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.
-
-