org.xbill.DNS

Class Lookup

java.lang.Object

org.xbill.DNS.Lookup

public final class Lookup
extends Object

The Lookup object issues queries to caching DNS servers. The input consists of a name, an optional type, and an optional class. Caching is enabled by default and used when possible to reduce the number of DNS requests. A Resolver, which defaults to an ExtendedResolver initialized with the resolvers located by the ResolverConfig class, performs the queries. A search path of domain suffixes is used to resolve relative names, and is also determined by the ResolverConfig class.

A Lookup object may be reused, but should not be used by multiple threads.

Author:

Brian Wellington

See Also:

Cache, Resolver, ResolverConfig

Field Summary

Fields

Modifier and Type	Field and Description
static int	HOST_NOT_FOUND The host does not exist.
static int	SUCCESSFUL The lookup was successful.
static int	TRY_AGAIN The lookup failed due to a network error.
static int	TYPE_NOT_FOUND The host exists, but has no records associated with the queried type.
static int	UNRECOVERABLE The lookup failed due to a data or server error.

Constructor Summary

Constructors

Constructor and Description
Lookup(Name name) Create a Lookup object that will find records of type A at the given name in the IN class.
Lookup(Name name, int type) Create a Lookup object that will find records of the given name and type in the IN class.
Lookup(Name name, int type, int dclass) Create a Lookup object that will find records of the given name, type, and class.
Lookup(String name) Create a Lookup object that will find records of type A at the given name in the IN class.
Lookup(String name, int type) Create a Lookup object that will find records of the given name and type in the IN class.
Lookup(String name, int type, int dclass) Create a Lookup object that will find records of the given name, type, and class.

Method Summary

Modifier and Type	Method and Description
Name[]	getAliases() Returns all known aliases for this name.
Record[]	getAnswers() Returns the answers from the lookup.
static Cache	getDefaultCache(int dclass) Gets the Cache that will be used as the default for the specified class by future Lookups.
static HostsFileParser	getDefaultHostsFileParser() Gets the default HostsFileParser to use for new Lookup instances.
static Resolver	getDefaultResolver() Gets the Resolver that will be used as the default by future Lookups.
static List<Name>	getDefaultSearchPath() Gets the search path that will be used as the default by future Lookups.
String	getErrorString() Returns an error string describing the result code of this lookup.
HostsFileParser	getHostsFileParser() Gets or sets the local hosts database parser to use for lookup before using a Resolver.
int	getResult() Returns the result code of the lookup.
static void	refreshDefault()
Record[]	run() Performs the lookup, using the specified Cache, Resolver, and search path.
void	setCache(Cache cache) Sets the cache to use when performing this lookup.
void	setCredibility(int credibility) Sets the minimum credibility level that will be accepted when performing the lookup.
void	setCycleResults(boolean cycleResults) Controls the behavior if results being returned from the cache should be cycled in a round-robin style (true) or if the raw lookup results should be returned (false).
static void	setDefaultCache(Cache cache, int dclass) Sets the Cache to be used as the default for the specified class by future Lookups.
static void	setDefaultHostsFileParser(HostsFileParser hostsFileParser) Sets the default HostsFileParser to use for new Lookup instances.
static void	setDefaultNdots(int ndots) Sets the default ndots to use when performing a lookup, overriding the default value.
static void	setDefaultResolver(Resolver resolver) Sets the default Resolver to be used as the default by future Lookups.
static void	setDefaultSearchPath(List<Name> domains) Sets the search path to be used as the default by future Lookups.
static void	setDefaultSearchPath(Name... domains) Sets the search path to be used as the default by future Lookups.
static void	setDefaultSearchPath(String... domains) Sets the search path that will be used as the default by future Lookups.
void	setHostsFileParser(HostsFileParser hostsFileParser) Gets or sets the local hosts database parser to use for lookup before using a Resolver.
void	setNdots(int ndots) Sets ndots to use when performing this lookup, overriding the default value.
static void	setPacketLogger(PacketLogger logger) Sets a custom logger that will be used to log the sent and received packets.
void	setResolver(Resolver resolver) Sets the resolver to use when performing this lookup.
void	setSearchPath(List<Name> domains) Sets the search path to use when performing this lookup.
void	setSearchPath(Name... domains) Sets the search path to use when performing this lookup.
void	setSearchPath(String... domains) Sets the search path to use when performing this lookup.

Methods inherited from class java.lang.Object

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

