Package com.linecorp.armeria.client

Class DnsResolverGroupBuilder

java.lang.Object

com.linecorp.armeria.client.AbstractDnsResolverBuilder

com.linecorp.armeria.client.DnsResolverGroupBuilder

public final class DnsResolverGroupBuilder
extends AbstractDnsResolverBuilder

Builds an AddressResolverGroup which builds AddressResolvers that update DNS caches automatically. Standard DnsNameResolver will only expire a cache entry after TTL, meaning DNS queries after TTL will always take time to resolve. A refreshing AddressResolver on the other hand updates the DNS cache automatically when TTL elapses, meaning DNS queries after TTL will retrieve a refreshed result right away. If refreshing fails, the AddressResolver will retry with autoRefreshBackoff(Backoff).

Method Summary

Modifier and Type	Method	Description
DnsResolverGroupBuilder	autoRefreshBackoff(Backoff refreshBackoff)	Sets the Backoff which is used when the DnsNameResolver fails to update the cache.
DnsResolverGroupBuilder	autoRefreshTimeout(Duration timeout)	Sets the timeout after which a refreshing DnsRecord should expire.
DnsResolverGroupBuilder	autoRefreshTimeout(ToLongFunction<? super String> timeoutFunction)	Sets the ToLongFunction which determines how long the DnsRecords for a hostname should be refreshed after the first cache.
DnsResolverGroupBuilder	autoRefreshTimeoutMillis(long timeoutMillis)	Sets the timeout in milliseconds after which a refreshing DnsRecord should expire.
DnsResolverGroupBuilder	cacheSpec(String cacheSpec)	Sets the Caffeine specification string of the cache that stores the domain names and their resolved addresses.
DnsResolverGroupBuilder	decodeIdn(boolean decodeIdn)	Sets if the domain and host names should be decoded to unicode when received.
DnsResolverGroupBuilder	disableDnsQueryMetrics()	Deprecated.
DnsResolverGroupBuilder	dnsCache(DnsCache dnsCache)	Sets the DnsCache that caches the resolved DnsRecords and the cause of a failure if negative cache is activated.
DnsResolverGroupBuilder	dnsQueryLifecycleObserverFactory(DnsQueryLifecycleObserverFactory observerFactory)	Sets the DnsQueryLifecycleObserverFactory that is used to generate objects which can observe individual DNS queries.
DnsResolverGroupBuilder	dnsServerAddressStreamProvider(DnsServerAddressStreamProvider dnsServerAddressStreamProvider)	Deprecated.
DnsResolverGroupBuilder	enableAutoRefresh(boolean autoRefresh)	Sets whether to enable auto refresh for expired DnsRecords.
DnsResolverGroupBuilder	enableDnsQueryMetrics(boolean enable)	Enables the default DnsQueryLifecycleObserverFactory that collects DNS query metrics through MeterRegistry.
DnsResolverGroupBuilder	hostsFileEntriesResolver(HostsFileEntriesResolver hostsFileEntriesResolver)	Sets the HostsFileEntriesResolver which is used to first check if the hostname is locally aliased.
DnsResolverGroupBuilder	maxPayloadSize(int maxPayloadSize)	Sets the capacity of the datagram packet buffer in bytes.
DnsResolverGroupBuilder	maxQueriesPerResolve(int maxQueriesPerResolve)	Sets the base value of maximum allowed number of DNS queries to send when resolving a host name.
DnsResolverGroupBuilder	meterRegistry(MeterRegistry meterRegistry)	Sets MeterRegistry to collect the DNS query metrics.
DnsResolverGroupBuilder	ndots(int ndots)	Sets the number of dots which must appear in a name before an initial absolute query is made.
DnsResolverGroupBuilder	negativeTtl(int negativeTtl)	Sets the TTL of the cache for the failed DNS queries in seconds.
DnsResolverGroupBuilder	optResourceEnabled(boolean optResourceEnabled)	Enables the automatic inclusion of an optional records that tries to give the remote DNS server a hint about how much data the resolver can read per response.
DnsResolverGroupBuilder	queryTimeout(Duration queryTimeout)	Sets the timeout of the DNS query performed by this resolver.
DnsResolverGroupBuilder	queryTimeoutForEachAttempt(Duration queryTimeoutForEachAttempt)	Sets the timeout of each DNS query performed by this endpoint group.
DnsResolverGroupBuilder	queryTimeoutMillis(long queryTimeoutMillis)	Sets the timeout of the DNS query performed by this resolver in milliseconds.
DnsResolverGroupBuilder	queryTimeoutMillisForEachAttempt(long queryTimeoutMillisForEachAttempt)	Sets the timeout of each DNS query performed by this endpoint group in milliseconds.
DnsResolverGroupBuilder	recursionDesired(boolean recursionDesired)	Sets if this resolver has to send a DNS query with the RD (recursion desired) flag set.
DnsResolverGroupBuilder	refreshBackoff(Backoff refreshBackoff)	Deprecated. Use autoRefreshBackoff(Backoff) instead.
DnsResolverGroupBuilder	resolvedAddressTypes(ResolvedAddressTypes resolvedAddressTypes)	Sets ResolvedAddressTypes which is the list of the protocol families of the address resolved.
DnsResolverGroupBuilder	searchDomains(Iterable<String> searchDomains)	Sets the list of search domains of the resolver.
DnsResolverGroupBuilder	searchDomains(String... searchDomains)	Sets the search domains of the resolver.
DnsResolverGroupBuilder	serverAddresses(Iterable<InetSocketAddress> serverAddresses)	Sets the DNS server addresses to send queries to.
DnsResolverGroupBuilder	serverAddresses(InetSocketAddress... serverAddresses)	Sets the DNS server addresses to send queries to.
DnsResolverGroupBuilder	serverAddressStreamProvider(DnsServerAddressStreamProvider serverAddressStreamProvider)	Sets the DnsServerAddressStreamProvider which is used to determine which DNS server is used to resolve each hostname.
DnsResolverGroupBuilder	traceEnabled(boolean traceEnabled)	Sets if this resolver should generate detailed trace information in exception messages so that it is easier to understand the cause of resolution failure.
DnsResolverGroupBuilder	ttl(int minTtl, int maxTtl)	Sets the minimum and maximum TTL of the cached DNS resource records in seconds.

