How to perform domain name resolution using the Android SDK - HTTPDNS

Introduction

The HTTPDNS SDK provides domain name resolution APIs and related features, including:

Domain name blacklist. For more information, see Set a domain name blacklist for HTTPDNS.
Custom time to live (TTL). For more information, see Customize the TTL of resolution results.
IP address ranking. For more information, see Enable IP address ranking.

Set domain names for pre-resolution

After your app starts and the SDK is initialized, call this API to set frequently used domain names for pre-resolution. The SDK resolves these domain names in advance, reducing latency for subsequent resolution requests.

If you call this API during runtime, the SDK immediately resolves the specified domain names, refreshes the cached results, and forces a new scheduling decision. This is typically used after certain business actions to update domain name resolution.

Important

To balance resolution efficiency and response speed, the SDK limits each batch to five domain names. If the pre-resolution list contains more than five domain names, the SDK submits the tasks in batches automatically.

`<u>setPreResolveHosts</u>`

API definition

void setPreResolveHosts(ArrayList<String> hostList)

void setPreResolveHosts(ArrayList<String> hostList, RequestIpType requestIpType)

Introduced in version

2.4.0

Class

HttpDnsService

Parameters

Parameter

Type

Required

Description

hostList

ArrayList<String>

Yes

A list of domain names to pre-resolve. If the requestIpType parameter is not specified, the default value is RequestIpType.v4.

Important

