io.netty.resolver.dns

Class DnsNameResolverBuilder

java.lang.Object

io.netty.resolver.dns.DnsNameResolverBuilder

public final class DnsNameResolverBuilder
extends Object

A DnsNameResolver builder.

Constructor Summary

Constructors

Constructor and Description
DnsNameResolverBuilder() Creates a new builder.
DnsNameResolverBuilder(EventLoop eventLoop) Creates a new builder.

Method Summary

Modifier and Type	Method and Description
DnsNameResolverBuilder	authoritativeDnsServerCache(AuthoritativeDnsServerCache authoritativeDnsServerCache) Sets the cache for authoritative NS servers
DnsNameResolverBuilder	authoritativeDnsServerCache(DnsCache authoritativeDnsServerCache) Deprecated. Use authoritativeDnsServerCache(AuthoritativeDnsServerCache)
DnsNameResolver	build() Returns a new DnsNameResolver instance.
protected ChannelFactory<? extends DatagramChannel>	channelFactory() Deprecated.
DnsNameResolverBuilder	channelFactory(ChannelFactory<? extends DatagramChannel> datagramChannelFactory) Deprecated. use datagramChannelFactory(ChannelFactory)
DnsNameResolverBuilder	channelType(Class<? extends DatagramChannel> channelType) Deprecated. use datagramChannelType(Class)
DnsNameResolverBuilder	cnameCache(DnsCnameCache cnameCache) Sets the cache for CNAME mappings.
DnsNameResolverBuilder	completeOncePreferredResolved(boolean completeOncePreferredResolved) If true SimpleNameResolver.resolveAll(String) will notify the returned Future as soon as all queries for the preferred address-type are complete.
static ResolvedAddressTypes	computeResolvedAddressTypes(InternetProtocolFamily... internetProtocolFamilies) Compute a ResolvedAddressTypes from some InternetProtocolFamilys.
DnsNameResolverBuilder	consolidateCacheSize(int maxNumConsolidation) Set the maximum size of the cache that is used to consolidate lookups for different hostnames when in-flight.
DnsNameResolverBuilder	copy() Creates a copy of this DnsNameResolverBuilder
DnsNameResolverBuilder	datagramChannelFactory(ChannelFactory<? extends DatagramChannel> datagramChannelFactory) Sets the ChannelFactory that will create a DatagramChannel.
DnsNameResolverBuilder	datagramChannelStrategy(DnsNameResolverChannelStrategy datagramChannelStrategy) Set the strategy that is used to determine how a DatagramChannel is used by the resolver for sending queries over UDP protocol.
DnsNameResolverBuilder	datagramChannelType(Class<? extends DatagramChannel> channelType) Sets the ChannelFactory as a ReflectiveChannelFactory of this type.
DnsNameResolverBuilder	decodeIdn(boolean decodeIdn) Set if domain / host names should be decoded to unicode when received.
DnsNameResolverBuilder	dnsQueryLifecycleObserverFactory(DnsQueryLifecycleObserverFactory lifecycleObserverFactory) Set the factory used to generate objects which can observe individual DNS queries.
DnsNameResolverBuilder	eventLoop(EventLoop eventLoop) Sets the EventLoop which will perform the communication with the DNS servers.
DnsNameResolverBuilder	hostsFileEntriesResolver(HostsFileEntriesResolver hostsFileEntriesResolver)
DnsNameResolverBuilder	localAddress(SocketAddress localAddress) Configure the address that will be used to bind too.
DnsNameResolverBuilder	maxPayloadSize(int maxPayloadSize) Sets the capacity of the datagram packet buffer (in bytes).
DnsNameResolverBuilder	maxQueriesPerResolve(int maxQueriesPerResolve) Sets the maximum allowed number of DNS queries to send when resolving a host name.
protected DnsServerAddressStreamProvider	nameServerProvider()
DnsNameResolverBuilder	nameServerProvider(DnsServerAddressStreamProvider dnsServerAddressStreamProvider) Set the DnsServerAddressStreamProvider which is used to determine which DNS server is used to resolve each hostname.
DnsNameResolverBuilder	ndots(int ndots) Set the number of dots which must appear in a name before an initial absolute query is made.
DnsNameResolverBuilder	negativeTtl(int negativeTtl) Sets the TTL of the cache for the failed DNS queries (in seconds).
DnsNameResolverBuilder	optResourceEnabled(boolean optResourceEnabled) Enable the automatic inclusion of a optional records that tries to give the remote DNS server a hint about how much data the resolver can read per response.
protected DnsServerAddressStream	queryServerAddressStream()
DnsNameResolverBuilder	queryServerAddressStream(DnsServerAddressStream queryServerAddressStream) Set the DnsServerAddressStream which provides the server address for DNS queries.
DnsNameResolverBuilder	queryTimeoutMillis(long queryTimeoutMillis) Sets the timeout of each DNS query performed by this resolver (in milliseconds).
DnsNameResolverBuilder	recursionDesired(boolean recursionDesired) Sets if this resolver has to send a DNS query with the RD (recursion desired) flag set.
DnsNameResolverBuilder	resolveCache(DnsCache resolveCache) Sets the cache for resolution results.
DnsNameResolverBuilder	resolvedAddressTypes(ResolvedAddressTypes resolvedAddressTypes) Sets the list of the protocol families of the address resolved.
DnsNameResolverBuilder	searchDomains(Iterable<String> searchDomains) Set the list of search domains of the resolver.
DnsNameResolverBuilder	socketChannelFactory(ChannelFactory<? extends SocketChannel> channelFactory) Sets the ChannelFactory that will create a SocketChannel for TCP fallback if needed.
DnsNameResolverBuilder	socketChannelFactory(ChannelFactory<? extends SocketChannel> channelFactory, boolean retryOnTimeout) Sets the ChannelFactory that will create a SocketChannel for TCP fallback if needed.
DnsNameResolverBuilder	socketChannelType(Class<? extends SocketChannel> channelType) Sets the ChannelFactory as a ReflectiveChannelFactory of this type for TCP fallback if needed.
DnsNameResolverBuilder	socketChannelType(Class<? extends SocketChannel> channelType, boolean retryOnTimeout) Sets the ChannelFactory as a ReflectiveChannelFactory of this type for TCP fallback if needed.
DnsNameResolverBuilder	traceEnabled(boolean traceEnabled) Deprecated. Prefer to configure a LoggingDnsQueryLifeCycleObserverFactory instead.
DnsNameResolverBuilder	ttl(int minTtl, int maxTtl) Sets the minimum and maximum TTL of the cached DNS resource records (in seconds).

