Package uk.num.numlib.api

Class NumAPIImpl

java.lang.Object
uk.num.numlib.api.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​(uk.num.numlib.dns.DNSServices dnsServices, java.lang.String dnsHost)
    Alternative constructor used to override the default DNS hosts.

  • Method Summary

    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 setModulesLocation​(java.lang.String modulesLocation)  
    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 Details

  • Constructor Details

    • NumAPIImpl

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

    • NumAPIImpl

      public NumAPIImpl​(uk.num.numlib.dns.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[] dnsHosts) throws NumInvalidDNSHostException, uk.num.numlib.exc.NumInvalidParameterException
      Support multiple DNS hosts.
      Parameters:
      dnsHosts - The DNS host String arraymto override the defaults configured for the local machine.
      Throws:
      NumInvalidDNSHostException - on error
      uk.num.numlib.exc.NumInvalidParameterException - 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 Details

    • 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, uk.num.numlib.exc.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
      uk.num.numlib.exc.NumInvalidParameterException - on error

    • begin

      public NumAPIContext begin​(@NonNull @NonNull java.net.URL numAddress, int timeoutMillis) throws java.net.MalformedURLException, uk.num.numlib.exc.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
      uk.num.numlib.exc.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

    • setModulesLocation

      public void setModulesLocation​(java.lang.String modulesLocation)