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

Introduction

The HTTPDNS software development kit (SDK) provides a rich set of domain name resolution APIs and other related features, including the following:

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, immediately call this API to set hot spot domain names that you may use later. This allows the SDK to resolve these domain names in advance and reduces the latency of subsequent resolution requests.

If you call this API during runtime, the SDK immediately resolves the domain names in the specified list. This refreshes the resolution results for these domain names and records them in the cache. This action is equivalent to forcing an update. It is typically used after certain business actions to refresh the current domain name resolution and force a new scheduling decision.

Important

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

`<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

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 resolution result is obtained and returned.
This API first queries the cache. If a valid resolution result exists in the cache, the cached result is returned immediately. If no valid result is found in the cache, the API blocks the calling thread and performs domain name 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 this API from being misused in the main thread, which can cause the app to stutter, the API detects the calling thread. If it is the main thread, the API automatically downgrades to the logic of the getHttpDnsResultForHostSyncNonBlocking API.

Important

The total time that the synchronous resolution API takes is controlled by the timeout configuration. If resolution is not successful within the timeout period, an empty resolution result is returned immediately.

`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	Parsing results.

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 resolution result is returned through a callback.
This API first queries the cache. If a valid resolution result exists in the cache, the cached result is returned immediately through the callback. If no valid result is found in the cache, the API performs domain name 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 that the asynchronous resolution API takes is controlled by the timeout configuration. If resolution is not successful within the timeout period, an empty resolution result is returned immediately 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 it may return an empty result.
This API only queries the cache and returns the resolution result from the cache. If no resolution result is in the cache, or if the cached result has expired, domain name resolution is performed in a worker thread. After the resolution is successful, the cache is updated for the next resolution 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. This allows your domain name configurations to take effect in seconds. For example, assume the domain name xxx.com resolves to the IP address ip1. If ip1 is under attack, 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 immediately receives this change and purges the ip1 cache for the domain name on the server.
Manually call this API to clear the local cache for the domain name xxx.com.
The next request from the app after the cache is cleared triggers the server to request the latest IP address, ip2, from the authoritative server. This makes 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.