Lookup (dnsjava documentation)
Date: 2013-04-10

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

    Methods
    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 Resolver` | `getDefaultResolver()` Gets the Resolver that will be used as the default by future Lookups.
    `static 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.
    `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.
    `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` | `setDefaultResolver(Resolver resolver)` Sets the default Resolver 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` | `setNdots(int ndots)` Sets ndots to use when performing this lookup, overriding the default value.
    `void` | `setResolver(Resolver resolver)` Sets the resolver 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 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(Name[] domains)

      Sets the search path to be used as the default by future Lookups.
      Parameters:
        `domains` - The default search path.

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

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

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

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

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