com.verisign.getdns

Class GetDNSFactory

java.lang.Object

com.verisign.getdns.GetDNSFactory

public class GetDNSFactory
extends java.lang.Object

This class is used to create a getdns context

Many calls in the DNS API require a DNS context. A DNS context contains the information that the API needs in order to process DNS calls, such as the locations of upstream DNS servers, DNSSEC trust anchors, and so on. The internal structure of the DNS context is opaque, and might be different on each OS. A typical application using this API doesn't need to know anything about contexts. Basically, the application creates a default context, uses its functions, and then closes it when done. Context manipulation is available for more DNS-aware programs, but is unlikely to be of interest to applications that just want the results of lookups for A, AAAA, SRV, and PTR records. It is expected that contexts in implementations of the API will not necessarily be thread-safe, but they will not be thread-hostile.

A context should not be used by multiple threads: create a new context for use on a different thread. It is just fine for an application to have many contexts, and some DNS-heavy applications will certainly want to have many even if the application uses a single thread. See below for the methods for creating contexts. When the context is used in the API for the first time and setFromOs is 1, the API starts replacing some of the values with values from the OS, such as those that would be found in res_query(3), /etc/resolv.conf, and so on, then proceeds with the new function. Some advanced users will not want the API to change the values to the OS's defaults; if setFromOs is 0, the API will not do any updates to the initial values based on changes in the OS. For example, this might be useful if the API is acting as a stub resolver that is using a specific upstream recursive resolver chosen by the application, not the one that might come back from DHCP.

Constructor Summary

Constructors

Constructor and Description
GetDNSFactory()

Method Summary

Methods

Modifier and Type	Method and Description
static IGetDNSContextAsyncWithCallback	createAsyncWithCallback(int setFromOs, java.util.HashMap<ContextOptionName,java.lang.Object> contextOptions) Creates a context for calling the API asynchronously using a callback mechanism. That is, when an application calls one of these asynchronous functions and provides a callback, the API will invoke the callback with the response or exception when run() is invoked
static IGetDNSContextAsyncWithFuture	createAsyncWithFuture(int setFromOs, java.util.HashMap<ContextOptionName,java.lang.Object> contextOptions) Creates a context for calling the API asynchronously using Future. That is, when an application calls one of these asynchronous functions, the API returns a future object which will be populated with the response or exception when run() is invoked
static IGetDNSContextSync	createSync(int setFromOs, java.util.HashMap<ContextOptionName,java.lang.Object> contextOptions) Creates a context for calling the API synchronously. That is, when an application calls one of these synchronous functions, the API gathers all the required information and then returns the result

Methods inherited from class java.lang.Object

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

Constructor Detail

GetDNSFactory

public GetDNSFactory()

Method Detail

createAsyncWithCallback

public static IGetDNSContextAsyncWithCallback createAsyncWithCallback(int setFromOs,
                                                      java.util.HashMap<ContextOptionName,java.lang.Object> contextOptions)
                                                               throws GetDNSException

Creates a context for calling the API asynchronously using a callback mechanism.
That is, when an application calls one of these asynchronous functions and provides a callback, the API will invoke the callback with the response or exception when run() is invoked

Parameters:

setFromOs - Specify 1 to use values from the OS, such as those that would be found in res_query(3), /etc/resolv.conf, and so on.

contextOptions - Default options to initialize the context.

Returns:

Callback based Async context.

Throws:

GetDNSException

createAsyncWithFuture

public static IGetDNSContextAsyncWithFuture createAsyncWithFuture(int setFromOs,
                                                  java.util.HashMap<ContextOptionName,java.lang.Object> contextOptions)
                                                           throws GetDNSException

Creates a context for calling the API asynchronously using Future.
That is, when an application calls one of these asynchronous functions, the API returns a future object which will be populated with the response or exception when run() is invoked

Parameters:

setFromOs - Specify 1 to use values from the OS, such as those that would be found in res_query(3), /etc/resolv.conf, and so on.

contextOptions - Default options to initialize the context.

Returns:

Future based Async context.

Throws:

GetDNSException

createSync

public static IGetDNSContextSync createSync(int setFromOs,
                            java.util.HashMap<ContextOptionName,java.lang.Object> contextOptions)
                                     throws GetDNSException

Creates a context for calling the API synchronously.
That is, when an application calls one of these synchronous functions, the API gathers all the required information and then returns the result

Parameters:

setFromOs - Specify 1 to use values from the OS, such as those that would be found in res_query(3), /etc/resolv.conf, and so on.

contextOptions - Default options to initialize the context.

Returns:

Sync context.

Throws:

GetDNSException