Package uk.num.numlib.api

Interface NumAPI

All Known Implementing Classes:
NumAPIImpl
public interface NumAPI

  • 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 setTCPOnly​(boolean flag)
    Tell dnsjava to use TCP and not UDP.
    void shutdown()
    Stop any outstanding DNS queries still in the Executor.

  • Method Details

    • setTCPOnly

      void setTCPOnly​(boolean flag)
      Tell dnsjava to use TCP and not UDP.
      Parameters:
      flag - true to use TCP only.

    • begin

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

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

      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.

      Note: Calling `get()` on the resulting Future _may_ take up to 20 seconds to return a result if it is waiting for improved results from the scraper service. Better to poll the `handler.getResult()` method periodically for a more responsive interface.

      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

      void shutdown()
      Stop any outstanding DNS queries still in the Executor.