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

org.xbill.DNS

## Class Name

- java.lang.Object
- - org.xbill.DNS.Name

- All Implemented Interfaces:
    Serializable, Comparable

      public class Name
      extends Object
      implements Comparable, Serializable

  A representation of a domain name. It may either be absolute (fully qualified) or relative.
  Author:
    Brian Wellington
  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static Name` | `empty` The root name
    `static Name` | `root` The root name

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Name(byte[] b)` Create a new name from DNS wire format
    `Name(DNSInput in)` Create a new name from DNS a wire format message
    `Name(Name src, int n)` Create a new name by removing labels from the beginning of an existing Name
    `Name(String s)` Create a new name from a string.
    `Name(String s, Name origin)` Create a new name from a string and an origin.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `Name` | `canonicalize()` Returns a canonicalized version of the Name (all lowercase).
    `int` | `compareTo(Object o)` Compares this Name to another Object.
    `static Name` | `concatenate(Name prefix, Name suffix)` Creates a new name by concatenating two existing names.
    `boolean` | `equals(Object arg)` Are these two Names equivalent?
    `static Name` | `fromConstantString(String s)` Create a new name from a constant string.
    `Name` | `fromDNAME(DNAMERecord dname)` Generates a new Name to be used when following a DNAME.
    `static Name` | `fromString(String s)` Create a new name from a string.
    `static Name` | `fromString(String s, Name origin)` Create a new name from a string and an origin.
    `byte[]` | `getLabel(int n)` Retrieve the nth label of a Name.
    `String` | `getLabelString(int n)` Convert the nth label in a Name to a String
    `int` | `hashCode()` Computes a hashcode based on the value
    `boolean` | `isAbsolute()` Is this name absolute?
    `boolean` | `isWild()` Is this name a wildcard?
    `int` | `labels()` The number of labels in the name.
    `short` | `length()` The length of the name.
    `Name` | `relativize(Name origin)` If this name is a subdomain of origin, return a new name relative to origin with the same value.
    `boolean` | `subdomain(Name domain)` Is the current Name a subdomain of the specified name?
    `String` | `toString()` Convert a Name to a String
    `String` | `toString(boolean omitFinalDot)` Convert a Name to a String
    `byte[]` | `toWire()` Emit a Name in DNS wire format
    `void` | `toWire(DNSOutput out, Compression c)` Emit a Name in DNS wire format
    `void` | `toWire(DNSOutput out, Compression c, boolean canonical)` Emit a Name in DNS wire format
    `byte[]` | `toWireCanonical()` Emit a Name in canonical DNS wire format (all lowercase)
    `void` | `toWireCanonical(DNSOutput out)` Emit a Name in canonical DNS wire format (all lowercase)
    `Name` | `wild(int n)` Generates a new Name with the first n labels replaced by a wildcard

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### root

          public static final Name root

      The root name

    - #### empty

          public static final Name empty

      The root name

  - ### Constructor Detail

    - #### Name

          public Name(String s,
              Name origin)
               throws TextParseException

      Create a new name from a string and an origin. This does not automatically make the name absolute; it will be absolute if it has a trailing dot or an absolute origin is appended.
      Parameters:
        `s` - The string to be converted
        `origin` - If the name is not absolute, the origin to be appended.
      Throws:
        `TextParseException` - The name is invalid.

    - #### Name

          public Name(String s)
               throws TextParseException

      Create a new name from a string. This does not automatically make the name absolute; it will be absolute if it has a trailing dot.
      Parameters:
        `s` - The string to be converted
      Throws:
        `TextParseException` - The name is invalid.

    - #### Name

          public Name(DNSInput in)
               throws WireParseException

      Create a new name from DNS a wire format message
      Parameters:
        `in` - A stream containing the DNS message which is currently positioned at the start of the name to be read.
      Throws:
        `WireParseException`

    - #### Name

          public Name(byte[] b)
               throws IOException

      Create a new name from DNS wire format
      Parameters:
        `b` - A byte array containing the wire format of the name.
      Throws:
        `IOException`

    - #### Name

          public Name(Name src,
              int n)

      Create a new name by removing labels from the beginning of an existing Name
      Parameters:
        `src` - An existing Name
        `n` - The number of labels to remove from the beginning in the copy

  - ### Method Detail

    - #### fromString

          public static Name fromString(String s,
                        Name origin)
                                 throws TextParseException

      Create a new name from a string and an origin. This does not automatically make the name absolute; it will be absolute if it has a trailing dot or an absolute origin is appended. This is identical to the constructor, except that it will avoid creating new objects in some cases.
      Parameters:
        `s` - The string to be converted
        `origin` - If the name is not absolute, the origin to be appended.
      Throws:
        `TextParseException` - The name is invalid.

    - #### fromString

          public static Name fromString(String s)
                                 throws TextParseException

      Create a new name from a string. This does not automatically make the name absolute; it will be absolute if it has a trailing dot. This is identical to the constructor, except that it will avoid creating new objects in some cases.
      Parameters:
        `s` - The string to be converted
      Throws:
        `TextParseException` - The name is invalid.

    - #### fromConstantString

          public static Name fromConstantString(String s)

      Create a new name from a constant string. This should only be used when the name is known to be good - that is, when it is constant.
      Parameters:
        `s` - The string to be converted
      Throws:
        `IllegalArgumentException` - The name is invalid.

    - #### concatenate

          public static Name concatenate(Name prefix,
                         Name suffix)
                                  throws NameTooLongException

      Creates a new name by concatenating two existing names.
      Parameters:
        `prefix` - The prefix name.
        `suffix` - The suffix name.
      Returns:
        The concatenated name.
      Throws:
        `NameTooLongException` - The name is too long.

    - #### relativize

          public Name relativize(Name origin)

      If this name is a subdomain of origin, return a new name relative to origin with the same value. Otherwise, return the existing name.
      Parameters:
        `origin` - The origin to remove.
      Returns:
        The possibly relativized name.

    - #### wild

          public Name wild(int n)

      Generates a new Name with the first n labels replaced by a wildcard
      Returns:
        The wildcard name

    - #### canonicalize

          public Name canonicalize()

      Returns a canonicalized version of the Name (all lowercase). This may be the same name, if the input Name is already canonical.

    - #### fromDNAME

          public Name fromDNAME(DNAMERecord dname)
                         throws NameTooLongException

      Generates a new Name to be used when following a DNAME.
      Parameters:
        `dname` - The DNAME record to follow.
      Returns:
        The constructed name.
      Throws:
        `NameTooLongException` - The resulting name is too long.

    - #### isWild

          public boolean isWild()

      Is this name a wildcard?

    - #### isAbsolute

          public boolean isAbsolute()

      Is this name absolute?

    - #### length

          public short length()

      The length of the name.

    - #### labels

          public int labels()

      The number of labels in the name.

    - #### subdomain

          public boolean subdomain(Name domain)

      Is the current Name a subdomain of the specified name?

    - #### toString

          public String toString(boolean omitFinalDot)

      Convert a Name to a String
      Parameters:
        `omitFinalDot` - If true, and the name is absolute, omit the final dot.
      Returns:
        The representation of this name as a (printable) String.

    - #### toString

          public String toString()

      Convert a Name to a String
      Overrides:
        `toString` in class `Object`
      Returns:
        The representation of this name as a (printable) String.

    - #### getLabel

          public byte[] getLabel(int n)

      Retrieve the nth label of a Name. This makes a copy of the label; changing this does not change the Name.
      Parameters:
        `n` - The label to be retrieved. The first label is 0.

    - #### getLabelString

          public String getLabelString(int n)

      Convert the nth label in a Name to a String
      Parameters:
        `n` - The label to be converted to a (printable) String. The first label is 0.

    - #### toWire

          public void toWire(DNSOutput out,
                    Compression c)

      Emit a Name in DNS wire format
      Parameters:
        `out` - The output stream containing the DNS message.
        `c` - The compression context, or null of no compression is desired.
      Throws:
        `IllegalArgumentException` - The name is not absolute.

    - #### toWire

          public byte[] toWire()

      Emit a Name in DNS wire format
      Throws:
        `IllegalArgumentException` - The name is not absolute.

    - #### toWireCanonical

          public void toWireCanonical(DNSOutput out)

      Emit a Name in canonical DNS wire format (all lowercase)
      Parameters:
        `out` - The output stream to which the message is written.

    - #### toWireCanonical

          public byte[] toWireCanonical()

      Emit a Name in canonical DNS wire format (all lowercase)
      Returns:
        The canonical form of the name.

    - #### toWire

          public void toWire(DNSOutput out,
                    Compression c,
                    boolean canonical)

      Emit a Name in DNS wire format
      Parameters:
        `out` - The output stream containing the DNS message.
        `c` - The compression context, or null of no compression is desired.
        `canonical` - If true, emit the name in canonicalized form (all lowercase).
      Throws:
        `IllegalArgumentException` - The name is not absolute.

    - #### equals

          public boolean equals(Object arg)

      Are these two Names equivalent?
      Overrides:
        `equals` in class `Object`

    - #### hashCode

          public int hashCode()

      Computes a hashcode based on the value
      Overrides:
        `hashCode` in class `Object`

    - #### compareTo

          public int compareTo(Object o)

      Compares this Name to another Object.
      Specified by:
        `compareTo` in interface `Comparable`
      Parameters:
        `o` - The Object to be compared.
      Returns:
        The value 0 if the argument is a name equivalent to this name; a value less than 0 if the argument is less than this name in the canonical ordering, and a value greater than 0 if the argument is greater than this name in the canonical ordering.
      Throws:
        `ClassCastException` - if the argument is not a Name.