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

org.xbill.DNS

## Class Message

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

- All Implemented Interfaces:
    Cloneable
  Direct Known Subclasses:
    Update

      public class Message
      extends Object
      implements Cloneable

  A DNS Message. A message is the basic unit of communication between the client and server of a DNS operation. A message consists of a Header and 4 message sections.
  Author:
    Brian Wellington
  See Also:
    `Resolver`, `Header`, `Section`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `MAXLENGTH` The maximum length of a message in wire format.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Message()` Creates a new Message with a random Message ID
    `Message(byte[] b)` Creates a new Message from its DNS wire format representation
    `Message(int id)` Creates a new Message with the specified Message ID

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addRecord(Record r, int section)` Adds a record to a section of the Message, and adjusts the header.
    `Object` | `clone()` Creates a copy of this Message.
    `boolean` | `findRecord(Record r)` Determines if the given record is already present in any section.
    `boolean` | `findRecord(Record r, int section)` Determines if the given record is already present in the given section.
    `boolean` | `findRRset(Name name, int type)` Determines if an RRset with the given name and type is already present in any section.
    `boolean` | `findRRset(Name name, int type, int section)` Determines if an RRset with the given name and type is already present in the given section.
    `Header` | `getHeader()` Retrieves the Header.
    `OPTRecord` | `getOPT()` Returns the OPT record from the ADDITIONAL section, if one is present.
    `Record` | `getQuestion()` Returns the first record in the QUESTION section.
    `int` | `getRcode()` Returns the message's rcode (error code).
    `Record[]` | `getSectionArray(int section)` Returns an array containing all records in the given section, or an empty array if the section is empty.
    `RRset[]` | `getSectionRRsets(int section)` Returns an array containing all records in the given section grouped into RRsets.
    `TSIGRecord` | `getTSIG()` Returns the TSIG record from the ADDITIONAL section, if one is present.
    `boolean` | `isSigned()` Was this message signed by a TSIG?
    `boolean` | `isVerified()` If this message was signed by a TSIG, was the TSIG verified?
    `static Message` | `newQuery(Record r)` Creates a new Message with a random Message ID suitable for sending as a query.
    `static Message` | `newUpdate(Name zone)` Creates a new Message to contain a dynamic update.
    `int` | `numBytes()` Returns the size of the message.
    `void` | `removeAllRecords(int section)` Removes all records from a section of the Message, and adjusts the header.
    `boolean` | `removeRecord(Record r, int section)` Removes a record from a section of the Message, and adjusts the header.
    `String` | `sectionToString(int i)` Converts the given section of the Message to a String.
    `void` | `setHeader(Header h)` Replaces the Header with a new one.
    `void` | `setTSIG(TSIG key, int error, TSIGRecord querytsig)` Sets the TSIG key and other necessary information to sign a message.
    `String` | `toString()` Converts the Message to a String.
    `byte[]` | `toWire()` Returns an array containing the wire format representation of the Message.
    `byte[]` | `toWire(int maxLength)` Returns an array containing the wire format representation of the Message with the specified maximum length.

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

      `equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### MAXLENGTH

          public static final int MAXLENGTH

      The maximum length of a message in wire format.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### Message

          public Message(int id)

      Creates a new Message with the specified Message ID

    - #### Message

          public Message()

      Creates a new Message with a random Message ID

    - #### Message

          public Message(byte[] b)
                  throws IOException

      Creates a new Message from its DNS wire format representation
      Parameters:
        `b` - A byte array containing the DNS Message.
      Throws:
        `IOException`

  - ### Method Detail

    - #### newQuery

          public static Message newQuery(Record r)

      Creates a new Message with a random Message ID suitable for sending as a query.
      Parameters:
        `r` - A record containing the question

    - #### newUpdate

          public static Message newUpdate(Name zone)

      Creates a new Message to contain a dynamic update. A random Message ID and the zone are filled in.
      Parameters:
        `zone` - The zone to be updated

    - #### setHeader

          public void setHeader(Header h)

      Replaces the Header with a new one.
      See Also:
        `Header`

    - #### getHeader

          public Header getHeader()

      Retrieves the Header.
      See Also:
        `Header`

    - #### addRecord

          public void addRecord(Record r,
                       int section)

      Adds a record to a section of the Message, and adjusts the header.
      See Also:
        `Record`, `Section`

    - #### removeRecord

          public boolean removeRecord(Record r,
                             int section)

      Removes a record from a section of the Message, and adjusts the header.
      See Also:
        `Record`, `Section`

    - #### removeAllRecords

          public void removeAllRecords(int section)

      Removes all records from a section of the Message, and adjusts the header.
      See Also:
        `Record`, `Section`

    - #### findRecord

          public boolean findRecord(Record r,
                           int section)

      Determines if the given record is already present in the given section.
      See Also:
        `Record`, `Section`

    - #### findRecord

          public boolean findRecord(Record r)

      Determines if the given record is already present in any section.
      See Also:
        `Record`, `Section`

    - #### findRRset

          public boolean findRRset(Name name,
                          int type,
                          int section)

      Determines if an RRset with the given name and type is already present in the given section.
      See Also:
        `RRset`, `Section`

    - #### findRRset

          public boolean findRRset(Name name,
                          int type)

      Determines if an RRset with the given name and type is already present in any section.
      See Also:
        `RRset`, `Section`

    - #### getQuestion

          public Record getQuestion()

      Returns the first record in the QUESTION section.
      See Also:
        `Record`, `Section`

    - #### getTSIG

          public TSIGRecord getTSIG()

      Returns the TSIG record from the ADDITIONAL section, if one is present.
      See Also:
        `TSIGRecord`, `TSIG`, `Section`

    - #### isSigned

          public boolean isSigned()

      Was this message signed by a TSIG?
      See Also:
        `TSIG`

    - #### isVerified

          public boolean isVerified()

      If this message was signed by a TSIG, was the TSIG verified?
      See Also:
        `TSIG`

    - #### getOPT

          public OPTRecord getOPT()

      Returns the OPT record from the ADDITIONAL section, if one is present.
      See Also:
        `OPTRecord`, `Section`

    - #### getRcode

          public int getRcode()

      Returns the message's rcode (error code). This incorporates the EDNS extended rcode.

    - #### getSectionArray

          public Record[] getSectionArray(int section)

      Returns an array containing all records in the given section, or an empty array if the section is empty.
      See Also:
        `Record`, `Section`

    - #### getSectionRRsets

          public RRset[] getSectionRRsets(int section)

      Returns an array containing all records in the given section grouped into RRsets.
      See Also:
        `RRset`, `Section`

    - #### toWire

          public byte[] toWire()

      Returns an array containing the wire format representation of the Message.

    - #### toWire

          public byte[] toWire(int maxLength)

      Returns an array containing the wire format representation of the Message with the specified maximum length. This will generate a truncated message (with the TC bit) if the message doesn't fit, and will also sign the message with the TSIG key set by a call to setTSIG(). This method may return null if the message could not be rendered at all; this could happen if maxLength is smaller than a DNS header, for example.
      Parameters:
        `maxLength` - The maximum length of the message.
      Returns:
        The wire format of the message, or null if the message could not be rendered into the specified length.
      See Also:
        `Flags`, `TSIG`

    - #### setTSIG

          public void setTSIG(TSIG key,
                     int error,
                     TSIGRecord querytsig)

      Sets the TSIG key and other necessary information to sign a message.
      Parameters:
        `key` - The TSIG key.
        `error` - The value of the TSIG error field.
        `querytsig` - If this is a response, the TSIG from the request.

    - #### numBytes

          public int numBytes()

      Returns the size of the message. Only valid if the message has been converted to or from wire format.

    - #### sectionToString

          public String sectionToString(int i)

      Converts the given section of the Message to a String.
      See Also:
        `Section`

    - #### toString

          public String toString()

      Converts the Message to a String.
      Overrides:
        `toString` in class `Object`

    - #### clone

          public Object clone()

      Creates a copy of this Message. This is done by the Resolver before adding TSIG and OPT records, for example.
      Overrides:
        `clone` in class `Object`
      See Also:
        `Resolver`, `TSIGRecord`, `OPTRecord`