Field Detail

SUCCESSFUL

public static final int SUCCESSFUL

The lookup was successful.

See Also:

Constant Field Values

UNRECOVERABLE

public static final int UNRECOVERABLE

The lookup failed due to a data or server error. Repeating the lookup would not be helpful.

See Also:

Constant Field Values

TRY_AGAIN

public static final int TRY_AGAIN

The lookup failed due to a network error. Repeating the lookup may be helpful.

See Also:

Constant Field Values

HOST_NOT_FOUND

public static final int HOST_NOT_FOUND

The host does not exist.

See Also:

Constant Field Values

TYPE_NOT_FOUND

public static final int TYPE_NOT_FOUND

The host exists, but has no records associated with the queried type.

See Also:

Constant Field Values

Constructor Detail

Lookup

public Lookup(Name name,
              int type,
              int dclass)

Create a Lookup object that will find records of the given name, type, and class. The lookup will use the default cache, resolver, and search path, and look for records that are reasonably credible.

Parameters:

name - The name of the desired records

type - The type of the desired records

dclass - The class of the desired records

Throws:

IllegalArgumentException - The type is a meta type other than ANY.

See Also:

Cache, Resolver, Credibility, Name, Type, DClass

Lookup

public Lookup(Name name,
              int type)

Create a Lookup object that will find records of the given name and type in the IN class.

Parameters:

name - The name of the desired records

type - The type of the desired records

Throws:

IllegalArgumentException - The type is a meta type other than ANY.

See Also:

Lookup(Name,int,int)

Lookup

public Lookup(Name name)

Create a Lookup object that will find records of type A at the given name in the IN class.

Parameters:

name - The name of the desired records

See Also:

Lookup(Name,int,int)

Lookup

public Lookup(String name,
              int type,
              int dclass)
       throws TextParseException

Create a Lookup object that will find records of the given name, type, and class.

Parameters:

name - The name of the desired records

type - The type of the desired records

dclass - The class of the desired records

Throws:

TextParseException - The name is not a valid DNS name

IllegalArgumentException - The type is a meta type other than ANY.

See Also:

Lookup(Name,int,int)

Lookup

public Lookup(String name,
              int type)
       throws TextParseException

Create a Lookup object that will find records of the given name and type in the IN class.

Parameters:

name - The name of the desired records

type - The type of the desired records

Throws:

TextParseException - The name is not a valid DNS name

IllegalArgumentException - The type is a meta type other than ANY.

See Also:

Lookup(Name,int,int)

Lookup

public Lookup(String name)
       throws TextParseException

Create a Lookup object that will find records of type A at the given name in the IN class.

Parameters:

name - The name of the desired records

Throws:

TextParseException - The name is not a valid DNS name

See Also:

Lookup(Name,int,int)

Method Detail

refreshDefault

public static void refreshDefault()

getDefaultResolver

public static Resolver getDefaultResolver()

Gets the Resolver that will be used as the default by future Lookups.

Returns:

The default resolver.

setDefaultResolver

public static void setDefaultResolver(Resolver resolver)

Sets the default Resolver to be used as the default by future Lookups.

Parameters:

resolver - The default resolver.

getDefaultCache

public static Cache getDefaultCache(int dclass)

Gets the Cache that will be used as the default for the specified class by future Lookups.

Parameters:

dclass - The class whose cache is being retrieved.

Returns:

The default cache for the specified class.

setDefaultCache

public static void setDefaultCache(Cache cache,
                                   int dclass)

Sets the Cache to be used as the default for the specified class by future Lookups.

Parameters:

cache - The default cache for the specified class.

dclass - The class whose cache is being set.

getDefaultSearchPath

public static List<Name> getDefaultSearchPath()

Gets the search path that will be used as the default by future Lookups.

Returns:

The default search path.

setDefaultSearchPath

public static void setDefaultSearchPath(List<Name> domains)

Sets the search path to be used as the default by future Lookups.

Parameters:

domains - The default search path.

Throws:

IllegalArgumentException - if a domain in the search path is not absolute and cannot be made absolute.

setDefaultSearchPath

public static void setDefaultSearchPath(Name... domains)

Sets the search path to be used as the default by future Lookups.

Parameters:

domains - The default search path.

Throws:

IllegalArgumentException - if a domain in the search path is not absolute and cannot be made absolute.

setDefaultSearchPath

public static void setDefaultSearchPath(String... domains)
                                 throws TextParseException

