Alibaba Cloud DNS:Android SDK development guide

Overview

The Android SDK is a Java wrapper for the DoH JSON API of HTTPDNS. It provides Java interfaces for Android apps to resolve domain names and includes an efficient local cache that uses TTL and LRU policies. Developers can integrate HTTPDNS into their Android apps to resolve domain name resolution errors and achieve precise, low-cost scheduling.

The SDK offers the following advantages:

• Simple to use

  You only need to integrate the provided SDK to access the HTTPDNS service. The integration method is straightforward and delivers an effortless, convenient resolution experience.

• Zero latency

  The SDK implements an LRU cache that stores resolved IP addresses locally. It proactively refreshes expired TTL-based cache entries to keep cached data current and effective. This enables zero-latency domain name resolution.

For implementation guidance, refer to the alidns_android_demo sample project source code.

Integrate the SDK

Integrate the SDK

allprojects {
  repositories {
    maven {
      url 'https://maven.aliyun.com/repository/public/'
    }
    mavenLocal()
    mavenCentral()
  }
}

dependencies {
     implementation 'com.alibaba.pdns:alidns-android-sdk:2.3.0'
     implementation 'com.google.code.gson:gson:2.8.5'
}

Initialize the SDK

First, identify your Account ID in the console and create keys to obtain your AccessKey ID and AccessKey Secret. Then integrate and initialize the SDK. For specific initialization instructions, see the code examples in the Application section.

public class DnsCacheApplication extends Application{

    private String accountId = "Your Account ID"; // Set the Account ID that you use to access the SDK in the console.
    private String accessKeyId = "Your AccessKey ID"; // Set the AccessKey ID that you use to access the SDK in the console.
    private String accessKeySecret = "Your AccessKey secret"; // Set the AccessKey secret that you use to access the SDK in the console.

    @Override
    public void onCreate() {
       super.onCreate();
       DNSResolver.Init(this,accountId,accessKeyId,accessKeySecret); // Set the Account ID, AccessKey ID, and AccessKey secret that you use to access the SDK in the console.
       // Note: If you configure domain names to be kept in the cache, resolution is automatically initiated when 75% of the TTL elapses. This ensures that the resolution of configured domain names always hits the cache. However, if you use a CDN, the TTL value may be small. This results in many resolution requests and increases costs. Use this method with caution.
       DNSResolver.setKeepAliveDomains(new String[]{"The domain name to be kept in the cache 1","The domain name to be kept in the cache 2",...});
       DNSResolver.getInstance().preLoadDomains(DNSResolver.QTYPE_IPV4,new String[]{"The domain name to be pre-resolved 1","The domain name to be pre-resolved 2",...}); // Set the specified domain names of the IPv4 type for pre-resolution. Replace the pre-resolution domain names with the domain names that you want to resolve using Alibaba Cloud DNS.
    }
}

Your Android app must also declare the following permissions:

<!--Required permissions-->
   <uses-permission android:name="android.permission.INTERNET"/>
   <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
   <uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>

Authenticate the SDK

Starting from version 2.0, this SDK supports authentication to protect user identity security and prevent unauthorized third-party misuse. To enable authentication, refer to Create Keys to create an AccessKey ID and an AccessKey Secret in the console. If you do not configure authentication parameters during SDK initialization, HTTPDNS rejects domain name resolution requests without authentication. This disables domain name resolution functionality and affects your business operations. Therefore, you must configure authentication parameters when initializing the HTTPDNS SDK.

Set authentication parameters as follows:

DNSResolver.Init(this,accountId,accessKeyId,accessKeySecret);

Common SDK integration issues

<application
        android:name=".DnsCacheApplication"
        android:icon="@mipmap/ic_launcher"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:supportsRtl="true"
        android:theme="@style/AppTheme"
        android:usesCleartextTraffic="true">

<uses-library android:name="org.apache.http.legacy" android:required="false"/>

ndk.dir=...\\ndk\\21.4.7075529; // ... is the local NDK installation path

android.useDeprecatedNdk = true;

