org.minidns.dnsname

## Class DnsName

- java.lang.Object
- - org.minidns.dnsname.DnsName

- All Implemented Interfaces:
    Serializable, CharSequence, Comparable<DnsName>

      public final class DnsName
      extends Object
      implements CharSequence, Serializable, Comparable<DnsName>

  A DNS name, also called "domain name". A DNS name consists of multiple 'labels' and is subject to certain restrictions (see for example RFC 3696 § 2.).

  Instances of this class can be created by using `from(String)`.

  This class holds three representations of a DNS name: ACE, raw ACE and IDN. ACE (ASCII Compatible Encoding), which can be accessed via `ace`, represents mostly the data that got send over the wire. But since DNS names are case insensitive, the ACE value is normalized to lower case. You can use `getRawAce()` to get the raw ACE data that was received, which possibly includes upper case characters. The IDN (Internationalized Domain Name), that is the DNS name as it should be shown to the user, can be retrieved using `asIdn()`.

  More information about Internationalized Domain Names can be found at:
  - UTS #46 - Unicode IDNA Compatibility Processing
  - RFC 8753 - Internationalized Domain Names for Applications (IDNA) Review for New Unicode Versions
  See Also:
    RFC 3696, Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `String` | `ace` The DNS name in ASCII Compatible Encoding (ACE).
    `static DnsName` | `IN_ADDR_ARPA`
    `static DnsName` | `IP6_ARPA`
    `(package private) static int` | `MAX_DNSNAME_LENGTH_IN_OCTETS`
    `static int` | `MAX_LABELS`
    `static DnsName` | `ROOT`
    `static boolean` | `VALIDATE` Whether or not the DNS name is validated on construction.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `String` | `asIdn()`
    `char` | `charAt(int index)`
    `int` | `compareTo(DnsName other)`
    `boolean` | `equals(Object other)`
    `static DnsName` | `from(CharSequence name)`
    `static DnsName` | `from(DnsLabel grandchild, DnsLabel child, DnsName parent)`
    `static DnsName` | `from(DnsLabel child, DnsName parent)`
    `static DnsName` | `from(DnsName... nameComponents)`
    `static DnsName` | `from(DnsName child, DnsName parent)` Create a DNS name by "concatenating" the child under the parent name.
    `static DnsName` | `from(String name)`
    `static DnsName` | `from(String[] parts)`
    `byte[]` | `getBytes()` Serialize a domain name under IDN rules.
    `String` | `getDomainpart()` Domainpart in ACE representation.
    `String` | `getHostpart()` Hostpart in ACE representation.
    `DnsLabel` | `getHostpartLabel()`
    `DnsLabel` | `getLabel(int labelNum)`
    `int` | `getLabelCount()`
    `DnsLabel[]` | `getLabels()` Get a copy of the labels of this DNS name.
    `DnsName` | `getParent()` Return the parent of this DNS label.
    `String` | `getRawAce()`
    `byte[]` | `getRawBytes()`
    `DnsLabel[]` | `getRawLabels()` Get a copy of the raw labels of this DNS name.
    `int` | `hashCode()`
    `boolean` | `isChildOf(DnsName parent)`
    `boolean` | `isDirectChildOf(DnsName parent)`
    `boolean` | `isRootLabel()`
    `int` | `length()`
    `static DnsName` | `parse(DataInputStream dis, byte[] data)` Parse a domain name starting at the current offset and moving the input stream pointer past this domain name (even if cross references occure).
    `int` | `size()`
    `DnsName` | `stripToLabels(int labelCount)`
    `CharSequence` | `subSequence(int start, int end)`
    `String` | `toString()`
    `void` | `writeToStream(OutputStream os)`

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

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

    - ### Methods inherited from interface java.lang.CharSequence

      `chars, codePoints`