Methods inherited from class java.lang.Object

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

Constructor Detail

DnsNameResolverBuilder

public DnsNameResolverBuilder()

Creates a new builder.

DnsNameResolverBuilder

public DnsNameResolverBuilder(EventLoop eventLoop)

Creates a new builder.

Parameters:

eventLoop - the EventLoop which will perform the communication with the DNS servers.

Method Detail

eventLoop

public DnsNameResolverBuilder eventLoop(EventLoop eventLoop)

Sets the EventLoop which will perform the communication with the DNS servers.

Parameters:

eventLoop - the EventLoop

Returns:

this

channelFactory

@Deprecated
protected ChannelFactory<? extends DatagramChannel> channelFactory()

Deprecated.

channelFactory

@Deprecated
public DnsNameResolverBuilder channelFactory(ChannelFactory<? extends DatagramChannel> datagramChannelFactory)

Deprecated. use datagramChannelFactory(ChannelFactory)

Sets the ChannelFactory that will create a DatagramChannel.

If TCP fallback should be supported as well it is required to call the socketChannelFactory(ChannelFactory) or socketChannelType(Class) method.

Parameters:

datagramChannelFactory - the ChannelFactory

Returns:

this

datagramChannelFactory

public DnsNameResolverBuilder datagramChannelFactory(ChannelFactory<? extends DatagramChannel> datagramChannelFactory)