Methods inherited from class com.linecorp.armeria.client.AbstractDnsResolverBuilder

buildConfigurator, cacheSpec, hostsFileEntriesResolver, maxTtl, maybeCreateDnsCache, meterRegistry, minTtl, ndots, negativeTtl, queryTimeoutMillis, searchDomains, serverAddressStreamProvider

Methods inherited from class java.lang.Object

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

Method Details

refreshBackoff

@Deprecated
public DnsResolverGroupBuilder refreshBackoff(Backoff refreshBackoff)

Deprecated.

Use autoRefreshBackoff(Backoff) instead.

Sets Backoff which is used when the DnsNameResolver fails to update the cache.

resolvedAddressTypes

public DnsResolverGroupBuilder resolvedAddressTypes(ResolvedAddressTypes resolvedAddressTypes)

Sets ResolvedAddressTypes which is the list of the protocol families of the address resolved.

See Also:

• DnsNameResolverBuilder.resolvedAddressTypes(ResolvedAddressTypes)

enableAutoRefresh

@UnstableApi
public DnsResolverGroupBuilder enableAutoRefresh(boolean autoRefresh)

Sets whether to enable auto refresh for expired DnsRecords. This option is enabled by default.

If this option is disabled, the expired DnsRecord is removed from the DnsCache and a new DnsQuery will be executed when the next request to the domain is made.

autoRefreshBackoff

public DnsResolverGroupBuilder autoRefreshBackoff(Backoff refreshBackoff)

Sets the Backoff which is used when the DnsNameResolver fails to update the cache.

autoRefreshTimeout

@UnstableApi
public DnsResolverGroupBuilder autoRefreshTimeout(ToLongFunction<? super String> timeoutFunction)

Sets the ToLongFunction which determines how long the DnsRecords for a hostname should be refreshed after the first cache. The ToLongFunction should return the refresh timeout in milliseconds. If a non-positive number is returned, the DnsRecords are removed immediately without refresh.

Note that the timeout function is called whenever the cached DnsRecords expire.