The SDK supports configuring the HTTP request protocol type for DNS resolution, allowing you to choose between HTTP and HTTPS. The SDK uses HTTPS for DNS resolution by default because it provides better security.HTTPDNS Billing is based on HTTP resolution requests, where HTTPS resolution is billed at five times the HTTP traffic. Select the HTTP request protocol type based on your business needs.

  /**
   * Pre-loads domain names based on the automatically detected network environment (IPv4-only, IPv6-only, or dual-stack).
   * In a dual-stack network environment, both IPv4 and IPv6 resolution results are pre-loaded. You can call this method during SDK initialization when the application starts.
   * This method pre-stores the resolution results in the cache to reduce the latency of subsequent domain name resolutions.
   *
   * @param domains The domain names to be pre-loaded.
   */
   public void preLoadDomains(final String[] domains)

    /**
     * Pre-loads specified domain names for IPv4 or IPv6 resolution.
     * You can call this method during SDK initialization when the application starts. This method pre-stores the resolution results in the cache to reduce the latency of subsequent domain name resolutions.
     *
     * @param qType Specify whether to pre-load domain names for IPv4 or IPv6 resolution.
     * @param domains The domain names to be pre-loaded.
     */
    public void preLoadDomains(String qType, final String[] domains)
   /**
   * Obtains the resolution data for the domain name based on the automatically detected network environment (IPv4-only, IPv6-only, or dual-stack).
   * If the resolution result exists in the cache and has not expired, the result from the cache is returned.
   * If the cache is empty or the cached result has expired, a synchronous network request is sent to the server to obtain the recursive resolution result. The result is then returned to you and stored in the cache.
   *
   * @param host The domain name that you want to resolve.
   * @return The optimal IP address array based on the current network environment.
   */
    public String[] getIpsByHost(String host)

