Package uk.num.numlib.api

Class NumAPI

java.lang.Object

uk.num.numlib.api.NumAPI

public class NumAPI
extends java.lang.Object

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 int	MAX_NUM_REDIRECTS

Constructor Summary

Constructors

Constructor	Description
NumAPI()	Default constructor to initialise the default DNS services and MODL services.
NumAPI(java.lang.String dnsHost)	Alternative constructor used to override the default DNS hosts.
NumAPI(java.lang.String dnsHost, int port)	Alternative constructor used to override the default DNS host and port.
NumAPI(DNSServices dnsServices, ModlServices modlServices)	Constructor allowing the core services to be overridden, mainly for testing purposes, but could also be useful for other purposes.

Method Summary

Modifier and Type	Method	Description
NumAPIContext	begin(java.lang.String moduleId, java.lang.String netString, int timeoutMillis)	Initialise a new NumAPIContextBase object for a specific module/domain 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	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

Field Detail

MAX_NUM_REDIRECTS

public static final int MAX_NUM_REDIRECTS

See Also:

Constant Field Values

Constructor Detail

NumAPI

public NumAPI()

Default constructor to initialise the default DNS services and MODL services.

NumAPI

public NumAPI(DNSServices dnsServices,
              ModlServices modlServices)

Constructor allowing the core services to be overridden, mainly for testing purposes, but could also be useful for other purposes.

Parameters:

dnsServices - Replacement DNSServices implementation.

modlServices - Replacement ModlServices implementation.

NumAPI

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

Throws:

NumInvalidDNSHostException - on error

NumAPI

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

Parameters:

flag - true to use TCP only.

setTopLevelZone

public void setTopLevelZone(java.lang.String zone)

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'

begin

public NumAPIContext begin(java.lang.String moduleId,
                           java.lang.String netString,
                           int timeoutMillis)
                    throws NumBadModuleIdException,
                           NumBadModuleConfigDataException,
                           NumBadURLException,
                           NumInvalidParameterException,
                           NumBadRecordException,
                           NumDNSQueryException,
                           NumInvalidDNSQueryException

Initialise a new NumAPIContextBase object for a specific module/domain 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.

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

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.

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.