Sets the ChannelFactory that will create a DatagramChannel.

If TCP fallback should be supported as well it is required to call the socketChannelFactory(ChannelFactory) or socketChannelType(Class) method.

Parameters:

datagramChannelFactory - the ChannelFactory

Returns:

this

channelType

@Deprecated
public DnsNameResolverBuilder channelType(Class<? extends DatagramChannel> channelType)

Deprecated. use datagramChannelType(Class)

Sets the ChannelFactory as a ReflectiveChannelFactory of this type. Use as an alternative to channelFactory(ChannelFactory).

If TCP fallback should be supported as well it is required to call the socketChannelFactory(ChannelFactory) or socketChannelType(Class) method.

Parameters:

channelType - the type

Returns:

this

datagramChannelType

public DnsNameResolverBuilder datagramChannelType(Class<? extends DatagramChannel> channelType)

Sets the ChannelFactory as a ReflectiveChannelFactory of this type. Use as an alternative to datagramChannelFactory(ChannelFactory).

If TCP fallback should be supported as well it is required to call the socketChannelFactory(ChannelFactory) or socketChannelType(Class) method.

Parameters:

channelType - the type

Returns:

this

socketChannelFactory

public DnsNameResolverBuilder socketChannelFactory(ChannelFactory<? extends SocketChannel> channelFactory)

Sets the ChannelFactory that will create a SocketChannel for TCP fallback if needed.

TCP fallback is not enabled by default and must be enabled by providing a non-null ChannelFactory for this method.

Parameters:

channelFactory - the ChannelFactory or null if TCP fallback should not be supported. By default, TCP fallback is not enabled.

Returns:

this

socketChannelType

public DnsNameResolverBuilder socketChannelType(Class<? extends SocketChannel> channelType)

Sets the ChannelFactory as a ReflectiveChannelFactory of this type for TCP fallback if needed. Use as an alternative to socketChannelFactory(ChannelFactory).

TCP fallback is not enabled by default and must be enabled by providing a non-null channelType for this method.

Parameters:

channelType - the type or null if TCP fallback should not be supported. By default, TCP fallback is not enabled.

Returns:

this

socketChannelFactory

public DnsNameResolverBuilder socketChannelFactory(ChannelFactory<? extends SocketChannel> channelFactory,
                                                   boolean retryOnTimeout)

Sets the ChannelFactory that will create a SocketChannel for TCP fallback if needed.

TCP fallback is not enabled by default and must be enabled by providing a non-null ChannelFactory for this method.

Parameters:

channelFactory - the ChannelFactory or null if TCP fallback should not be supported. By default, TCP fallback is not enabled.

retryOnTimeout - if true the DnsNameResolver will also fallback to TCP if a timeout was detected, if false it will only try to use TCP if the response was marked as truncated.

Returns:

this

socketChannelType

public DnsNameResolverBuilder socketChannelType(Class<? extends SocketChannel> channelType,
                                                boolean retryOnTimeout)

Sets the ChannelFactory as a ReflectiveChannelFactory of this type for TCP fallback if needed. Use as an alternative to socketChannelFactory(ChannelFactory).

TCP fallback is not enabled by default and must be enabled by providing a non-null channelType for this method.

Parameters:

channelType - the type or null if TCP fallback should not be supported. By default, TCP fallback is not enabled.

retryOnTimeout - if true the DnsNameResolver will also fallback to TCP if a timeout was detected, if false it will only try to use TCP if the response was marked as truncated.

Returns:

this

resolveCache

public DnsNameResolverBuilder resolveCache(DnsCache resolveCache)

Sets the cache for resolution results.

Parameters:

resolveCache - the DNS resolution results cache

Returns:

this

cnameCache