For example:

 AtomicInteger refreshCounter = new AtomicInteger(MAX_NUM_REFRESH);
 dnsResolverGroupBuilder.autoRefreshTimeout(hostname -> {
     if (hostname.endsWith("busy.domain.com")) {
         return Duration.ofDays(7).toMillis(); // Automatically refresh the cached domain for 7 days.
     }
     if (hostname.endsWith("sporadic.domain.dom")) {
         return 0; // Don't need to refresh a sporadically used domain.
     }

     if (hostname.endsWith("counting.domain.dom")) {
         // Allow refreshing up to MAX_NUM_REFRESH times.
         if (refreshCounter.getAndDecrease() > 0) {
             return Long.MAX_VALUE;
         } else {
             refreshCounter.set(MAX_NUM_REFRESH);
             return 0;
         }
     }
     ...
 });
 

autoRefreshTimeout

@UnstableApi
public DnsResolverGroupBuilder autoRefreshTimeout(Duration timeout)

Sets the timeout after which a refreshing DnsRecord should expire. If this option is unspecified and enableAutoRefresh(boolean) is set to true, a cached DnsRecord is automatically refreshed until the ClientFactory is closed. Duration.ZERO disables the timeout.

autoRefreshTimeoutMillis

@UnstableApi
public DnsResolverGroupBuilder autoRefreshTimeoutMillis(long timeoutMillis)

Sets the timeout in milliseconds after which a refreshing DnsRecord should expire. If this option is unspecified and enableAutoRefresh(boolean) is set to true, a cached DnsRecord is automatically refreshed until the ClientFactory is closed. 0 disables the timeout.

traceEnabled

public DnsResolverGroupBuilder traceEnabled(boolean traceEnabled)

Description copied from class: AbstractDnsResolverBuilder

Sets if this resolver should generate detailed trace information in exception messages so that it is easier to understand the cause of resolution failure. This flag is enabled by default.

Overrides:

traceEnabled in class AbstractDnsResolverBuilder

queryTimeout

public DnsResolverGroupBuilder queryTimeout(Duration queryTimeout)

Description copied from class: AbstractDnsResolverBuilder

Sets the timeout of the DNS query performed by this resolver. 0 disables the timeout. If unspecified, 5000 ms will be used.

Overrides:

queryTimeout in class AbstractDnsResolverBuilder

queryTimeoutMillis

public DnsResolverGroupBuilder queryTimeoutMillis(long queryTimeoutMillis)

Description copied from class: AbstractDnsResolverBuilder

Sets the timeout of the DNS query performed by this resolver in milliseconds. 0 disables the timeout. If unspecified, 5000 ms will be used.

Overrides:

queryTimeoutMillis in class AbstractDnsResolverBuilder

queryTimeoutForEachAttempt

public DnsResolverGroupBuilder queryTimeoutForEachAttempt(Duration queryTimeoutForEachAttempt)

Description copied from class: AbstractDnsResolverBuilder

Sets the timeout of each DNS query performed by this endpoint group. This option is useful if you want to set a timeout for each search domain resolution. If unspecified, the value of AbstractDnsResolverBuilder.queryTimeout(Duration) is used.

Overrides:

queryTimeoutForEachAttempt in class AbstractDnsResolverBuilder

queryTimeoutMillisForEachAttempt

public DnsResolverGroupBuilder queryTimeoutMillisForEachAttempt(long queryTimeoutMillisForEachAttempt)

Description copied from class: AbstractDnsResolverBuilder

Sets the timeout of each DNS query performed by this endpoint group in milliseconds. This option is useful if you want to set a timeout for each search domain resolution. If unspecified, the value of AbstractDnsResolverBuilder.queryTimeoutMillis(long) is used.

Overrides:

queryTimeoutMillisForEachAttempt in class AbstractDnsResolverBuilder

recursionDesired

public DnsResolverGroupBuilder recursionDesired(boolean recursionDesired)

Description copied from class: AbstractDnsResolverBuilder

Sets if this resolver has to send a DNS query with the RD (recursion desired) flag set. This flag is enabled by default.

Overrides:

recursionDesired in class AbstractDnsResolverBuilder

maxQueriesPerResolve

public DnsResolverGroupBuilder maxQueriesPerResolve(int maxQueriesPerResolve)

Description copied from class: AbstractDnsResolverBuilder

