Package com.chilkatsoft.chilkat2

Class Dns

java.lang.Object

com.chilkatsoft.chilkat2.ChilkatObject

com.chilkatsoft.chilkat2.Dns

All Implemented Interfaces:

AutoCloseable

public class Dns
extends ChilkatObject

<section class="dns-summary">

Configure DNS resolution and query DNS records directly from Chilkat.

Chilkat.Dns is a focused class for DNS configuration and DNS record querying. It allows applications to control the nameservers used by Chilkat, query common DNS record types into JSON, configure DNS-over-TLS preference, set DNS query timeouts, and obtain useful diagnostics through LastErrorText.

DNS record queries

Query common DNS record types and receive structured JSON results that are easy to inspect or pass to other application logic.

Nameserver control

Configure the nameservers Chilkat uses instead of relying only on the operating system's default DNS configuration.

DNS-over-TLS preference

Prefer DNS-over-TLS when appropriate for applications that need encrypted DNS lookups.

Timeout settings

Control how long DNS queries may wait before failing, which is useful for responsive applications and troubleshooting.

Application-wide behavior

Nameserver settings affect DNS resolution across Chilkat classes, not only the current Dns object.

Diagnostics

Use LastErrorText to troubleshoot DNS configuration, lookup failures, timeout problems, or nameserver connectivity issues.

Common pattern: Use Dns either to perform direct DNS lookups, or to configure the DNS behavior used by Chilkat as a whole. Because nameserver changes can affect DNS resolution across Chilkat classes, treat them as application-wide configuration rather than object-local state.

For an extended overview, see Dns Class Overview.

</section>

Event-capable: long-running methods report progress through a ProgressListener installed with setProgressListener(ProgressListener), onAbortCheck(BooleanSupplier), onPercentDone(IntPredicate) or onProgressInfo(BiConsumer).

Instances hold a native Chilkat object: close them with ChilkatObject.close() (try-with-resources) when done; an unclosed instance is freed when it becomes unreachable.

See Also:

Online reference

Constructor Summary

Constructors

Constructor	Description
Dns()	Creates a new Dns object.

Method Summary

Modifier and Type	Method	Description
void	addDefaultNameservers()	Adds the default (auto-assigned) nameservers to the collection of nameservers used by Chilkat for DNS queries and domain to IP address lookups.
void	addNameserver(String ipAddr, boolean supportsTls)	Adds a new nameserver to the collection of nameservers used by Chilkat for DNS queries and domain to IP address lookups.
int	getHeartbeatMs()	The interval in milliseconds between each AbortCheck event callback, which enables an application to abort certain method calls before they complete.
int	getMaxWaitMs()	The maxiumum number of milliseconds to wait for the answer to a DNS query.
String	getNameserver(int index)	Returns the IP address of the Nth nameserver currently used by Chilkat for DNS queries and domain to IP address lookups.
int	getNumNameservers()	The number of nameservers currently being used by Chilkat for DNS queries in all objects/classes, such as for HTTP, Email, FTP, SSH, etc.
ProgressListener	getProgressListener()	Returns the installed listener, or null.
int	getTlsPref()	Specifies the TLS preference.
String	getUncommonOptions()	This is a catch-all property to be used for uncommon needs.
void	onAbortCheck(BooleanSupplier callback)	Installs a listener whose only callback is abortCheck: called every HeartbeatMs milliseconds during a long-running method; return true to abort it.
void	onPercentDone(IntPredicate callback)	Installs a listener whose only callback is percentDone: called with the completion percentage (0..100) as a long-running method progresses; return true to abort it.
void	onProgressInfo(BiConsumer<String,String> callback)	Installs a listener whose only callback is progressInfo: called with a name/value pair of progress information as a long-running method proceeds.
boolean	query(String recordType, String domain, JsonObject answer)	Performs an DNS query for domain and returns the answer in answer.
void	removeAllNameservers()	Removes all nameservers from the collection of nameservers used by Chilkat.
void	removeNameserver(String ipAddr)	Removes a nameserver from the collection of nameservers used by Chilkat.
void	setHeartbeatMs(int value)	Sets the HeartbeatMs property; see getHeartbeatMs().
void	setMaxWaitMs(int value)	Sets the MaxWaitMs property; see getMaxWaitMs().
void	setProgressListener(ProgressListener listener)	Installs the listener that receives this object's progress events (abortCheck, percentDone, progressInfo) during its long-running methods; replaces any listener or lambda installed before; null removes it.
void	setTlsPref(int value)	Sets the TlsPref property; see getTlsPref().
void	setUncommonOptions(String value)	Sets the UncommonOptions property; see getUncommonOptions().

Methods inherited from class com.chilkatsoft.chilkat2.ChilkatObject

close, getDebugLogFilePath, getLastErrorHtml, getLastErrorText, getLastErrorXml, getLastMethodSuccess, getVerboseLogging, getVersion, isClosed, setDebugLogFilePath, setLastMethodSuccess, setVerboseLogging, toString

Methods inherited from class java.lang.Object

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

Constructor Details

Dns

public Dns()

Creates a new Dns object.

Method Details

getHeartbeatMs

public int getHeartbeatMs()

The interval in milliseconds between each AbortCheck event callback, which enables an application to abort certain method calls before they complete. By default, HeartbeatMs is set to 0, meaning no AbortCheck event callbacks will trigger.

Returns:

