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 Detail

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 NumBadModuleIdException,
                    NumInvalidParameterException,
                    NumBadRecordException,
                    NumDNSQueryException,
                    NumInvalidDNSQueryException,
                    RrSetNoHeadersException,
                    RrSetHeaderFormatException,
                    RrSetIncompleteException,
                    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:

NumBadModuleIdException - on error

java.net.MalformedURLException - on error

NumInvalidParameterException - on error

NumBadRecordException - on error

NumDNSQueryException - on error

NumInvalidDNSQueryException - on error

RrSetHeaderFormatException - on error

RrSetNoHeadersException - on error

RrSetIncompleteException - on error

begin

NumAPIContext begin(@NonNull
                    @NonNull java.net.URL numAddress,
                    int timeoutMillis)
             throws 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

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.