Package org.xbill.DNS

Class Lookup

java.lang.Object
org.xbill.DNS.Lookup
public final class Lookup extends Object
The Lookup object issues queries to the local hosts database (/etc/hosts) and to recursive 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.

Lookup is considered legacy (but not yet deprecated). Use LookupSession instead, which is thread safe and fully async.

Author:
Brian Wellington
See Also:

  • Field Summary

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

  • Constructor Summary

    Constructors
    Constructor
    Description
    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.
    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.

  • Method Summary

    Modifier and Type
    Method
    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(String... domains)
    Sets the search path that will 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.
    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(String... domains)
    Sets the search path 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.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • SUCCESSFUL

      public static final int SUCCESSFUL
      The lookup was successful.
      See Also:

    • 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:

    • TRY_AGAIN

      public static final int TRY_AGAIN
      The lookup failed due to a network error. Repeating the lookup may be helpful.
      See Also:

    • HOST_NOT_FOUND

      public static final int HOST_NOT_FOUND
      The host does not exist.
      See Also:

    • TYPE_NOT_FOUND

      public static final int TYPE_NOT_FOUND
      The host exists, but has no records associated with the queried type.
      See Also:

  • Constructor Details

    • 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:

    • 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

      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

      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

      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

      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:

  • Method Details

    • 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. This is only applicable to the default I/O implementations.
      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.
      Throws:
      IllegalArgumentException - If the DClass of the cache doesn't match this Lookup's DClass.

    • 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