Sets the search path that will be used as the default by future Lookups.

Parameters:

domains - The default search path.

Throws:

TextParseException - A name in the array is not a valid DNS name.

getDefaultHostsFileParser

public static HostsFileParser getDefaultHostsFileParser()

Gets the default HostsFileParser to use for new Lookup instances.

Since:

3.4

setDefaultHostsFileParser

public static void setDefaultHostsFileParser(HostsFileParser hostsFileParser)

Sets the default HostsFileParser to use for new Lookup instances.

Since:

3.4

setPacketLogger

public static void setPacketLogger(PacketLogger logger)

Sets a custom logger that will be used to log the sent and received packets.

Parameters:

logger - The logger

setResolver

public void setResolver(Resolver resolver)

Sets the resolver to use when performing this lookup. This overrides the default value.

Parameters:

resolver - The resolver to use.

setSearchPath

public void setSearchPath(List<Name> domains)

Sets the search path to use when performing this lookup. This overrides the default value.

Parameters:

domains - An array of names containing the search path.

Throws:

IllegalArgumentException - if a domain in the search path is not absolute and cannot be made absolute.

setSearchPath

public void setSearchPath(Name... domains)

Sets the search path to use when performing this lookup. This overrides the default value.

Parameters:

domains - An array of names containing the search path.

Throws:

IllegalArgumentException - if a domain in the search path is not absolute and cannot be made absolute.

setSearchPath

public void setSearchPath(String... domains)
                   throws TextParseException

Sets the search path to use when performing this lookup. This overrides the default value.

Parameters:

domains - An array of names containing the search path.

Throws:

TextParseException - A name in the array is not a valid DNS name.

setCache

public void setCache(Cache cache)

Sets the cache to use when performing this lookup. This overrides the default value. If the results of this lookup should not be permanently cached, null can be provided here.

Parameters:

cache - The cache to use.

setDefaultNdots

public static void setDefaultNdots(int ndots)

Sets the default ndots to use when performing a lookup, overriding the default value. Specifically, this refers to the number of "dots" which, if present in a name, indicate that a lookup for the absolute name should be attempted before appending any search path elements.

Parameters:

ndots - The ndots value to use, which must be greater than or equal to 0.

setNdots

public void setNdots(int ndots)

Sets ndots to use when performing this lookup, overriding the default value. Specifically, this refers to the number of "dots" which, if present in a name, indicate that a lookup for the absolute name should be attempted before appending any search path elements.

Parameters:

ndots - The ndots value to use, which must be greater than or equal to 0.

setCredibility

public void setCredibility(int credibility)

Sets the minimum credibility level that will be accepted when performing the lookup. This defaults to Credibility.NORMAL.

Parameters:

credibility - The minimum credibility level.

setCycleResults

public void setCycleResults(boolean cycleResults)

Controls the behavior if results being returned from the cache should be cycled in a round-robin style (true) or if the raw lookup results should be returned (false).

Parameters:

cycleResults - The desired behavior of the order of the results

run

public Record[] run()

Performs the lookup, using the specified Cache, Resolver, and search path.

Returns:

The answers, or null if none are found.

getAnswers

public Record[] getAnswers()

Returns the answers from the lookup.

Returns:

The answers, or null if none are found.

Throws:

IllegalStateException - The lookup has not completed.

getAliases

public Name[] getAliases()

Returns all known aliases for this name. Whenever a CNAME/DNAME is followed, an alias is added to this array. The last element in this array will be the owner name for records in the answer, if there are any.

Returns:

The aliases.

Throws:

IllegalStateException - The lookup has not completed.

getResult

public int getResult()

Returns the result code of the lookup.

Returns:

The result code, which can be SUCCESSFUL, UNRECOVERABLE, TRY_AGAIN, HOST_NOT_FOUND, or TYPE_NOT_FOUND.

Throws:

IllegalStateException - The lookup has not completed.

getErrorString

public String getErrorString()

Returns an error string describing the result code of this lookup.

Returns:

A string, which may either directly correspond the result code or be more specific.

Throws:

IllegalStateException - The lookup has not completed.

getHostsFileParser

public HostsFileParser getHostsFileParser()

Gets or sets the local hosts database parser to use for lookup before using a Resolver.

Since:

3.4

setHostsFileParser

public void setHostsFileParser(HostsFileParser hostsFileParser)

Gets or sets the local hosts database parser to use for lookup before using a Resolver.

Since:

3.4