Sets the base value of maximum allowed number of DNS queries to send when resolving a host name. The actual maximum allowed number of queries will be multiplied by the DnsServerAddressStream.size(). For example, if maxQueriesPerResolve is 5 and DnsServerAddressStream.size() is 2, DNS queries can be executed up to 10 times. The DnsServerAddressStream is provided by DnsServerAddressStreamProvider.

Overrides:

maxQueriesPerResolve in class AbstractDnsResolverBuilder

See Also:

• AbstractDnsResolverBuilder.serverAddressStreamProvider(DnsServerAddressStreamProvider)

serverAddresses

public DnsResolverGroupBuilder serverAddresses(InetSocketAddress... serverAddresses)

Description copied from class: AbstractDnsResolverBuilder

Sets the DNS server addresses to send queries to. Operating system default is used by default.

Overrides:

serverAddresses in class AbstractDnsResolverBuilder

serverAddresses

public DnsResolverGroupBuilder serverAddresses(Iterable<InetSocketAddress> serverAddresses)

Description copied from class: AbstractDnsResolverBuilder

Sets the DNS server addresses to send queries to. Operating system default is used by default.

Overrides:

serverAddresses in class AbstractDnsResolverBuilder

serverAddressStreamProvider

public DnsResolverGroupBuilder serverAddressStreamProvider(DnsServerAddressStreamProvider serverAddressStreamProvider)

Description copied from class: AbstractDnsResolverBuilder

Sets the DnsServerAddressStreamProvider which is used to determine which DNS server is used to resolve each hostname.

Overrides:

serverAddressStreamProvider in class AbstractDnsResolverBuilder

dnsServerAddressStreamProvider

@Deprecated
public DnsResolverGroupBuilder dnsServerAddressStreamProvider(DnsServerAddressStreamProvider dnsServerAddressStreamProvider)

Deprecated.

Description copied from class: AbstractDnsResolverBuilder

Sets the DnsServerAddressStreamProvider which is used to determine which DNS server is used to resolve each hostname.

Overrides:

dnsServerAddressStreamProvider in class AbstractDnsResolverBuilder

maxPayloadSize

public DnsResolverGroupBuilder maxPayloadSize(int maxPayloadSize)

Description copied from class: AbstractDnsResolverBuilder

Sets the capacity of the datagram packet buffer in bytes.

Overrides:

maxPayloadSize in class AbstractDnsResolverBuilder

optResourceEnabled

public DnsResolverGroupBuilder optResourceEnabled(boolean optResourceEnabled)

Description copied from class: AbstractDnsResolverBuilder

Enables the automatic inclusion of an optional records that tries to give the remote DNS server a hint about how much data the resolver can read per response. Some DNS Server may not support this and so fail to answer queries.

Overrides:

optResourceEnabled in class AbstractDnsResolverBuilder

hostsFileEntriesResolver

public DnsResolverGroupBuilder hostsFileEntriesResolver(HostsFileEntriesResolver hostsFileEntriesResolver)

Description copied from class: AbstractDnsResolverBuilder

Sets the HostsFileEntriesResolver which is used to first check if the hostname is locally aliased.

Overrides:

hostsFileEntriesResolver in class AbstractDnsResolverBuilder

dnsQueryLifecycleObserverFactory

public DnsResolverGroupBuilder dnsQueryLifecycleObserverFactory(DnsQueryLifecycleObserverFactory observerFactory)

Description copied from class: AbstractDnsResolverBuilder

Sets the DnsQueryLifecycleObserverFactory that is used to generate objects which can observe individual DNS queries.

Overrides:

dnsQueryLifecycleObserverFactory in class AbstractDnsResolverBuilder

disableDnsQueryMetrics

@Deprecated
public DnsResolverGroupBuilder disableDnsQueryMetrics()

Deprecated.

Description copied from class: AbstractDnsResolverBuilder

Disables the default DnsQueryLifecycleObserverFactory that collects DNS query metrics through MeterRegistry.

Overrides:

disableDnsQueryMetrics in class AbstractDnsResolverBuilder

searchDomains

public DnsResolverGroupBuilder searchDomains(String... searchDomains)

Description copied from class: AbstractDnsResolverBuilder

Sets the search domains of the resolver.

Overrides:

searchDomains in class AbstractDnsResolverBuilder

searchDomains

public DnsResolverGroupBuilder searchDomains(Iterable<String> searchDomains)