- - ### Field Detail

    - #### ace

          public final String ace

      The DNS name in ASCII Compatible Encoding (ACE).

    - #### IN_ADDR_ARPA

          public static final DnsName IN_ADDR_ARPA

    - #### IP6_ARPA

          public static final DnsName IP6_ARPA

    - #### MAX_DNSNAME_LENGTH_IN_OCTETS

          static final int MAX_DNSNAME_LENGTH_IN_OCTETS

      See Also:
        RFC 1035 § 2.3.4., Constant Field Values

    - #### MAX_LABELS

          public static final int MAX_LABELS

      See Also:
        Constant Field Values

    - #### ROOT

          public static final DnsName ROOT

    - #### VALIDATE

          public static final boolean VALIDATE

      Whether or not the DNS name is validated on construction.
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### asIdn

          public String asIdn()

    - #### charAt

          public char charAt(int index)

      Specified by:
        `charAt` in interface `CharSequence`

    - #### compareTo

          public int compareTo(DnsName other)

      Specified by:
        `compareTo` in interface `Comparable<DnsName>`

    - #### equals

          public boolean equals(Object other)

      Overrides:
        `equals` in class `Object`

    - #### from

          public static DnsName from(CharSequence name)

    - #### from

          public static DnsName from(DnsLabel grandchild,
                                     DnsLabel child,
                                     DnsName parent)

    - #### from

          public static DnsName from(DnsLabel child,
                                     DnsName parent)

    - #### from

          public static DnsName from(DnsName... nameComponents)

    - #### from

          public static DnsName from(DnsName child,
                                     DnsName parent)

      Create a DNS name by "concatenating" the child under the parent name. The child can also be seen as the "left" part of the resulting DNS name and the parent is the "right" part.

      For example using "i.am.the.child" as child and "of.this.parent.example" as parent, will result in a DNS name: "i.am.the.child.of.this.parent.example".

      Parameters:
        `child` - the child DNS name.
        `parent` - the parent DNS name.
      Returns:
        the resulting of DNS name.

    - #### from

          public static DnsName from(String name)

    - #### from

          public static DnsName from(String[] parts)

    - #### getBytes

          public byte[] getBytes()

      Serialize a domain name under IDN rules.
      Returns:
        The binary domain name representation.

    - #### getDomainpart

          public String getDomainpart()

      Domainpart in ACE representation.
      Returns:
        the domainpart in ACE representation.

    - #### getHostpart

          public String getHostpart()

      Hostpart in ACE representation.
      Returns:
        the hostpart in ACE representation.

    - #### getHostpartLabel

          public DnsLabel getHostpartLabel()

    - #### getLabel

          public DnsLabel getLabel(int labelNum)

    - #### getLabelCount

          public int getLabelCount()

    - #### getLabels

          public DnsLabel[] getLabels()

      Get a copy of the labels of this DNS name. The resulting array will contain the labels in reverse order, that is, the top-level domain will be at res[0].
      Returns:
        an array of the labels in reverse order.

    - #### getParent

          public DnsName getParent()

      Return the parent of this DNS label. Will return the root label if this label itself is the root label (because there is no parent of root).

      For example:

      - `"foo.bar.org".getParent() == "bar.org"`
      - `".".getParent() == "."`
      Returns:
        the parent of this DNS label.

    - #### getRawAce

          public String getRawAce()

    - #### getRawBytes

          public byte[] getRawBytes()

    - #### getRawLabels

          public DnsLabel[] getRawLabels()

      Get a copy of the raw labels of this DNS name. The resulting array will contain the labels in reverse order, that is, the top-level domain will be at res[0].
      Returns:
        an array of the raw labels in reverse order.

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `Object`

    - #### isChildOf

          public boolean isChildOf(DnsName parent)

    - #### isDirectChildOf

          public boolean isDirectChildOf(DnsName parent)

    - #### isRootLabel

          public boolean isRootLabel()

    - #### length

          public int length()

      Specified by:
        `length` in interface `CharSequence`

    - #### parse

          public static DnsName parse(DataInputStream dis,
                                      byte[] data)
                               throws IOException

      Parse a domain name starting at the current offset and moving the input stream pointer past this domain name (even if cross references occure).
      Parameters:
        `dis` - The input stream.
        `data` - The raw data (for cross references).
      Returns:
        The domain name string.
      Throws:
        `IOException` - Should never happen.

    - #### size

          public int size()

    - #### stripToLabels

          public DnsName stripToLabels(int labelCount)

    - #### subSequence

          public CharSequence subSequence(int start,
                                          int end)

      Specified by:
        `subSequence` in interface `CharSequence`

    - #### toString

          public String toString()

      Specified by:
        `toString` in interface `CharSequence`
      Overrides:
        `toString` in class `Object`

    - #### writeToStream

          public void writeToStream(OutputStream os)
                             throws IOException

      Throws:
        `IOException`