public final class DnsOptions
extends Object


A class configuring the host resolution functionality. Note that while we refer to DNS as the most common mechanism being used for brevity, settings apply to other means of resolving hostnames like hosts file resolution.

Hostnames can be resolved in two ways - either by using the system resolver (using getaddrinfo provided by system libraries), or by using a custom resolver which is tailored for the HTTP networking stack.

The built-in stack provides several advantages over using the global system resolver:

  • It has been tailored to the needs of the HTTP networking stack, particularly speed and stability.
  • getaddrinfo is a blocking call which requires dedicating worker threads and makes cancellation impossible (we need to abandon the thread until the call completes)
  • The getaddrinfo interface gives no insight into the root cause of failures
  • struct addrinfo provides no TTL (Time To Live) of the returned addresses. This restricts flexibility of handling caching (e.g. allowing the use of stale DNS records) and requires us to either rely on OS DNS caches, or be extremely conservative with the TTL.

Most configuration in this class is only applicable if the built-in DNS resolver is used.

Summary

Nested classes

class DnsOptions.Builder

Builder for DnsOptions. 

class DnsOptions.StaleDnsOptions

A class configuring the stale DNS functionality. 

Constants

int DNS_OPTION_DISABLED

Option is disabled.

int DNS_OPTION_ENABLED

Option is enabled.

int DNS_OPTION_UNSPECIFIED

Option is unspecified, platform default value will be used.

Public methods

int getPersistHostCache()

See Builder.setPersistHostCache(int)

Duration getPersistHostCachePeriod()

See Builder.setPersistHostCachePeriod

int getPreestablishConnectionsToStaleDnsResults()

See Builder.setPreestablishConnectionsToStaleDnsResults(int)

int getStaleDns()

See Builder.setStaleDns(int)

DnsOptions.StaleDnsOptions getStaleDnsOptions()

See Builder.setStaleDnsOptions

int getUseHttpStackDnsResolver()

See Builder.setUseHttpStackDnsResolver(int)

Inherited methods

From class java.lang.Object

Object clone()

Creates and returns a copy of this object.

boolean equals(Object obj)

Indicates whether some other object is "equal to" this one.

void finalize()

Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.

final Class<?> getClass()

Returns the runtime class of this Object.

int hashCode()

Returns a hash code value for the object.

final void notify()

Wakes up a single thread that is waiting on this object's monitor.

final void notifyAll()

Wakes up all threads that are waiting on this object's monitor.

String toString()

Returns a string representation of the object.

final void wait(long timeoutMillis, int nanos)

Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.

final void wait(long timeoutMillis)

Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.

final void wait()

Causes the current thread to wait until it is awakened, typically by being notified or interrupted.

Constants

DNS_OPTION_DISABLED

Added in API level 34
Also in S Extensions 7 

public static final int DNS_OPTION_DISABLED

Option is disabled.

Constant Value: 2 (0x00000002)

DNS_OPTION_ENABLED

Added in API level 34
Also in S Extensions 7 

public static final int DNS_OPTION_ENABLED

Option is enabled.

Constant Value: 1 (0x00000001)

DNS_OPTION_UNSPECIFIED

Added in API level 34
Also in S Extensions 7 

public static final int DNS_OPTION_UNSPECIFIED

Option is unspecified, platform default value will be used.

Constant Value: 0 (0x00000000)

Public methods

getPersistHostCache

Added in API level 34
Also in S Extensions 7 

public int getPersistHostCache ()

See Builder.setPersistHostCache(int)

Returns
int Value is one of the following:

getPersistHostCachePeriod

Added in API level 34
Also in S Extensions 7 

public Duration getPersistHostCachePeriod ()

See Builder.setPersistHostCachePeriod

Returns
Duration This value may be null.

getPreestablishConnectionsToStaleDnsResults

Added in API level 34
Also in S Extensions 7 

public int getPreestablishConnectionsToStaleDnsResults ()

See Builder.setPreestablishConnectionsToStaleDnsResults(int)

Returns
int Value is one of the following:

getStaleDns

Added in API level 34
Also in S Extensions 7 

public int getStaleDns ()

See Builder.setStaleDns(int)

Returns
int Value is one of the following:

getStaleDnsOptions

Added in API level 34
Also in S Extensions 7 

public DnsOptions.StaleDnsOptions getStaleDnsOptions ()

See Builder.setStaleDnsOptions

Returns
DnsOptions.StaleDnsOptions This value may be null.

getUseHttpStackDnsResolver

Added in API level 34
Also in S Extensions 7 

public int getUseHttpStackDnsResolver ()

See Builder.setUseHttpStackDnsResolver(int)

Returns
int Value is one of the following:

Content and code samples on this page are subject to the licenses described in the Content License. Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.

Last updated 2026-02-13 UTC.