the value of the HeartbeatMs property

setHeartbeatMs

public void setHeartbeatMs(int value)

Sets the HeartbeatMs property; see getHeartbeatMs().

Parameters:

value - the new value

getMaxWaitMs

public int getMaxWaitMs()

The maxiumum number of milliseconds to wait for the answer to a DNS query. A value of 0 is to wait indefinitely (no timeout). It's not a good idea to specify 0 (infinite timeout) or a value less than 1000 (1 second). The default value is 10000 milliseconds.

Returns:

the value of the MaxWaitMs property

setMaxWaitMs

public void setMaxWaitMs(int value)

Sets the MaxWaitMs property; see getMaxWaitMs().

Parameters:

value - the new value

getNumNameservers

public int getNumNameservers()

The number of nameservers currently being used by Chilkat for DNS queries in all objects/classes, such as for HTTP, Email, FTP, SSH, etc.

Returns:

the value of the NumNameservers property (read-only)

getTlsPref

public int getTlsPref()

Specifies the TLS preference. Possible values are:

• 0 = No TLS
• 1 = Prefer TLS if possible.
• 2 = Require TLS

The default value is 0. If TLS is preferred then DNS nameservers with TLS capability will be tried first. If none succeed, then UDP/TCP will be tried. If TLS is required, then only TLS capable nameservers will be tried and all DNS queries will use TLS.

Note: To use TLS, your application needs to first specify nameservers by calling AddNameserver once per nameserver with the supportsTls argument set to true.

Returns:

the value of the TlsPref property

setTlsPref

public void setTlsPref(int value)

Sets the TlsPref property; see getTlsPref().

Parameters:

value - the new value

getUncommonOptions

public String getUncommonOptions()

This is a catch-all property to be used for uncommon needs. This property defaults to the empty string and should typically remain empty.

Returns:

the value of the UncommonOptions property

setUncommonOptions

public void setUncommonOptions(String value)

Sets the UncommonOptions property; see getUncommonOptions().

Parameters:

value - the new value (not null)

addDefaultNameservers

public void addDefaultNameservers()

Adds the default (auto-assigned) nameservers to the collection of nameservers used by Chilkat for DNS queries and domain to IP address lookups.

addNameserver

public void addNameserver(String ipAddr,
 boolean supportsTls)

Adds a new nameserver to the collection of nameservers used by Chilkat for DNS queries and domain to IP address lookups. The ipAddr specifies the IPv4 address of the nameserver. The supportsTls indicates if the namserver supports DoT (DNS over TLS. DoT uses port 853 for encrypted DNS communication.) If the TlsPreference property is set to 1 or 2, then Chilkat will use TLS nameservers.

Parameters:

ipAddr - the ipAddr argument (not null)

supportsTls - the supportsTls argument

getNameserver

public String getNameserver(int index)

Returns the IP address of the Nth nameserver currently used by Chilkat for DNS queries and domain to IP address lookups. The index specifies the index of the nameserver. The 1st nameserver is at index 0.

Parameters:

index - the index argument

Returns:

the result (never null)

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

query

public boolean query(String recordType,
 String domain,
 JsonObject answer)

Performs an DNS query for domain and returns the answer in answer. The type of DNS query is specified in recordType and can be A, AAAA, ALIAS, CAA, MX, NS, SOA, TXT. Additional record types can be added as needed.

Parameters:

recordType - the recordType argument (not null)

domain - the domain argument (not null)

answer - the answer argument (not null)

Returns:

the result; this method never throws ChilkatException

removeAllNameservers

public void removeAllNameservers()

Removes all nameservers from the collection of nameservers used by Chilkat. An application can call this method to reset to 0 nameservers before adding new nameservers. If a DNS domain to IP address resolution is needed by Chilkat, then the auto-assigned nameserver IP addresses will be automaticaly restored.

removeNameserver

public void removeNameserver(String ipAddr)

Removes a nameserver from the collection of nameservers used by Chilkat. The ipAddr is the IPv4 address of the nameserver to be removed.

Parameters:

ipAddr - the ipAddr argument (not null)

setProgressListener

public void setProgressListener(ProgressListener listener)

Installs the listener that receives this object's progress events (abortCheck, percentDone, progressInfo) during its long-running methods; replaces any listener or lambda installed before; null removes it.

Parameters:

listener - the listener, or null

Throws:

IllegalStateException - if called from inside one of this object's own callbacks

getProgressListener

public ProgressListener getProgressListener()

Returns the installed listener, or null.

Returns:

the listener installed with setProgressListener(ProgressListener) or one of the on... methods

onAbortCheck

public void onAbortCheck(BooleanSupplier callback)

Installs a listener whose only callback is abortCheck: called every HeartbeatMs milliseconds during a long-running method; return true to abort it. Replaces any listener installed before.

Parameters:

callback - the callback, or null to remove the listener

onPercentDone

public void onPercentDone(IntPredicate callback)

Installs a listener whose only callback is percentDone: called with the completion percentage (0..100) as a long-running method progresses; return true to abort it. Replaces any listener installed before.

Parameters:

callback - the callback, or null to remove the listener

onProgressInfo

public void onProgressInfo(BiConsumer<String,String> callback)

Installs a listener whose only callback is progressInfo: called with a name/value pair of progress information as a long-running method proceeds. Replaces any listener installed before.

Parameters:

callback - the callback, or null to remove the listener