Package 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 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 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
All Methods Instance Methods Concrete Methods Modifier and Type Method 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, toString
-
-
-
-
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 benull
.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 benull
.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 isnull
, 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 benull
if the JVM-default socket factory should be used.connectionOptions
- The set of connection options that should be used for the connections. It may benull
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 benull
.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 benull
.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 bothproviderURL
andjndiProperties
arenull
, 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 bothproviderURL
andjndiProperties
arenull
, 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). IfproviderURL
isnull
andjndiProperties
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 ofproviderURL
andjndiProperties
is non-null
. If this isnull
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 benull
if the JVM-default socket factory should be used.connectionOptions
- The set of connection options that should be used for the connections. It may benull
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, BindRequest bindRequest, 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 benull
.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 benull
.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 bothproviderURL
andjndiProperties
arenull
, 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 bothproviderURL
andjndiProperties
arenull
, 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). IfproviderURL
isnull
andjndiProperties
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 ofproviderURL
andjndiProperties
is non-null
. If this isnull
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 benull
if the JVM-default socket factory should be used.connectionOptions
- The set of connection options that should be used for the connections. It may benull
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 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
-
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 benull
, 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 benull
, 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 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.
-
-