/**
    * Obtains the array of IPv4 records that correspond to the hostname.
    * If the resolution result exists in the cache and has not expired, the result from the cache is returned.
    * If the cache is empty or the cached result has expired, a synchronous network request is sent to the server to obtain the recursive resolution result. The result is then returned to you and stored in the cache.
    *
    * @param hostName The hostname, such as www.taobao.com.
    * @return The array of IPv4 addresses that correspond to the hostname.
    */
  public  String[] getIPsV4ByHost(String hostName) 

   /**
    * Obtains the array of IPv6 records that correspond to the hostname.
    * @param hostName The hostname, such as www.taobao.com.
    * @return The array of IPv6 addresses that correspond to the hostname.
    */
  public String[] getIPsV6ByHost(String hostName) 

  

  /**
   * Obtains the IP address array for the resolved domain name from the cache based on the automatically detected network environment (IPv4-only, IPv6-only, or dual-stack).
   * If the cache is empty, this method returns null and initiates an asynchronous query. The query result is then stored in the cache.
   * If a resolution result exists in the cache and you allow returning expired results, the expired IP addresses are returned, and the cache is updated asynchronously.
   * If you do not allow returning expired results and the cached result has expired, this method returns null and then asynchronously updates the cache.
   *
   * @param host The domain name that you query, such as www.taobao.com.
   * @param isAllowExp Specify whether to return the resolution result of the expired domain name.
   * @return The IP address array for the resolved host from the cache.
   */
   public String[] getIpsByHostFromCache(String host, boolean isAllowExp)
   
    /**
     * Obtains the IP address array of the IPv4 record type for the resolved domain name from the cache.
     * If the cache is empty, this method returns null and initiates an asynchronous query. The query result is then stored in the cache.
     * If a resolution result exists in the cache and you allow returning expired results, the expired IP addresses are returned, and the cache is updated asynchronously.
     * If you do not allow returning expired results and the cached result has expired, this method returns null and then asynchronously updates the cache.
     *
     * @param host The domain name that you query, such as www.taobao.com.
     * @param isAllowExp Specify whether to return the resolution result of the expired domain name.
     * @return Obtain the IP address array of the IPv4 record type from the cache after the host field is resolved.
     */
    private String[] getIpv4ByHostFromCache(String host , boolean isAllowExp)

    /**
     * Obtains the IP address array of the IPv6 record type for the resolved domain name from the cache.
     * If the cache is empty, this method returns null and initiates an asynchronous query. The query result is then stored in the cache.
     * If a resolution result exists in the cache and you allow returning expired results, the expired IP addresses are returned, and the cache is updated asynchronously.
     * If you do not allow returning expired results and the cached result has expired, this method returns null and then asynchronously updates the cache.
     *
     * @param host The domain name that you query, such as www.taobao.com.
     * @param isAllowExp Specify whether to return the resolution result of the expired domain name.
     * @return Obtain the IP address array of the IPv6 record type from the cache after the host field is resolved.
     */
    private String[] getIpv6ByHostFromCache(String host , boolean isAllowExp)

  /**
  * Obtains the DomainInfo object array in the IPv4 records that correspond to the URL.
  * If the resolution result exists in the cache and has not expired, the result from the cache is returned.
  * If the cache is empty or the cached result has expired, a synchronous network request is sent to the server to obtain the recursive resolution result. The result is then returned to you and stored in the cache.
  *
  * @param url The URL, such as http://www.taobao.com.
  * @return Obtain the DomainInfo object array in the IPv4 records that correspond to the URL.
  */
  public DomainInfo[] getIPsV4DInfoByUrl(String url) 

  Note: The URL in the DomainInfo object is the URL in which the host field is automatically replaced by a specific IP address. You do not need to manually replace the host field in the URL.

  /**
   * Obtains the DomainInfo object array in the IPv6 records that correspond to the URL.
   * If the resolution result exists in the cache and has not expired, the result from the cache is returned.
   * If the cache is empty or the cached result has expired, a synchronous network request is sent to the server to obtain the recursive resolution result. The result is then returned to you and stored in the cache.
   * 
   * @param url The URL, such as http://m.taobao.com.
   * @return Obtain the DomainInfo object array in the IPv6 records that correspond to the URL.
   */
   public DomainInfo[] getIPsV6DInfoByUrl(String url) 

  /**
    * Obtains a DomainInfo object in the IPv4 records that correspond to a specific URL.
    * If the resolution result exists in the cache and has not expired, the result from the cache is returned.
    * If the cache is empty or the cached result has expired, a synchronous network request is sent to the server to obtain the recursive resolution result. The result is then returned to you and stored in the cache.
    *
    * @param url The URL, such as http://m.taobao.com.
    * @return Obtain a DomainInfo object in the IPv4 records that correspond to the URL.
    */
    public DomainInfo getIPV4DInfoByUrl(String url) 


  /**
    * Obtains a DomainInfo object in the IPv6 records that correspond to a specific URL.
    * If the resolution result exists in the cache and has not expired, the result from the cache is returned.
    * If the cache is empty or the cached result has expired, a synchronous network request is sent to the server to obtain the recursive resolution result. The result is then returned to you and stored in the cache.
    *
    * @param url The URL, such as http://www.taobao.com.
    * @return Obtain a DomainInfo object in the IPv6 records that correspond to the URL.
    */
   public DomainInfo getIPV6DInfoByUrl(String url) 

   Note: The returned DomainInfo object encapsulates the following properties.

  /**
   * The auto-increment ID of the endpoint.
    */
    public String id = null;

   /**
    * The URL that can be directly used. The host in the URL is replaced by an IP address.
    */
     public String url = null;

    /**
    * The service name that needs to be included in the header of the HTTP request.
    */
    public String host = "";

   /**
    * The returned content body.
    */
   public String data = null;

   /**
    * The time when the request starts.
    */
   public String startTime = null;

   /**
    * The time when the request ends. If the request times out, this value is null.
    */
   public String stopTime = null; 

   /**
   * The returned server status code, such as 200, 404, or 500.
   */
   public String code = null;

  /**
    * Obtains the IPv4 record that corresponds to the hostname.
    * If the resolution result exists in the cache and has not expired, the result from the cache is returned.
     * If the cache is empty or the cached result has expired, a synchronous network request is sent to the server to obtain the recursive resolution result. The result is then returned to you and stored in the cache.
  
    * @param hostName The hostname, such as www.taobao.com.
    * @return A random IPv4 address in the set of IPv4 addresses that correspond to the hostname is returned. If connection speed testing of IP addresses is enabled, the optimal IPv4 address is returned.
    */
  public String getIPV4ByHost(String hostName) 

   /**
    * Obtains the IPv6 record that corresponds to the hostname.
    * If the resolution result exists in the cache and has not expired, the result from the cache is returned.
    * If the cache is empty or the cached result has expired, a synchronous network request is sent to the server to obtain the recursive resolution result. The result is then returned to you and stored in the cache.
  
    * @param hostName The hostname, such as www.taobao.com.
    * @return Obtain a random IPv6 address in the set of IPv6 addresses that correspond to the hostname. If connection speed testing of IP addresses is enabled, the optimal IPv6 address is returned.
    */
   public String getIPV6ByHost(String hostName) 
      

    /**
     * Obtains the statistics on successful and failed requests for HTTPDNS.
     *
     * @return Obtain the JSON array string of the resolution statistics on all domain names.
     */
    public String getRequestReportInfo()
    
     /**
     * Sets the cache reserve for domain names. The resolution of a configured domain name is automatically initiated when 75% of the TTL elapses. This ensures that the resolution of the configured domain name always hits the cache and improves the resolution efficiency of the SDK.
     * We recommend that you do not configure an excessive number of domain names for this feature. The current limit is 10 domain names. This feature is configured independently of the pre-resolution feature.
     *
     * @param persistentCacheDomains
     */
    public synchronized static void setKeepAliveDomains(String[] persistentCacheDomains) {
    
     /**
     * Purges the cache of specified domain names. If the hostname is null, the cache of all domain names is purged.
     *
     * @param domains The array of domain names whose cache you want to purge.
     */
    public void clearHostCache(String[] domains){

URL: Input endpoint, for example http://www.taobao.com.

 String hostname = "www.taobao.com";
 String url = "http://www.taobao.com";

1. Get optimal IP data for the current network environment

String[] ip = DNSResolver.getInstance().getIpsByHost(hostname); // Get the optimal IP address from domain name resolution for the current network.

2. Preload domain name resolution for the current network environment

DNSResolver.getInstance().preLoadDomains(domains); // Pre-resolves domain names. Replace `domains` with the domain names that you want Alibaba Cloud DNS to resolve.

3. Retrieve cached domain name resolutions for the current network environment

String[] ip = DNSResolver.getInstance().getIpsByHostFromCache(hostname,true);// Get domain name resolution data from the cache for the current network environment.

4. Get an IPv4 address

String IPV4 = DNSResolver.getInstance().getIPV4ByHost(hostname); // Get the IPv4 address from domain name resolution.

5. Get an IPv6 address

String IPV6 =  DNSResolver.getInstance().getIPV6ByHost(hostname); // Get the IPv6 address from domain name resolution.

6. Retrieve the resolved IPv4 address from the cache

String[] IPV4 =  DNSResolver.getInstance().getIpv4ByHostFromCache(hostname , true); // Get the resolved IPv4 address from the cache.

7. Retrieve the resolved IPv6 address from the cache

String[] IPV6 =  DNSResolver.getInstance().getIpv6ByHostFromCache(hostname , true); // Get the resolved IPv6 address from the cache.

8. Retrieve the DomainInfo object by URL

DomainInfo dinfo = DNSResolver.getInstance().getIPV4DInfoByUrl(url); // Get the replaced URL.

9. Clear the resolution cache for a specific domain name

DNSResolver.getInstance().clearHostCache(hostName); // Clear the cache for a specified domain name. Set hostName to null to clear the cache for all domain names.

10. Retrieve statistics for successful and failed Alibaba Cloud DNS requests

String reportInfo = DNSResolver.getInstance().getRequestReportInfo(); // Get statistics about successful and failed requests.

The fields in the JSON string array of domain name resolution statistics are described as follows:

 [
      {
         "avgRtt":"1",                         // Average domain name resolution time, in milliseconds (ms)
         "degradeLocalDnsCount": 0,            // Number of times degraded to Local DNS
         "domainName":"www.example.com",       // Domain name being resolved
         "hitDnsCacheCount": 1,                // Number of cache hits
         "httpabnormalCount": 0,               // Number of failed recursive queries
         "isp": "China Mobile",                // ISP name
         "localDnsResolveErrCount": 0,         // Number of Local DNS resolution failures
         "maxRtt": 8.0,                        // Maximum domain name resolution time, in milliseconds (ms)
         "nonetworkCount": 0,                  // Number of times with no network connectivity
         "permissionErrCount": 0,              // Number of user authentication failures
         "queryType": 1,                       // IP type. 1 indicates IPv4. 28 indicates IPv6
         "recursiveReqCount": 1,               // Number of recursive queries
         "reqParameterErrCount": 0,            // Number of request parameter format errors
         "reqPathErrCount": 0,                 // Number of URL errors
         "reqServerErrCount": 0,               // Number of DNS server-side errors
         "reqTimeoutCount": 0,                 // Number of DNS service timeout errors
         "resolveSuccessCount": 1,             // Number of successful resolutions
         "timeoutCount": 0,                    // Number of network timeout errors
         "utfNetWorkErroNum": 0                // Number of data reporting timeout errors
      }
         ......
 ]

Examples

public class MainActivity extends AppCompatActivity {
   private Button button;
   private TextView tvInfo;
   private TextView tvResult;
   private String hostUrl = "http://www.taobao.com"; // Replace this with the hostUrl that you want to resolve.
   private String hostName = "www.taobao.com"; // Replace this with the hostName that you want to resolve.
   private static final String TAG = "PDnsDemo";
   private static ExecutorService pool = Executors.newSingleThreadExecutor();
   private static final String PDNS_RESULT = "pdns_result";
   private static final int SHOW_CONSOLE_TEXT = 10000;
   private Handler mHandler;

   @Override
   protected void onCreate(Bundle savedInstanceState) {
       super.onCreate(savedInstanceState);
       setContentView(R.layout.demo_activity_main);
       init();
       initHandler();
   }

 private void init() {
       tvInfo = findViewById(R.id.tv_respons_info);
       tvResult = findViewById(R.id.tv_respons);
       button = findViewById(R.id.btn_onclik);
       button.setOnClickListener(new View.OnClickListener() {
           public void onClick(View view) {
               new Thread(new Runnable() {
                      @Override
                      public void  run() {
                      // Call the getIPV4ByHost method from the HTTPDNS SDK to obtain the resolved IP address of the target domain name.
                      String ip = DNSResolver.getInstance().getIPV4ByHost(hostName);
                      if(ip != null){
                         tvInfo.setText("The resolved IP for the domain is: "+ ip);
                      }
                      // Call the getIPV4DInfoByUrl method from the HTTPDNS SDK to obtain a DomainInfo object. The URL in this object is the original URL with its host replaced by the resolved IP address.
                      DomainInfo dinfo = DNSResolver.getInstance().getIPV4DInfoByUrl(hostUrl);
                      if (dinfo != null) {
                           showResponse(dinfo);
                      }
                   }
               }).start();
           }
       });
   }

   private void initHandler() {
       mHandler = new Handler() {
           @Override
           public void handleMessage(Message msg) {
               switch (msg.what)  {
                   case SHOW_CONSOLE_TEXT:
                       tvResult.setText(msg.getData().getString(PDNS_RESULT) + "\n");
                       break;
               }
           }
       };
   }

   private void showResponse(final DomainInfo dinfo) {
                // Send an HTTP request
               String requestUrl = dinfo.url;
               HttpURLConnection conn = null;
               try {
                   URL url = new URL(requestUrl);
                   conn = (HttpURLConnection) url.openConnection();
                   // When accessing using an IP address, you must set the host field in the HTTP request header to the resolved domain name.
                   conn.setRequestProperty("Host", url.getHost()); // Set the host field in the HTTP request header.
                   DataInputStream dis = new DataInputStream(conn.getInputStream());
                   int len;
                   byte[] buff = new byte[4096];
                   StringBuilder response = new StringBuilder();
                   while ((len = dis.read(buff)) != -1) {
                       response.append(new String(buff, 0, len));
                   }
                   Log.d(TAG, "Response: " + response.toString());
                   dis.close();
                   sendMessage(response.toString());
               } catch (IOException e) {
                   e.printStackTrace();
               } finally {
                   if (conn != null) {
                       conn.disconnect();
                   }
               }
           }

   private void sendMessage(String message) {
       if (mHandler != null) {
               Message msg = mHandler.obtainMessage();
               Bundle bundle = new Bundle();
               bundle.putString(PDNS_RESULT, message);
               msg.setData(bundle);
               msg.what = SHOW_CONSOLE_TEXT;
               mHandler.sendMessage(msg);
       }
   }
}

public class DnsCacheApplication extends Application {
    
    private String Account ID = "your Account ID"; // Set your Account ID for SDK integration in the console.
    private String AccessKey ID = "your AccessKey ID"; // Set your AccessKey ID for SDK integration in the console.
    private String AccessKey Secret = "your AccessKey secret"; // Set your AccessKey secret for SDK integration in the console.

    @Override
    public void onCreate() {
       super.onCreate();
       DNSResolver.Init(this, Account ID, AccessKey ID, AccessKey Secret); // Configure the Account ID, AccessKey ID, and AccessKey secret for SDK integration in the console.
       DNSResolver.setKeepAliveDomains(new String[]{"domain-name-1", "domain-name-2", ...}); // Configure domain names for cache reserve. These domain names are automatically resolved at 75% of their TTL to ensure cache hits during domain name resolution.
       DNSResolver.getInstance().preLoadDomains(DNSResolver.QTYPE_IPV4, new String[]{"domain-name-to-preload-1", "domain-name-to-preload-2", ...}); // Pre-resolve IPv4 domain names. Replace the preloaded domain names with the domain names you want to resolve using Alibaba Cloud DNS.
    }
}

Best practices for domain name resolution

Pre-resolution + Allow expired replies = Best performance

In high-performance network scenarios, combining pre-resolution with allowing expired replies significantly improves DNS resolution speed—even achieving zero-latency resolution.

Thanks to the SDK’s built-in caching, after pre-resolution, subsequent requests for the same domain name hit the cache directly. This avoids network round trips and greatly improves user experience.

1. Pre-resolution

Enable caching and pre-resolve critical domain names (recommended at app startup).

In the Application class, parse the domain names used in your business logic in advance in the onCreate() method, and cache the results in local memory.

1. For IPv4-only environments

// ******** For scenarios that support IPv4 only *******
public class DnsCacheApplication extends Application{
    private String Account ID = "your Account ID"; // Set your Account ID for SDK integration in the console
    private String AccessKey ID = "your AccessKey ID"; // Set your AccessKey ID for SDK integration in the console
    private String AccessKey Secret = "your AccessKey secret "; // Set your AccessKey secret for SDK integration in the console

    @Override
    public void onCreate() {
       super.onCreate();
       DNSResolver.Init(this,Account ID,AccessKey ID,AccessKey Secret); // Set your Account ID, AccessKey ID, and AccessKey secret for SDK integration in the console
       DNSResolver.setEnableCache(true); // Enable caching. Default value: true
       // IPv4 record type for pre-resolution    
       DNSResolver.getInstance().preLoadDomains(DNSResolver.QTYPE_IPV4,new String[]{"example-domain-1.com","example-domain-2.com",...}); // Pre-resolve domain names of the specified IPv4 type. Replace the sample domain names with the domain names you want to resolve using Alibaba Cloud DNS.
    }
}

2. For IPv6-enabled environments

//********This applies to scenarios that require IPv6 support.*******
public class DnsCacheApplication extends Application{
    private String accountID = "your_account_id"; // Set the Account ID for accessing the SDK from the console.
    private String accessKeyID = "your_accesskey_id"; // Set the AccessKey ID for accessing the SDK from the console.
    private String accessKeySecret = "your_accesskey_secret"; // Set the AccessKey secret for accessing the SDK from the console.

    @Override
    public void onCreate() {
       super.onCreate();
       // Set the Account ID, AccessKey ID, and AccessKey secret for accessing the SDK from the console.
       DNSResolver.Init(this, accountID, accessKeyID, accessKeySecret);
       // Specify whether to enable caching. This feature is enabled by default.
       DNSResolver.setEnableCache(true);
       // Specify whether to enable domain name resolution over an IPv6 network. This feature is disabled by default.
       DNSResolver.setEnableIPv6(true);  
       // Specify whether to enable IP speed testing. This feature is disabled by default.
       DNSResolver.setEnableSpeedTest(true); 
       // Pre-resolve domain names into IPv4 and IPv6 addresses.
       // Pre-resolve the specified domain names of the IPv4 and IPv6 types. Replace the sample domain names with the domain names that you want to resolve using Alibaba Cloud DNS.
       DNSResolver.getInstance().preLoadDomains(DNSResolver.QTYPE_IPV4_IPV6,new String[]{"your_domain_to_preload_1","your_domain_to_preload_2",...});
    }
}

2. Allow expired replies

Use cached results first (allow expired IPs). Before sending a network request, get the IP address from the cache and allow using expired but still usable cache entries. This delivers immediate results—even after TTL expiry—as long as the cache entry exists. This achieves zero wait time.

1. For IPv4-only environments

    //********Applicable to scenarios that support only IPv4*******
    @Override
    public List<InetAddress> lookup(@NonNull String hostname) throws UnknownHostException {
        // Prioritize retrieving IP addresses from the cache (second parameter set to true allows returning expired but active records)
        String[] IPArray = mDNSResolver.getIpv4ByHostFromCache(hostname,true);
        if (IPArray == null || IPArray.length == 0){
            // Cache miss, initiate asynchronous resolution
            IPArray = mDNSResolver.getIPsV4ByHost(hostname);
        }
        if (IPArray != null && IPArray.length > 0) {
            List<InetAddress> inetAddresses = new ArrayList<>();
            InetAddress address;
            for (String ip : IPArray) {
                address = InetAddress.getByName(ip);
                inetAddresses.add(address);
            }
            if (!inetAddresses.isEmpty()) {
                return inetAddresses;
            }
        }
        return okhttp3.Dns.SYSTEM.lookup(hostname);
    }

2. For IPv6-enabled environments

    //********Applies to scenarios that require IPv6 support*******
    @Override
    public List<InetAddress> lookup(@NonNull String hostname) throws UnknownHostException {
        // First retrieve IP addresses from the cache (the second parameter is set to true to allow returning expired but active records)
        String[] IPArray = mDNSResolver.getIpsByHostFromCache(hostname,true);
        if (IPArray == null || IPArray.length == 0){
            // Cache miss: initiate asynchronous resolution
            IPArray = mDNSResolver.getIpsByHost(hostname);
        }
        if (IPArray != null && IPArray.length > 0) {
            List<InetAddress> inetAddresses = new ArrayList<>();
            InetAddress address;
            for (String ip : IPArray) {
                address = InetAddress.getByName(ip);
                inetAddresses.add(address);
            }
            if (!inetAddresses.isEmpty()) {
                return inetAddresses;
            }
        }
        return okhttp3.Dns.SYSTEM.lookup(hostname);
    }

Usage notes

1. After obtaining the IP address of the domain name through HTTPDNS, the client can use this IP to send business requests, and the Host field in the HTTP request header must be set to the original domain name.

2. To ensure normal operation of your business, when the HTTPDNS SDK returns an empty IP address for domain name resolution, application developers must use the original domain-based request URL for fallback requests. The following example code shows this:

   String ip = DNSResolver.getInstance().getIPV4ByHost("domain name");
   if (ip != null) {
   	// Replace the host in the URL with the IP address to make the API request.
   }else {
   	// Make a fallback request using the request URL with the original domain name.
   }

3. To help you get started with the HTTPDNS SDK more quickly, we provide developers with a demo program that you can download locally for reference. Click here to download the demo program.

4. After you complete SDK integration, check the Traffic Analysis section of the console to verify that the integration is successful. If no traffic is generated, verify that the Account ID, AccessKey ID, and AccessKey Secret parameters are configured correctly.

On-premises DNS

Starting with v2.3.0, the HTTPDNS Android SDK supports on-premises DNS deployments.

On-premises DNS is suitable for scenarios with strict compliance or custom resolution policy requirements—such as finance, government, and large internet enterprises. The SDK supports four deployment modes: public cloud DNS only, on-premises DNS only, active-standby hybrid (public cloud DNS + on-premises DNS as mutual fallback), and flexible adaptation to different business architectures.

Core capabilities

• On-premises deployment support: Configure on-premises DNS endpoints using IPv4/IPv6 addresses or host domain names.

• Bidirectional authentication mechanism: Uses customer-specific accessKeyId and accessKeySecret to sign requests, ensuring secure communication.

• Circuit breaking and health check: When a self-managed DNS node fails consecutively three or more times, it is automatically circuit-broken. Thereafter, its availability is checked every minute using the specified healthCheckDomain. After recovery, it is automatically re-enabled.

• Certificate validation control: Enable or disable TLS certificate validation (strongly recommended for production).

• Smart fallback: When primary DNS (public cloud DNS or on-premises DNS) fails beyond a threshold, automatically switch to standby DNS to ensure high availability.

• Seamless API compatibility: Whether using public cloud DNS or on-premises DNS, upper-layer resolution API calls remain identical—no business logic changes needed.

Configuration details

DNSResolver.Init(this, accountID,accessKeyId,accessKeySecret);

DNSResolver.InitFusionDNS(this,new String[]{"1.1.X.X","2.2.X.X"},null,null,"443", "check.example.com", "your_fusion_ak", "your_fusion_sk");
// Optional: Disable certificate validation (staging environment only)
// DNSResolver.setEnableCertificateValidation(false);

// Primary: public cloud DNS
DNSResolver.Init(this, accountID,accessKeyId,accessKeySecret);
    
// Secondary: on-premises DNS
DNSResolver.InitFusionDNS(this,new String[]{"1.1.X.X","2.2.X.X"},null,null,"443", "check.example.com", "your_fusion_ak", "your_fusion_sk");
// Optional: disable certificate validation (staging environment only)
// DNSResolver.setEnableCertificateValidation(false);

// Primary: On-premises DNS
DNSResolver.InitFusionDNS(this,new String[]{"1.1.X.X","2.2.X.X"},null,null,"443", "check.example.com", "your_fusion_ak", "your_fusion_sk");
// Optional: Disable certificate validation (for staging environments only).
// DNSResolver.setEnableCertificateValidation(false);

// Backup: Public cloud DNS
DNSResolver.Init(this, accountID,accessKeyId,accessKeySecret);

New service APIs

To support on-premises DNS deployment and high-availability disaster recovery, the SDK adds three core APIs for configuring on-premises DNS, controlling security policies, and enabling automatic primary-standby failover.

    /** Configures a self-managed DNS server for private deployment. If you use only public DNS, you do not need to call this method.
     *
     * Sets the address and authentication information for the self-managed DNS server.
     * Customers pass the private DNS server's address and authentication credentials through this interface.
     * The SDK uses this information to make requests.
     * @param ctx Context
     * @param serverIpv4Arr Array of IPv4 addresses (can be null)
     * @param serverIpv6Arr Array of IPv6 addresses (can be null)
     * @param serverHostArr Array of host domain names (can be null)
     * @param port Service port (for example, "443". If null, the default value "443" is used)
     * @param healthCheckDomain Domain name used for health checks after circuit breaking. When a DNS resolution service fails consecutively more than three times, circuit breaking is triggered, and the IP address of that service enters the healthCheck state (subsequent requests will not use this service). A timer runs every minute to call the DNS resolution API using this healthCheckDomain to probe whether the DNS resolution service is available. If the probe succeeds, the service returns to the alive state (subsequent requests can use this service)
     * @param accessKeyId Customer's private access key ID (used for authentication)
     * @param accessKeySecret Customer's private access key secret (used for authentication)
     */
    public static void InitFusionDNS(Context ctx,String[] serverIpv4Arr, String[] serverIpv6Arr, String[] serverHostArr, String port, String healthCheckDomain, String accessKeyId, String accessKeySecret)

    /**For on-premises DNS used in private deployments. You do not need to configure this method if you use only public DNS.
     *
     * Specifies whether to enable certificate validation for on-premises DNS (default: true). If the server is not configured with a domain name certificate or an IP certificate, you can set this parameter to false for testing. However, when you deploy to a production environment, we recommend that you set it to true. Otherwise, security risks may arise.
     * @param enable Set to true to enable certificate validation (default: true). Set to false to disable it.
     */
    public static void setEnableCertificateValidation(boolean enable)

    /**When both public cloud DNS and on-premises DNS are configured, specify the number of times DNS resolution fails on the primary DNS before automatically downgrading to the secondary DNS as a fallback. If only one DNS type is configured, you do not need to configure this method.
     *
     * Specify the number of times DNS resolution fails on the primary DNS before automatically downgrading to the secondary DNS as a fallback. If only one DNS type is configured, you do not need to configure this method.
     * @param fallbackThreshold The number of failures (default is 4 when public cloud DNS is primary, or 2 when on-premises DNS is primary).
     * Valid values are from 0 to 4. Setting 0 means immediate downgrade. The maximum value is 4.
     */
     public static void setFallbackThreshold(int fallbackThreshold)