public DnsNameResolverBuilder cnameCache(DnsCnameCache cnameCache)

Sets the cache for CNAME mappings.

Parameters:

cnameCache - the cache used to cache CNAME mappings for a domain.

Returns:

this

dnsQueryLifecycleObserverFactory

public DnsNameResolverBuilder dnsQueryLifecycleObserverFactory(DnsQueryLifecycleObserverFactory lifecycleObserverFactory)

Set the factory used to generate objects which can observe individual DNS queries.

Parameters:

lifecycleObserverFactory - the factory used to generate objects which can observe individual DNS queries.

Returns:

this

authoritativeDnsServerCache

@Deprecated
public DnsNameResolverBuilder authoritativeDnsServerCache(DnsCache authoritativeDnsServerCache)

Deprecated. Use authoritativeDnsServerCache(AuthoritativeDnsServerCache)

Sets the cache for authoritative NS servers

Parameters:

authoritativeDnsServerCache - the authoritative NS servers cache

Returns:

this

authoritativeDnsServerCache

public DnsNameResolverBuilder authoritativeDnsServerCache(AuthoritativeDnsServerCache authoritativeDnsServerCache)

Sets the cache for authoritative NS servers

Parameters:

authoritativeDnsServerCache - the authoritative NS servers cache

Returns:

this

localAddress

public DnsNameResolverBuilder localAddress(SocketAddress localAddress)

Configure the address that will be used to bind too. If null the default will be used.

Parameters:

localAddress - the bind address

Returns:

this

ttl

public DnsNameResolverBuilder ttl(int minTtl,
                                  int maxTtl)

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 0 and Integer.MAX_VALUE, which practically tells this resolver to respect the TTL from the DNS server.

Parameters:

minTtl - the minimum TTL

maxTtl - the maximum TTL

Returns:

this

negativeTtl

public DnsNameResolverBuilder negativeTtl(int negativeTtl)

Sets the TTL of the cache for the failed DNS queries (in seconds).

Parameters:

negativeTtl - the TTL for failed cached queries

Returns:

this

queryTimeoutMillis

public DnsNameResolverBuilder queryTimeoutMillis(long queryTimeoutMillis)

Sets the timeout of each DNS query performed by this resolver (in milliseconds). 0 disables the timeout. If not set or a negative number is set, the default timeout is used.

Parameters:

queryTimeoutMillis - the query timeout

Returns:

this

computeResolvedAddressTypes

public static ResolvedAddressTypes computeResolvedAddressTypes(InternetProtocolFamily... internetProtocolFamilies)

Compute a ResolvedAddressTypes from some InternetProtocolFamilys. An empty input will return the default value, based on "java.net" System properties. Valid inputs are (), (IPv4), (IPv6), (Ipv4, IPv6) and (IPv6, IPv4).

Parameters:

internetProtocolFamilies - a valid sequence of InternetProtocolFamilys

Returns:

a ResolvedAddressTypes

resolvedAddressTypes

public DnsNameResolverBuilder resolvedAddressTypes(ResolvedAddressTypes resolvedAddressTypes)

Sets the list of the protocol families of the address resolved. You can use computeResolvedAddressTypes(InternetProtocolFamily...) to get a ResolvedAddressTypes out of some InternetProtocolFamilys.

Parameters:

resolvedAddressTypes - the address types

Returns:

this

completeOncePreferredResolved

public DnsNameResolverBuilder completeOncePreferredResolved(boolean completeOncePreferredResolved)

If true SimpleNameResolver.resolveAll(String) will notify the returned Future as soon as all queries for the preferred address-type are complete.

Parameters:

completeOncePreferredResolved - true to enable, false to disable.

Returns:

this

recursionDesired

public DnsNameResolverBuilder recursionDesired(boolean recursionDesired)

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

Parameters:

recursionDesired - true if recursion is desired

Returns:

this

maxQueriesPerResolve

public DnsNameResolverBuilder maxQueriesPerResolve(int maxQueriesPerResolve)

