Class Client

  • Direct Known Subclasses:
    ThreadSafeClient

    public class Client
    extends java.lang.Object

    A client for Dedistributed's bulk DNS PTR lookup service. Create and maintain an instance of this class within your application to lookup PTR records using Dedistributed PTR (SAAS).

    For authentication, you must supply your access credentials to the constructor. These credentials consist a self-generated access key and its associated secret. You obtain Access Keys and Secrets via Dedistributed's self-service web application, available to you once you have subscribed to the service and registered with Dedistributed LLC through the AWS Marketplace.

    Latency Optimization

    To minimize latency and maximize throughput, you should choose a preferred PLS server geo-location. You do this by supplying the constructor with an AWS Region name or AWS Availability Zone Id in String form. Whenever possible, the Client is directed to a PLS located within the same Availability Zone. If no PLS instance is available within the specified Availability Zone but one is available within the same Region, your Client instance will be connected to it instead.

    Regions and Availability Zones are specified by their String names. E.g. "us-east-1" (a Region), or "use1-az1" (an AZ Id). See the AWS documentation for Regions and Availability Zones, and for the list of AWS Regions and AZ Ids.

    The underlying network connection used by the Client to communicate with the PLS is a TCP connection, to port 2153. The connection remains open until a call to close() is made, the session expires, or some network failure occurs.

    Session Expiration

    Session expiration is enforced by the PLS after 12-24 hours. If your application has longer lifecycles, you will need to create new instances of Client periodically and rotate them into service. You will need to cease using and close out the old instances. Expect to wait a second or two of time after calling the constructor before the Client is ready for queries.

    ThreadSafeClient Option

    Client is lightweight but is not thread safe. Use ThreadSafeClient for streaming, thread-safe queries. ThreadSafeClient will have a slightly higher CPU cost per call, and depending upon the number of threads making calls and the network latency may also have slightly higher latency for responses (responses are multiplexed through the same underlying TCP connection). Benchmark your application and tune for best results.

    Usage

    To use Client, step by step:

    1. Create an instance of this class via the constructor
    2. To perform a bulk PTR lookup, invoke one of the getPtrRecords() methods
    3. Interpret and use the results in your code (see next section)
    4. Repeat. (Use the same Client again and again)
    5. Close the instance when done (or as needed for expected session expiration)

    Interpreting Results

    Each call to getPtrRecords() returns results in the form of an array of byte arrays (e.g. byte[][]). The number of byte array references in the returned array will always be the same as the number of IP addresses given in the calling argument. The server produces an explicit result for each IP it sees.

    The PTR records are returned in order. If the same IP exists multiple times in the input array parameter, its PTR record value will be returned multiple times.

    For any given offset in the returned array, use the following to interpret the result:

    • If the reference to the byte array is null, there is no PTR record for the corresponding IP
    • If the reference is not null, a PTR record exists in the DNS. Typically, a defined PTR value is non-empty, and so the byte array will have a positive length. The bytes in the array are the PTR record value.
    • If the reference to the byte array is not null but the array is zero-length, then the PTR record published in DNS is a zero-length string (e.g. the empty string ""). This is rare, but it happens.

    Example Code

    The available SDKs include an ExampleApplication. Follow the instructions included in the README within the SDK to edit, compile, and execute it. It will let you get a direct feel for use of Client, and you can use ExampleApplication to both test connectivity and to your confirm validity of your access key and secret.

    See Also:
    ExampleApplication, ThreadSafeClient
    • Constructor Summary

      Constructors 
      Constructor Description
      Client​(java.lang.String access_key, java.lang.String secret, java.lang.String geo_preference)
      Instantiate a new Client.
    • Method Summary

      Modifier and Type Method Description
      void close()
      Close the underlying connection to the PLS held by this Client, and free any other held resources.
      byte[][] getPtrRecords​(byte[] ips)
      Retrieve the PTR records for the IP addresses stored in the input byte array as sets of networked-ordered four-byte sequences.
      byte[][] getPtrRecords​(byte[] ips, int offset, int length)
      Retrieve PTR records for the IPs in the given byte array.
      byte[][] getPtrRecords​(int[] ips)
      Retrieve the PTR records for the IP addresses provided as primitive Java ints in the input array.
      byte[][] getPtrRecords​(java.net.Inet4Address[] addresses)
      Given an array of Inet4Address, obtain the PTR records as an array of bytes[] in the same order as the input.
      • Methods inherited from class java.lang.Object

        equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

      • Client

        public Client​(java.lang.String access_key,
                      java.lang.String secret,
                      java.lang.String geo_preference)
               throws java.io.IOException,
                      PlsConnectException

        Instantiate a new Client. Establish an authorized, consumption-tracked query session. Connect the client via a persistent TCP connection to a Dedistributed PTR Lookup Server (PLS), and prepare to resolve PTR lookup queries.

        The parameter access_key should contain the String representation of one of your Access Keys. Access Keys are positive long integers, implying a string containing numerical ASCII digits only. Example value: "7651125672125".

        The parameter secret, also a String, must contain the hexadecimal representation of the access key's associated 128-bit secret. It is therefore a 32 hexadecimal character String. The hex digits above 9 (e.g. digits "a" through "f") must be lower case. Example: "acbd18db4cc2f85cedef654fccc4a4d8".

        The geo_preference parameter must contain the name of an AWS Region (such as "us-east-1"), the name of an AWS Availability Zone Id (such as "use1-az1"), or be null. See AWS documentation for a list of AWS Region names and AZ Ids. If the value is null, a PLS server will be selected from the pool of active instances, but the one assigned may not be near your client in the sense of network-nearness.

        Parameters:
        access_key - a String containing a positive Java long
        secret - a 32-character hex string (128-bits)
        geo_preference - a Region string, AZ Id string, or null
        Throws:
        PlsConnectException - if a service-level exception occurs
        java.io.IOException - if a network-level exception occurs
    • Method Detail

      • getPtrRecords

        public byte[][] getPtrRecords​(byte[] ips,
                                      int offset,
                                      int length)
                               throws java.io.IOException,
                                      PlsSessionExpireException

        Retrieve PTR records for the IPs in the given byte array. The IP addresses are assumed to be in network order (big-endian), with four bytes to the address (for the 32-bits of an IPv4 address). length should be a positive multiple of four.

        Parameters:
        ips - IP addresses as bytes in network order
        offset - an offset into the byte array where the first IP address begins
        length - the number of bytes representing the set of IPs for the query
        Returns:
        the set of PTR records corresponding to the input IP addresses
        Throws:
        java.io.IOException - if a network-related (socket) failure occurs
        PlsSessionExpireException - when the PLS expires the query session
      • getPtrRecords

        public byte[][] getPtrRecords​(byte[] ips)
                               throws java.io.IOException,
                                      PlsSessionExpireException
        Retrieve the PTR records for the IP addresses stored in the input byte array as sets of networked-ordered four-byte sequences.
        Parameters:
        ips - IP addresses as bytes in network order
        Returns:
        the set of PTR records corresponding to the input IP addresses
        Throws:
        java.io.IOException - if a network-related (socket) failure occurs
        PlsSessionExpireException - when the PLS expires the query session
      • getPtrRecords

        public byte[][] getPtrRecords​(int[] ips)
                               throws java.io.IOException,
                                      PlsSessionExpireException
        Retrieve the PTR records for the IP addresses provided as primitive Java ints in the input array.
        Parameters:
        ips - the IP addresses as Java int
        Returns:
        the set of PTR records corresponding to the input IP addresses
        Throws:
        java.io.IOException - if a network-related (socket) failure occurs
        PlsSessionExpireException - when the PLS expires the query session
      • getPtrRecords

        public byte[][] getPtrRecords​(java.net.Inet4Address[] addresses)
                               throws java.io.IOException,
                                      PlsSessionExpireException
        Given an array of Inet4Address, obtain the PTR records as an array of bytes[] in the same order as the input.
        Parameters:
        addresses - the IP addresses to lookup
        Returns:
        the set of PTR records corresponding to the input IP addresses
        Throws:
        java.io.IOException - if a network-related (socket) failure occurs
        PlsSessionExpireException - when the PLS expires the query session
      • close

        public void close()
                   throws java.io.IOException
        Close the underlying connection to the PLS held by this Client, and free any other held resources. After a call to this method, any subsequent calls and likely any in-flight calls to a getPtrRecords() method will fail.
        Throws:
        java.io.IOException - if an exception occurs upon closing of the Socket and input/output