The domain name to resolve must be a pure domain name string. It cannot contain a protocol header (such as http://), a path, or a port. Otherwise, resolution may fail.
Wildcard domain names are not supported.

Correct example:

 ArrayList<String>  hostList = new ArrayList<>();
 hostList.add("www.aliyun.com");
 hostList.add("www.taobao.com");

Incorrect example:

 ArrayList<String>  hostList = new ArrayList<>();
 hostList.add("https://www.aliyun.com");
 hostList.add("http://www.taobao.com/help");

requestIpType

RequestIpType

No

The type of IP addresses for pre-resolution. We recommend using RequestIpType.both.

The enumeration of IP address types to resolve. Valid values:

v4: Resolves to IPv4 addresses.
v6: Resolves to IPv6 addresses.
both: Resolves to both IPv4 and IPv6 addresses.
auto: The SDK determines the address type based on the device's current network stack. By default, it resolves to IPv4 addresses. If the current network stack supports IPv6, the SDK also attempts to resolve to IPv6 addresses.

Synchronous domain name resolution

The synchronous resolution API blocks the current thread until a valid result is obtained.
This API first queries the cache. If a valid result exists, the cached result is returned immediately. Otherwise, the API blocks the calling thread and performs resolution in a worker thread. When resolution is complete, it returns the result. If the timeout period is reached, it returns a null value.
To prevent misuse on the main thread, which can cause the app to stutter, the API detects the calling thread. If called from the main thread, the API automatically downgrades to the getHttpDnsResultForHostSyncNonBlocking API.

Important

The total time for synchronous resolution is controlled by the timeout configuration. If resolution does not succeed within the timeout period, an empty result is returned.

`getHttpDnsResultForHostSync`

API definition

HTTPDNSResult getHttpDnsResultForHostSync(String host, RequestIpType requestIpType)

Introduced in version

2.3.2

Class

HttpDnsService

Parameters

Parameter

Type

Required

Description

host

String

Yes

The domain name to resolve.

requestIpType

RequestIpType

Yes

The type of IP addresses to resolve. We recommend using RequestIpType.both.

The enumeration of IP address types to resolve. Valid values:

v4: Resolves to IPv4 addresses.
v6: Resolves to IPv6 addresses.
both: Resolves to both IPv4 and IPv6 addresses.
auto: The SDK determines the address type based on the device's current network stack. By default, it resolves to IPv4 addresses. If the current network stack supports IPv6, the SDK also attempts to resolve to IPv6 addresses.

Return values

Type	Description
HTTPDNSResult	The resolution result.

Sample code

Kotlin

val httpdns = HttpDns.getService(accountID)
val httpDnsResult = dnsService?.getHttpDnsResultForHostSync("www.aliyun.com", RequestIpType.auto)

Java

HttpDnsService httpdns = HttpDns.getService(accountID);
HTTPDNSResult httpDnsResult = httpdns.getHttpDnsResultForHostSync("www.aliyun.com", RequestIpType.auto);

Asynchronous domain name resolution

The asynchronous resolution API does not block the current thread. The result is returned through a callback.
This API first queries the cache. If a valid result exists, the cached result is returned immediately through the callback. Otherwise, the API performs resolution in a worker thread. After resolution is complete or the timeout period is reached, the result is returned through the callback.

Important

The total time for asynchronous resolution is controlled by the timeout configuration. If resolution does not succeed within the timeout period, an empty result is returned through the callback.

`getHttpDnsResultForHostAsync`

API definition

void getHttpDnsResultForHostAsync(String host, RequestIpType type, HttpDnsCallback callback)

Introduced in version

2.4.0

Class

HttpDnsService

Parameters

Parameter	Type	Required	Description
host	String	Yes	The domain name to resolve.
requestIpType	RequestIpType	Yes	The type of IP addresses to resolve. We recommend using RequestIpType.both. The enumeration of IP address types to resolve. Valid values: v4: Resolves to IPv4 addresses. v6: Resolves to IPv6 addresses. both: Resolves to both IPv4 and IPv6 addresses. auto: The SDK determines the address type based on the device's current network stack. By default, it resolves to IPv4 addresses. If the current network stack supports IPv6, the SDK also attempts to resolve to IPv6 addresses.
callback	HttpDnsCallback	Yes	The callback API for the domain name resolution result.

Sample code

Kotlin

val httpdns = HttpDns.getService(accountID)
val httpDnsResult = dnsService?.getHttpDnsResultForHostAsync("www.aliyun.com", RequestIpType.auto, HttpDnsCallback {
                        httpDnsResult = it
                    })

Java

HttpDnsService httpdns = HttpDns.getService(accountID);
HTTPDNSResult httpDnsResult = httpdns.getHttpDnsResultForHostAsync("www.aliyun.com", RequestIpType.auto, new HttpDnsCallback() {
                                void onHttpDnsCompleted(HTTPDNSResult result) {
                                }      
                              });

Synchronous non-blocking domain name resolution

The synchronous non-blocking resolution API does not block the current thread, but may return an empty result.
This API only queries the cache. If no result is cached or the cached result has expired, resolution is performed in a worker thread. After resolution succeeds, the cache is updated for the next call.

`getHttpDnsResultForHostSyncNonBlocking`

API definition

HTTPDNSResult getHttpDnsResultForHostSyncNonBlocking(String host, RequestIpType type)

Introduced in version

2.4.0

Class

HttpDnsService

Parameters

Parameter

Type

Required

Description

host

String

Yes

The domain name to resolve.

requestIpType

RequestIpType

Yes

The type of IP addresses to resolve. We recommend using RequestIpType.both.

The enumeration of IP address types to resolve. Valid values:

v4: Resolves to IPv4 addresses.
v6: Resolves to IPv6 addresses.
both: Resolves to both IPv4 and IPv6 addresses.
auto: The SDK determines the address type based on the device's current network stack. By default, it resolves to IPv4 addresses. If the current network stack supports IPv6, the SDK also attempts to resolve to IPv6 addresses.

Return values

Type	Description
HTTPDNSResult	The resolution result.

Sample code

Kotlin

val httpdns = HttpDns.getService(accountID)
val httpDnsResult = dnsService?.getHttpDnsResultForHostSyncNonBlocking("www.aliyun.com", RequestIpType.auto)

Java

HttpDnsService httpdns = HttpDns.getService(accountID);
HTTPDNSResult httpDnsResult = httpdns.getHttpDnsResultForHostSyncNonBlocking("www.aliyun.com", RequestIpType.auto);

Clear the cache for specific domain names

If you use Alibaba Cloud DNS, you can call this API to clear the local cache so that your domain name configuration changes take effect immediately. For example, assume the domain name xxx.com resolves to ip1. If ip1 is under attack and you need to migrate traffic to ip2, the process is as follows:

In the Alibaba Cloud DNS console, change the IP address for the domain name to ip2. The HTTPDNS server receives this change immediately and purges the ip1 cache on the server.
Manually call this API to clear the local cache for the domain name xxx.com.
The next request from the app triggers the server to fetch the latest IP address, ip2, from the authoritative server, making the new resolution result take effect immediately on the client.

`cleanHostCache`

API definition

void cleanHostCache(ArrayList<String> hosts)

Introduced in version

2.2.2

Note

This operation clears both the memory cache and the local cache.

Class

HttpDnsService

Parameters

Parameter	Type	Required	Description
hosts	ArrayList<String>	Yes	An array of domain names whose caches you want to clear. To clear all data, pass null or an empty array.