Sets the maximum allowed number of DNS queries to send when resolving a host name.

Parameters:

maxQueriesPerResolve - the max number of queries

Returns:

this

traceEnabled

@Deprecated
public DnsNameResolverBuilder traceEnabled(boolean traceEnabled)

Deprecated. Prefer to configure a LoggingDnsQueryLifeCycleObserverFactory instead.

Sets if this resolver should generate the detailed trace information in an exception message so that it is easier to understand the cause of resolution failure.

Parameters:

traceEnabled - true if trace is enabled

Returns:

this

maxPayloadSize

public DnsNameResolverBuilder maxPayloadSize(int maxPayloadSize)

Sets the capacity of the datagram packet buffer (in bytes). The default value is 4096 bytes.

Parameters:

maxPayloadSize - the capacity of the datagram packet buffer

Returns:

this

optResourceEnabled

public DnsNameResolverBuilder optResourceEnabled(boolean optResourceEnabled)

Enable the automatic inclusion of a optional records that tries to give the remote DNS server a hint about how much data the resolver can read per response. Some DNSServer may not support this and so fail to answer queries. If you find problems you may want to disable this.

Parameters:

optResourceEnabled - if optional records inclusion is enabled

Returns:

this

hostsFileEntriesResolver

public DnsNameResolverBuilder hostsFileEntriesResolver(HostsFileEntriesResolver hostsFileEntriesResolver)

Parameters:

hostsFileEntriesResolver - the HostsFileEntriesResolver used to first check if the hostname is locally aliased.

Returns:

this

nameServerProvider

protected DnsServerAddressStreamProvider nameServerProvider()

nameServerProvider

public DnsNameResolverBuilder nameServerProvider(DnsServerAddressStreamProvider dnsServerAddressStreamProvider)

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

Returns:

this.

queryServerAddressStream

protected DnsServerAddressStream queryServerAddressStream()

queryServerAddressStream

public DnsNameResolverBuilder queryServerAddressStream(DnsServerAddressStream queryServerAddressStream)

Set the DnsServerAddressStream which provides the server address for DNS queries.

Returns:

this.

searchDomains

public DnsNameResolverBuilder searchDomains(Iterable<String> searchDomains)

Set the list of search domains of the resolver.

Parameters:

searchDomains - the search domains

Returns:

this

ndots

public DnsNameResolverBuilder ndots(int ndots)

Set the number of dots which must appear in a name before an initial absolute query is made. The default value is 1.

Parameters:

ndots - the ndots value

Returns:

this

decodeIdn

public DnsNameResolverBuilder decodeIdn(boolean decodeIdn)

Set if domain / host names should be decoded to unicode when received. See rfc3492.

Parameters:

decodeIdn - if should get decoded

Returns:

this

consolidateCacheSize

public DnsNameResolverBuilder consolidateCacheSize(int maxNumConsolidation)

Set the maximum size of the cache that is used to consolidate lookups for different hostnames when in-flight. This means if multiple lookups are done for the same hostname and still in-flight only one actual query will be made and the result will be cascaded to the others.

Parameters:

maxNumConsolidation - the maximum lookups to consolidate (different hostnames), or 0 if no consolidation should be performed.

Returns:

this

datagramChannelStrategy

public DnsNameResolverBuilder datagramChannelStrategy(DnsNameResolverChannelStrategy datagramChannelStrategy)

Set the strategy that is used to determine how a DatagramChannel is used by the resolver for sending queries over UDP protocol.

Parameters:

datagramChannelStrategy - the DnsNameResolverChannelStrategy to use when doing queries over UDP protocol.

Returns:

this

build

public DnsNameResolver build()

Returns a new DnsNameResolver instance.

Returns:

a DnsNameResolver

copy

public DnsNameResolverBuilder copy()

Creates a copy of this DnsNameResolverBuilder

Returns:

DnsNameResolverBuilder