HTTPDNS:Java SDK API

Operation definition

static void init(String accountId, InitConfig config)

Class

HttpDnsClient

Parameters

Code example

InitConfig config = new InitConfig.Builder()
    .setSecretKey("your-secret-key")
    .setEnableHttps(true)
    .setTimeoutMillis(2000)
    .setEnableExpiredIp(true)
    .build();

HttpDnsClient.init("your-account-id", config);

Interface Definition

static HttpDnsClient getClient(String accountId)
static HttpDnsClient getClient(String accountId, String secretKey)

Class

HttpDnsClient

Parameters

Return Description

Code example

HttpDnsClient client = HttpDnsClient.getClient("your-account-id");

setSecretKey

Sets the key used to sign requests during HTTPDNS resolution.

After you set the key, the SDK signs requests that are sent to the server. This helps the HTTPDNS server authenticate resolution requests and provides tamper-proofing. This process improves the security of interactions between the SDK and the server.

Interface Definition

InitConfig.Builder setSecretKey(String secretKey)

Class

InitConfig.Builder

Parameters

setAesSecretKey

Sets the key used for encryption during HTTPDNS resolution.

After you set an encryption key, the SDK uses the AES algorithm to encrypt request parameters and responses when it sends requests to the server-side. This encryption feature provides enhanced security, but it also affects the billing logic. For more information, see Product Billing.

Interface definition

InitConfig.Builder setAesSecretKey(String aesSecretKey)

Class

InitConfig.Builder

Parameters

setEnableHttps

By default, the HTTPDNS SDK uses the HTTP protocol to send resolution requests. To use the HTTPS protocol, you can configure the SDK to use HTTPS for domain name resolution.

HTTPS requests provide greater security. However, HTTP and HTTPS requests are billed differently. For more information, see Product Billing.

Interface Definition

InitConfig.Builder setEnableHttps(boolean enableHttps)

Class

InitConfig.Builder

Parameters

setTimeoutMillis

Sets the timeout period for domain name resolution. The default value is 2000 ms.

Interface Definition

InitConfig.Builder setTimeoutMillis(int timeoutMillis)

Class

InitConfig.Builder

Parameters

setEnableExpiredIp

The SDK follows the DNS protocol and caches domain name resolution results according to their Time to Live (TTL). This improves the efficiency of retrieving IP addresses when the application initiates network requests. When the cache expires, if the application calls a resolution operation to retrieve an IP address, different situations occur:

1. If the application calls a synchronous non-blocking operation and the cache has expired, the SDK cannot immediately retrieve a new resolution result from the server. To avoid blocking the thread, the operation returns an empty result. The caller must handle the fallback to LocalDNS resolution.

2. If the application calls a synchronous or asynchronous operation, the SDK sends a resolution request to retrieve a new result from the server. This process takes some time. The synchronous operation blocks the thread until a new result is obtained. The asynchronous operation provides a callback only after a new result is obtained.

The SDK provides an option to reuse expired IP addresses. If you set this option to true, the operations can immediately return the expired IP address even if the cached IP has expired. This reduces the processing time for the DNS step and improves network request performance. At the same time, when the SDK finds that the IP has expired, it also starts an asynchronous thread to resolve the domain name and retrieve a new resolution result.

Therefore, the side effects of enabling this option are minimal, especially when the resolution configuration of the domain name itself does not change frequently, such as for primary site domain names or static gateway domain names. If the domain name resolution does change, enabling this option affects only the first request after the domain's cache expires. This is because when the SDK is called and finds an expired IP, it always immediately initiates an update to the domain name resolution.

Enabled by default.

Interface Definition

InitConfig.Builder setEnableExpiredIp(boolean enableExpiredIp)

Class

InitConfig.Builder

Parameters

enableMemoryCache

Sets whether to enable the memory cache.

Interface Definition

InitConfig.Builder enableMemoryCache(boolean enable)

Class

InitConfig.Builder

Parameters

setRegion

If your application needs to use HTTPDNS in an environment outside China, you can set the startup service node for this SDK to improve resolution efficiency. After you set the node, the SDK uses that node for domain name resolution and for subsequent updates to the scheduling node list.

Interface Definition

InitConfig.Builder setRegion(Region region)

Class

InitConfig.Builder

Parameters

setIPRankingList

Sets the IP preference list. After you configure this operation, if the corresponding domain name is resolved, the SDK performs IP speed tests on the returned IP addresses. It dynamically sorts the returned list to ensure that the first IP address has better availability.

Interface Definition

