Package uk.num.numlib.api

Class NumAPIImpl

  • All Implemented Interfaces:
    NumAPI
    public final class NumAPIImpl
extends java.lang.Object
implements NumAPI
    This is the main class for using the num-client-library. Use the default constructor to use the DNS servers configured on your local machine, or override these by supplying a specific DNS host domain name using the alternative constructor.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.String MATCH_NUM_RECORDS  

    • Constructor Summary

      Constructors 
      Constructor Description
      NumAPIImpl()
      Default constructor to initialise the default DNS services and MODL services.
      NumAPIImpl​(java.lang.String[] dnsHosts)
      Support multiple DNS hosts.
      NumAPIImpl​(java.lang.String dnsHost, int port)
      Alternative constructor used to override the default DNS host and port.
      NumAPIImpl​(DNSServices dnsServices, java.lang.String dnsHost)
      Alternative constructor used to override the default DNS hosts.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      NumAPIContext begin​(@NonNull java.lang.String numAddress, int timeoutMillis)
      Initialise a new NumAPIContextBase object for a specific module/NUM ID combination.
      NumAPIContext begin​(@NonNull java.net.URL numAddress, int timeoutMillis)
      Initialise a new NumAPIContextBase object for a specific module/NUM ID combination.
      java.util.concurrent.Future<java.lang.String> retrieveNumRecord​(NumAPIContext ctx, NumAPICallbacks handler, int timeoutMillis)
      This method uses the module context and the supplied Required User Variable values to obtain a fully expanded JSON object from DNS.
      void setTCPOnly​(boolean flag)
      Tell dnsjava to use TCP and not UDP.
      void shutdown()
      Stop any outstanding DNS queries still in the Executor.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Field Detail

      • MATCH_NUM_RECORDS

        public static final java.lang.String MATCH_NUM_RECORDS
        See Also:
        Constant Field Values

    • Constructor Detail

      • NumAPIImpl

        public NumAPIImpl()
        Default constructor to initialise the default DNS services and MODL services.

      • NumAPIImpl

        public NumAPIImpl​(DNSServices dnsServices,
                  java.lang.String dnsHost)
           throws NumInvalidDNSHostException
        Alternative constructor used to override the default DNS hosts. Unit tests rely on this constructor.
        Parameters:
        dnsHost - The DNS host to override the defaults configured for the local machine.
        dnsServices - used to inject dummy DNS services for testing.
        Throws:
        NumInvalidDNSHostException - on error

      • NumAPIImpl

        public NumAPIImpl​(java.lang.String dnsHost,
                  int port)
           throws NumInvalidDNSHostException
        Alternative constructor used to override the default DNS host and port.
        Parameters:
        dnsHost - The DNS host to override the defaults configured for the local machine.
        port - The port to use on the DNS host.
        Throws:
        NumInvalidDNSHostException - on error

    • Method Detail

      • setTCPOnly

        public void setTCPOnly​(boolean flag)
        Tell dnsjava to use TCP and not UDP.
        Specified by:
        setTCPOnly in interface NumAPI
        Parameters:
        flag - true to use TCP only.

      • begin

        public NumAPIContext begin​(@NonNull
                           @NonNull java.lang.String numAddress,
                           int timeoutMillis)
                    throws java.net.MalformedURLException,
                           NumInvalidParameterException
        Initialise a new NumAPIContextBase object for a specific module/NUM ID combination. The returned context object can be used to obtain the list of required user variables that must be set before moving on to retrieveNumRecord().
        Specified by:
        begin in interface NumAPI
        Parameters:
        numAddress - E.g. `domain:module/path` or `user@domain:module/path` module is optional and defaults to 1
        timeoutMillis - the timeout in milliseconds to wait for responses from DNS.
        Returns:
        a new NumAPIContextBase object.
        Throws:
        java.net.MalformedURLException - on error
        NumInvalidParameterException - on error

      • begin

        public NumAPIContext begin​(@NonNull
                           @NonNull java.net.URL numAddress,
                           int timeoutMillis)
                    throws java.net.MalformedURLException,
                           NumInvalidParameterException
        Initialise a new NumAPIContextBase object for a specific module/NUM ID combination. The returned context object can be used to obtain the list of required user variables that must be set before moving on to retrieveNumRecord().
        Specified by:
        begin in interface NumAPI
        Parameters:
        numAddress - E.g. `domain:module/path` or `user@domain:module/path` module is optional and defaults to 1
        timeoutMillis - the timeout in milliseconds to wait for responses from DNS.
        Returns:
        a new NumAPIContextBase object.
        Throws:
        java.net.MalformedURLException - on error
        NumInvalidParameterException - on error

      • retrieveNumRecord

        public java.util.concurrent.Future<java.lang.String> retrieveNumRecord​(NumAPIContext ctx,
                                                                       NumAPICallbacks handler,
                                                                       int timeoutMillis)
        This method uses the module context and the supplied Required User Variable values to obtain a fully expanded JSON object from DNS. The supplied handler will be notified when the results are available or an error occurs.
        Specified by:
        retrieveNumRecord in interface NumAPI
        Parameters:
        ctx - The context object returned by the begin() method.
        handler - a handler object to receive the JSON results or processing errors.
        timeoutMillis - the maximum duration of each DNS request, the total wait time could be up to 4 times this value.
        Returns:
        A Future object

      • shutdown

        public void shutdown()
        Stop any outstanding DNS queries still in the Executor.
        Specified by:
        shutdown in interface NumAPI