Description copied from class: AbstractDnsResolverBuilder

Sets the list of search domains of the resolver.

Overrides:

searchDomains in class AbstractDnsResolverBuilder

ndots

public DnsResolverGroupBuilder ndots(int ndots)

Description copied from class: AbstractDnsResolverBuilder

Sets the number of dots which must appear in a name before an initial absolute query is made.

Overrides:

ndots in class AbstractDnsResolverBuilder

decodeIdn

public DnsResolverGroupBuilder decodeIdn(boolean decodeIdn)

Description copied from class: AbstractDnsResolverBuilder

Sets if the domain and host names should be decoded to unicode when received. See rfc3492. This flag is enabled by default.

Overrides:

decodeIdn in class AbstractDnsResolverBuilder

meterRegistry

public DnsResolverGroupBuilder meterRegistry(MeterRegistry meterRegistry)

Description copied from class: AbstractDnsResolverBuilder

Sets MeterRegistry to collect the DNS query metrics.

Overrides:

meterRegistry in class AbstractDnsResolverBuilder

cacheSpec

public DnsResolverGroupBuilder cacheSpec(String cacheSpec)

Description copied from class: AbstractDnsResolverBuilder

Sets the Caffeine specification string of the cache that stores the domain names and their resolved addresses. If not set, Flags.dnsCacheSpec() is used by default.

Note that AbstractDnsResolverBuilder.cacheSpec(String) and AbstractDnsResolverBuilder.dnsCache(DnsCache) are mutually exclusive.

Overrides:

cacheSpec in class AbstractDnsResolverBuilder

ttl

public DnsResolverGroupBuilder ttl(int minTtl,
 int maxTtl)

Description copied from class: AbstractDnsResolverBuilder

Sets the minimum and maximum TTL of the cached DNS resource records in seconds. If the TTL of the DNS resource record returned by the DNS server is less than the minimum TTL or greater than the maximum TTL, this resolver will ignore the TTL from the DNS server and use the minimum TTL or the maximum TTL instead respectively. The default value is 1 and Integer.MAX_VALUE, which practically tells this resolver to respect the TTL from the DNS server.

Note that AbstractDnsResolverBuilder.ttl(int, int) and AbstractDnsResolverBuilder.dnsCache(DnsCache) are mutually exclusive.

Overrides:

ttl in class AbstractDnsResolverBuilder

negativeTtl

public DnsResolverGroupBuilder negativeTtl(int negativeTtl)

Description copied from class: AbstractDnsResolverBuilder

Sets the TTL of the cache for the failed DNS queries in seconds. The default value is 0 which means that the DNS resolver does not cache when DNS queries are failed.

Note that AbstractDnsResolverBuilder.negativeTtl(int) and AbstractDnsResolverBuilder.dnsCache(DnsCache) are mutually exclusive.

Overrides:

negativeTtl in class AbstractDnsResolverBuilder

dnsCache

public DnsResolverGroupBuilder dnsCache(DnsCache dnsCache)

Description copied from class: AbstractDnsResolverBuilder

Sets the DnsCache that caches the resolved DnsRecords and the cause of a failure if negative cache is activated. This option is useful if you want to share a DnsCache with multiple DNS resolvers. If unspecified, the default DnsCache is used.

Note that if AbstractDnsResolverBuilder.cacheSpec(String), AbstractDnsResolverBuilder.ttl(int, int), or AbstractDnsResolverBuilder.negativeTtl(int) is set, the DNS resolver will create its own DnsCache using the properties. Therefore, AbstractDnsResolverBuilder.cacheSpec(String), AbstractDnsResolverBuilder.ttl(int, int), and AbstractDnsResolverBuilder.negativeTtl(int) are mutually exclusive with AbstractDnsResolverBuilder.dnsCache(DnsCache).

Overrides:

dnsCache in class AbstractDnsResolverBuilder

enableDnsQueryMetrics

public DnsResolverGroupBuilder enableDnsQueryMetrics(boolean enable)

Description copied from class: AbstractDnsResolverBuilder

Enables the default DnsQueryLifecycleObserverFactory that collects DNS query metrics through MeterRegistry. This option is enabled by default.

Overrides:

enableDnsQueryMetrics in class AbstractDnsResolverBuilder