Package uk.num.numlib.api

Interface NumAPI

All Known Implementing Classes:

NumAPIImpl

public interface NumAPI

Method Summary

Modifier and Type	Method	Description
NumAPIContext	begin(java.lang.String moduleId, java.lang.String numId, 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	setPopulatorTopLevelZone(java.lang.String populatorTopLevelZone)	Override the populator top-level zone from 'num.uk' to 'myzone.com' for example.
void	setTCPOnly(boolean flag)	Tell dnsjava to use TCP and not UDP.
void	setTopLevelZone(java.lang.String zone)	Override the top-level zone from 'num.uk' to 'myzone.com' for example.
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.

setTopLevelZone

void setTopLevelZone(java.lang.String zone)
              throws NumInvalidParameterException

Override the top-level zone from 'num.uk' to 'myzone.com' for example.

Parameters:

zone - The top level zone to use for DNS lookups. Replaces the default of 'num.uk'

Throws:

NumInvalidParameterException - if the zone is null or empty

setPopulatorTopLevelZone

void setPopulatorTopLevelZone(java.lang.String populatorTopLevelZone)
                       throws NumInvalidParameterException

Override the populator top-level zone from 'num.uk' to 'myzone.com' for example.

Parameters:

populatorTopLevelZone - The populator top level zone to use for DNS lookups. Replaces the default of 'num.uk'

Throws:

NumInvalidParameterException - if the zone is null or empty

begin

NumAPIContext begin(java.lang.String moduleId,
                    java.lang.String numId,
                    int timeoutMillis)
             throws NumBadModuleIdException,
                    NumBadModuleConfigDataException,
                    NumBadURLException,
                    NumInvalidParameterException,
                    NumBadRecordException,
                    NumDNSQueryException,
                    NumInvalidDNSQueryException,
                    RrSetNoHeadersException,
                    RrSetHeaderFormatException,
                    RrSetIncompleteException

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:

moduleId - E.g. "1" for the Contacts module.

numId - a NUM ID that identifies the location in DNS of a NUM record.

timeoutMillis - the timeout in milliseconds to wait for responses from DNS.

Returns:

a new NumAPIContextBase object.

Throws:

NumBadModuleIdException - on error

NumBadModuleConfigDataException - on error

NumBadURLException - on error

NumInvalidParameterException - on error

NumBadRecordException - on error

NumDNSQueryException - on error

NumInvalidDNSQueryException - on error

RrSetHeaderFormatException - on error

RrSetNoHeadersException - on error

RrSetIncompleteException - 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.