InitConfig.Builder setIPRankingList(List<? extends IPRankingBean> ipRankingList)

Class

InitConfig.Builder

Parameters

configCacheTtlChanger

By default, each resolution result uses the TTL provided by the server to determine if it has expired. To modify the TTL of a resolution result, you can configure it using this operation.

Interface Definition

InitConfig.Builder configCacheTtlChanger(CacheTtlChanger changer)

Class

InitConfig.Builder

Parameters

setNotUseHttpDnsFilter

To prevent specific domain names from being resolved using HTTPDNS, you can filter out those domain names with this operation. Filtered domain names return an empty resolution result. You need to fall back to LocalDNS for domain name resolution.

Interface Definition

InitConfig.Builder setNotUseHttpDnsFilter(NotUseHttpDnsFilter filter)

Class

InitConfig.Builder

Parameters

setSdnsGlobalParams

Sets global parameters for custom resolution (SDNS). These global parameters do not affect the extra parameter settings of the custom resolution operation. They are merged with the extra parameters of the custom resolution operation. Each custom resolution request carries these global parameters.

Interface Definition

InitConfig.Builder setSdnsGlobalParams(Map<String, String> params)

Class

InitConfig.Builder

Parameters

setPreResolveHosts

Interface Definition

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

Class

HttpDnsClient

Parameters

Code example

List<String> hosts = Arrays.asList("www.example.com", "api.example.com");
client.setPreResolveHosts(hosts, RequestIpType.both);

getHttpDnsResultForHostSyncNonBlocking

Interface definition

HTTPDNSResult getHttpDnsResultForHostSyncNonBlocking(String host, RequestIpType type)
HTTPDNSResult getHttpDnsResultForHostSyncNonBlocking(String host, RequestIpType type, String clientIp)
HTTPDNSResult getHttpDnsResultForHostSyncNonBlocking(String host, RequestIpType type, Map<String, String> params, String cacheKey)
HTTPDNSResult getHttpDnsResultForHostSyncNonBlocking(String host, RequestIpType type, Map<String, String> params, String cacheKey, String clientIp)

Class

HttpDnsClient

Parameters

Return value

Code example

HTTPDNSResult result = client.getHttpDnsResultForHostSyncNonBlocking(
    "www.example.com", 
    RequestIpType.both
);

if (result != null && result.getIps() != null && result.getIps().length > 0) {
    String ip = result.getIps()[0];
}

getHttpDnsResultForHostSync

Interface Definition

HTTPDNSResult getHttpDnsResultForHostSync(String host, RequestIpType type)
HTTPDNSResult getHttpDnsResultForHostSync(String host, RequestIpType type, String clientIp)
HTTPDNSResult getHttpDnsResultForHostSync(String host, RequestIpType type, Map<String, String> params, String cacheKey)
HTTPDNSResult getHttpDnsResultForHostSync(String host, RequestIpType type, Map<String, String> params, String cacheKey, String clientIp)

Class

HttpDnsClient

Parameters

Return value

Code example

HTTPDNSResult result = client.getHttpDnsResultForHostSync(
    "www.aliyun.com", 
    RequestIpType.both
);

getHttpDnsResultForHostAsync

Interface Definition

void getHttpDnsResultForHostAsync(String host, RequestIpType type, HttpDnsCallback callback)
void getHttpDnsResultForHostAsync(String host, RequestIpType type, String clientIp, HttpDnsCallback callback)
void getHttpDnsResultForHostAsync(String host, RequestIpType type, Map<String, String> params, String cacheKey, HttpDnsCallback callback)
void getHttpDnsResultForHostAsync(String host, RequestIpType type, Map<String, String> params, String cacheKey, String clientIp, HttpDnsCallback callback)

Class

HttpDnsClient

Parameters

Code example

client.getHttpDnsResultForHostAsync("www.example.com", RequestIpType.both, 
    new HttpDnsCallback() {
        @Override
        public void onHttpDnsCompleted(HTTPDNSResult result) {
            if (result != null && result.getIps() != null) {
                String[] ips = result.getIps();
                // Use the resolution result.
            }
        }
    });

cleanHostCache

Interface Definition

void cleanHostCache(ArrayList<String> hosts)

Class

HttpDnsClient

Parameters

Code example

// Clear the cache for a specific domain name.
ArrayList<String> hosts = new ArrayList<>();
hosts.add("www.example.com");
client.cleanHostCache(hosts);

// Clear all caches.
client.cleanHostCache(null);

getSessionId

Interface Definition

String getSessionId()

Class

