Package uk.num.numlib.api

Class NumAPIImpl

java.lang.Object

uk.num.numlib.api.NumAPIImpl

All Implemented Interfaces:

NumAPI

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

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

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

Methods inherited from class java.lang.Object

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

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[] dnsHosts)
           throws NumInvalidDNSHostException,
                  NumInvalidParameterException

Support multiple DNS hosts.

Parameters:

dnsHosts - The DNS host String arraymto override the defaults configured for the local machine.

Throws:

NumInvalidDNSHostException - on error

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

setTopLevelZone

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

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

Specified by:

setTopLevelZone in interface NumAPI

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

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

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

Specified by:

setPopulatorTopLevelZone in interface NumAPI

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

public 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().

Specified by:

begin in interface NumAPI

Parameters:

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

numId - a domain name, URL, or email address 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

RrSetIncompleteException - on error

RrSetHeaderFormatException - on error

RrSetNoHeadersException - 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