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 setting this key, the SDK signs all server requests, enabling request authentication and tamper-proofing.

Interface Definition

InitConfig.Builder setSecretKey(String secretKey)

Class

InitConfig.Builder

Parameters

setAesSecretKey

Sets the key used for encryption during HTTPDNS resolution.

After setting this key, the SDK encrypts request parameters and responses with AES. This enhances security but affects billing. Product Billing.

Interface definition

InitConfig.Builder setAesSecretKey(String aesSecretKey)

Class

InitConfig.Builder

Parameters

setEnableHttps

By default, the SDK uses HTTP for resolution requests. Enable this to use HTTPS instead.

HTTPS provides greater security but is billed differently. Product Billing.

Interface Definition

InitConfig.Builder setEnableHttps(boolean enableHttps)

Class

InitConfig.Builder

Parameters

setTimeoutMillis

Sets the resolution timeout. Default: 2000 ms.

Interface Definition

InitConfig.Builder setTimeoutMillis(int timeoutMillis)

Class

InitConfig.Builder

Parameters

setEnableExpiredIp

The SDK caches resolution results according to their TTL. When the cache expires and the application requests an IP address:

1. Synchronous non-blocking calls return an empty result when the cache has expired, because the SDK cannot immediately retrieve a new result without blocking. Fall back to LocalDNS in this case.

2. Synchronous or asynchronous calls send a resolution request to the server. The synchronous call blocks until a result is obtained; the asynchronous call delivers the result through a callback.

When set to true, resolution operations return the expired IP address immediately instead of waiting, reducing DNS latency. The SDK simultaneously starts an asynchronous refresh to obtain a new result.

Side effects are minimal, especially for domain names with stable resolution (primary sites, static gateways). If resolution does change, only the first request after expiry uses the stale IP, because the SDK always triggers an immediate async update upon finding an expired entry.

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

Sets the initial service node for environments outside China, improving resolution efficiency. The SDK uses this node for resolution and subsequent scheduling updates.

Interface Definition

InitConfig.Builder setRegion(Region region)

Class

InitConfig.Builder

Parameters

setIPRankingList

Sets the IP preference list. When the corresponding domain name is resolved, the SDK performs speed tests on returned IPs and sorts them by availability.

Interface Definition

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

Class

InitConfig.Builder

Parameters

configCacheTtlChanger

Overrides the server-provided TTL for resolution results with a custom value.

Interface Definition

InitConfig.Builder configCacheTtlChanger(CacheTtlChanger changer)

Class

InitConfig.Builder

Parameters

setNotUseHttpDnsFilter

Filters specific domain names from HTTPDNS resolution. Filtered domain names return an empty result; fall back to LocalDNS for these.

Interface Definition

InitConfig.Builder setNotUseHttpDnsFilter(NotUseHttpDnsFilter filter)

Class

InitConfig.Builder

Parameters

setSdnsGlobalParams

Sets global parameters for custom resolution (SDNS). These do not override per-request extra parameters but are merged with them. Every 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);