HttpDnsClient

Return value

Code example

String sessionId = client.getSessionId();
System.out.println("SessionId: " + sessionId);

getSdkVersion

Interface Definition

String getSdkVersion()

Class

HttpDnsClient

Return value

Code example

String version = client.getSdkVersion();
System.out.println("SDK Version: " + version);

HttpDnsLog.enable

Sets whether to enable logging for HTTPDNS. It is disabled by default.

Interface Definition

static void enable(boolean enable)

Class

HttpDnsLog

Parameters

Code example

HttpDnsLog.enable(true);

HttpDnsLog.setLogger

You can retrieve the logs that are output by the SDK by setting a log callback class.

Interface Definition

static void setLogger(ILogger logger)

Class

HttpDnsLog

Parameters

Code example

HttpDnsLog.setLogger(new ILogger() {
    @Override
    public void log(String msg) {
        System.out.println("[HTTPDNS] " + msg);
    }
});

HttpDnsLog.removeLogger

Deletes the log callback class.

Interface Definition

static void removeLogger(ILogger logger)

Class

HttpDnsLog

Parameters

Code example

HttpDnsLog.removeLogger(myLogger);

setRegion

Interface Definition

void setRegion(Region region)

Class

HttpDnsClient

Parameters

Code example

client.setRegion(Region.HK);  // Switch to the China (Hong Kong) node.

setAuthCurrentTime

Interface Definition

void setAuthCurrentTime(long time)

Class

HttpDnsClient

Parameters

Code example

HttpDnsClient client = HttpDnsClient.getClient(accountId);
client.setAuthCurrentTime(System.currentTimeMillis());

getHost

Retrieves the corresponding domain name.

Interface Definition

String getHost()

Return value

getIps

Retrieves the resolved IPv4 addresses.

Interface Definition

String[] getIps()

Return value

getIpv6s

Retrieves the resolved IPv6 addresses.

Interface Definition

String[] getIpv6s()

Return value

getExtras

Retrieves extra parameters from the resolution. Only custom resolutions have this data.

Interface Definition

String getExtras()

Return value

isExpired

Indicates whether the resolution result has expired. Expiration is calculated based on the time the result was obtained and the TTL configured for the domain name.

Interface Definition

boolean isExpired()

Return value

getTtl

Retrieves the Time to Live (TTL) of the resolution result.

Interface Definition

int getTtl()

Return value

onHttpDnsCompleted

The callback function after the resolution is complete. This function is called for both success and failure.

Interface Definition

void onHttpDnsCompleted(HTTPDNSResult result)

Parameters

Code example

client.getHttpDnsResultForHostAsync("www.example.com", RequestIpType.both, 
    new HttpDnsCallback() {
        @Override
        public void onHttpDnsCompleted(HTTPDNSResult result) {
            if (result != null && result.getIps() != null) {
                // Resolution succeeded.
            } else {
                // Resolution failed or no result.
            }
        }
    });

log

The log method.

Interface Definition

void log(String msg)

Parameters

Code example

HttpDnsLog.setLogger(new ILogger() {
    @Override
    public void log(String msg) {
        // Custom log processing.
        System.out.println("[HTTPDNS] " + msg);
    }
});

changeCacheTtl

Customizes the TTL.

Interface Definition

int changeCacheTtl(String host, RequestIpType type, int ttl)

Parameters

Response Description

Code example

new InitConfig.Builder()
    .configCacheTtlChanger(new CacheTtlChanger() {
        @Override
        public int changeCacheTtl(String host, RequestIpType type, int ttl) {
            if ("www.aliyun.com".equals(host)) {
                return ttl * 10;
            }
            return ttl;
        }
    });

notUseHttpDns

Configures domain names that should not be resolved by HTTPDNS.

Interface Definition

boolean notUseHttpDns(String hostName)

Parameters

Return value

Code example

new InitConfig.Builder()
    .setNotUseHttpDnsFilter(new NotUseHttpDnsFilter() {
        @Override
        public boolean notUseHttpDns(String hostName) {
            return "www.aliyun.com".equals(hostName);
        }
    });

Constructor

IPRankingBean(String hostName, int port)

Parameters

getHostName

Retrieves the domain name.

Interface Definition

String getHostName()

getPort

Retrieves the port.

Interface Definition

int getPort()

Code example

List<IPRankingBean> list = new ArrayList<>();
list.add(new IPRankingBean("www.example.com", 443));
list.add(new IPRankingBean("api.example.com", 8080));

new InitConfig.Builder()
    .setIPRankingList(list);