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

org.xbill.DNS

## Class Tokenizer

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

-     public class Tokenizer
      extends Object

  Tokenizer is used to parse DNS records and zones from text format,
  Author:
    Brian Wellington, Bob Halley

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `Tokenizer.Token`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `COMMENT` A comment; only returned when wantComment is set
    `static int` | `EOF` End of file
    `static int` | `EOL` End of line
    `static int` | `IDENTIFIER` An identifier (unquoted string)
    `static int` | `QUOTED_STRING` A quoted string
    `static int` | `WHITESPACE` Whitespace; only returned when wantWhitespace is set

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Tokenizer(File f)` Creates a Tokenizer from a file.
    `Tokenizer(InputStream is)` Creates a Tokenizer from an arbitrary input stream.
    `Tokenizer(String s)` Creates a Tokenizer from a string.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()` Closes any files opened by this tokenizer.
    `TextParseException` | `exception(String s)` Creates an exception which includes the current state in the error message
    `protected void` | `finalize()`
    `Tokenizer.Token` | `get()` Gets the next token from a tokenizer, ignoring whitespace and comments.
    `Tokenizer.Token` | `get(boolean wantWhitespace, boolean wantComment)` Gets the next token from a tokenizer.
    `InetAddress` | `getAddress(int family)` Gets the next token from a tokenizer and converts it to an IP Address.
    `byte[]` | `getBase32String(base32 b32)` Gets the next token from a tokenizer and decodes it as base32.
    `byte[]` | `getBase64()` Gets the remaining string tokens until an EOL/EOF is seen, concatenates them together, and converts the base64 encoded data to a byte array.
    `byte[]` | `getBase64(boolean required)` Gets the remaining string tokens until an EOL/EOF is seen, concatenates them together, and converts the base64 encoded data to a byte array.
    `void` | `getEOL()` Gets the next token from a tokenizer, which must be an EOL or EOF.
    `byte[]` | `getHex()` Gets the remaining string tokens until an EOL/EOF is seen, concatenates them together, and converts the hex encoded data to a byte array.
    `byte[]` | `getHex(boolean required)` Gets the remaining string tokens until an EOL/EOF is seen, concatenates them together, and converts the hex encoded data to a byte array.
    `byte[]` | `getHexString()` Gets the next token from a tokenizer and decodes it as hex.
    `String` | `getIdentifier()` Gets the next token from a tokenizer, ensures it is an unquoted string, and converts it to a string.
    `long` | `getLong()` Gets the next token from a tokenizer and converts it to a long.
    `Name` | `getName(Name origin)` Gets the next token from a tokenizer and converts it to a name.
    `String` | `getString()` Gets the next token from a tokenizer and converts it to a string.
    `long` | `getTTL()` Gets the next token from a tokenizer and parses it as a TTL.
    `long` | `getTTLLike()` Gets the next token from a tokenizer and parses it as if it were a TTL.
    `int` | `getUInt16()` Gets the next token from a tokenizer and converts it to an unsigned 16 bit integer.
    `long` | `getUInt32()` Gets the next token from a tokenizer and converts it to an unsigned 32 bit integer.
    `int` | `getUInt8()` Gets the next token from a tokenizer and converts it to an unsigned 8 bit integer.
    `void` | `unget()` Returns a token to the stream, so that it will be returned by the next call to get().

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

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

- - ### Field Detail

    - #### EOF

          public static final int EOF

      End of file
      See Also:
        Constant Field Values

    - #### EOL

          public static final int EOL

      End of line
      See Also:
        Constant Field Values

    - #### WHITESPACE

          public static final int WHITESPACE

      Whitespace; only returned when wantWhitespace is set
      See Also:
        Constant Field Values

    - #### IDENTIFIER

          public static final int IDENTIFIER

      An identifier (unquoted string)
      See Also:
        Constant Field Values

    - #### QUOTED_STRING

          public static final int QUOTED_STRING

      A quoted string
      See Also:
        Constant Field Values

    - #### COMMENT

          public static final int COMMENT

      A comment; only returned when wantComment is set
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### Tokenizer

          public Tokenizer(InputStream is)

      Creates a Tokenizer from an arbitrary input stream.
      Parameters:
        `is` - The InputStream to tokenize.

    - #### Tokenizer

          public Tokenizer(String s)

      Creates a Tokenizer from a string.
      Parameters:
        `s` - The String to tokenize.

    - #### Tokenizer

          public Tokenizer(File f)
                    throws FileNotFoundException

      Creates a Tokenizer from a file.
      Parameters:
        `f` - The File to tokenize.
      Throws:
        `FileNotFoundException`

  - ### Method Detail

    - #### get

          public Tokenizer.Token get(boolean wantWhitespace,
                            boolean wantComment)
                              throws IOException

      Gets the next token from a tokenizer.
      Parameters:
        `wantWhitespace` - If true, leading whitespace will be returned as a token.
        `wantComment` - If true, comments are returned as tokens.
      Returns:
        The next token in the stream.
      Throws:
        `TextParseException` - The input was invalid.
        `IOException` - An I/O error occurred.

    - #### get

          public Tokenizer.Token get()
                              throws IOException

      Gets the next token from a tokenizer, ignoring whitespace and comments.
      Returns:
        The next token in the stream.
      Throws:
        `TextParseException` - The input was invalid.
        `IOException` - An I/O error occurred.

    - #### unget

          public void unget()

      Returns a token to the stream, so that it will be returned by the next call to get().
      Throws:
        `IllegalStateException` - There are already ungotten tokens.

    - #### getString

          public String getString()
                           throws IOException

      Gets the next token from a tokenizer and converts it to a string.
      Returns:
        The next token in the stream, as a string.
      Throws:
        `TextParseException` - The input was invalid or not a string.
        `IOException` - An I/O error occurred.

    - #### getIdentifier

          public String getIdentifier()
                               throws IOException

      Gets the next token from a tokenizer, ensures it is an unquoted string, and converts it to a string.
      Returns:
        The next token in the stream, as a string.
      Throws:
        `TextParseException` - The input was invalid or not an unquoted string.
        `IOException` - An I/O error occurred.

    - #### getLong

          public long getLong()
                       throws IOException

      Gets the next token from a tokenizer and converts it to a long.
      Returns:
        The next token in the stream, as a long.
      Throws:
        `TextParseException` - The input was invalid or not a long.
        `IOException` - An I/O error occurred.

    - #### getUInt32

          public long getUInt32()
                         throws IOException

      Gets the next token from a tokenizer and converts it to an unsigned 32 bit integer.
      Returns:
        The next token in the stream, as an unsigned 32 bit integer.
      Throws:
        `TextParseException` - The input was invalid or not an unsigned 32 bit integer.
        `IOException` - An I/O error occurred.

    - #### getUInt16

          public int getUInt16()
                        throws IOException

      Gets the next token from a tokenizer and converts it to an unsigned 16 bit integer.
      Returns:
        The next token in the stream, as an unsigned 16 bit integer.
      Throws:
        `TextParseException` - The input was invalid or not an unsigned 16 bit integer.
        `IOException` - An I/O error occurred.

    - #### getUInt8

          public int getUInt8()
                       throws IOException

      Gets the next token from a tokenizer and converts it to an unsigned 8 bit integer.
      Returns:
        The next token in the stream, as an unsigned 8 bit integer.
      Throws:
        `TextParseException` - The input was invalid or not an unsigned 8 bit integer.
        `IOException` - An I/O error occurred.

    - #### getTTL

          public long getTTL()
                      throws IOException

      Gets the next token from a tokenizer and parses it as a TTL.
      Returns:
        The next token in the stream, as an unsigned 32 bit integer.
      Throws:
        `TextParseException` - The input was not valid.
        `IOException` - An I/O error occurred.
      See Also:
        `TTL`

    - #### getTTLLike

          public long getTTLLike()
                          throws IOException

      Gets the next token from a tokenizer and parses it as if it were a TTL.
      Returns:
        The next token in the stream, as an unsigned 32 bit integer.
      Throws:
        `TextParseException` - The input was not valid.
        `IOException` - An I/O error occurred.
      See Also:
        `TTL`

    - #### getName

          public Name getName(Name origin)
                       throws IOException

      Gets the next token from a tokenizer and converts it to a name.
      Parameters:
        `origin` - The origin to append to relative names.
      Returns:
        The next token in the stream, as a name.
      Throws:
        `TextParseException` - The input was invalid or not a valid name.
        `IOException` - An I/O error occurred.
        `RelativeNameException` - The parsed name was relative, even with the origin.
      See Also:
        `Name`

    - #### getAddress

          public InetAddress getAddress(int family)
                                 throws IOException

      Gets the next token from a tokenizer and converts it to an IP Address.
      Parameters:
        `family` - The address family.
      Returns:
        The next token in the stream, as an InetAddress
      Throws:
        `TextParseException` - The input was invalid or not a valid address.
        `IOException` - An I/O error occurred.
      See Also:
        `Address`

    - #### getEOL

          public void getEOL()
                      throws IOException

      Gets the next token from a tokenizer, which must be an EOL or EOF.
      Throws:
        `TextParseException` - The input was invalid or not an EOL or EOF token.
        `IOException` - An I/O error occurred.

    - #### getBase64

          public byte[] getBase64(boolean required)
                           throws IOException

      Gets the remaining string tokens until an EOL/EOF is seen, concatenates them together, and converts the base64 encoded data to a byte array.
      Parameters:
        `required` - If true, an exception will be thrown if no strings remain; otherwise null be be returned.
      Returns:
        The byte array containing the decoded strings, or null if there were no strings to decode.
      Throws:
        `TextParseException` - The input was invalid.
        `IOException` - An I/O error occurred.

    - #### getBase64

          public byte[] getBase64()
                           throws IOException

      Gets the remaining string tokens until an EOL/EOF is seen, concatenates them together, and converts the base64 encoded data to a byte array.
      Returns:
        The byte array containing the decoded strings, or null if there were no strings to decode.
      Throws:
        `TextParseException` - The input was invalid.
        `IOException` - An I/O error occurred.

    - #### getHex

          public byte[] getHex(boolean required)
                        throws IOException

      Gets the remaining string tokens until an EOL/EOF is seen, concatenates them together, and converts the hex encoded data to a byte array.
      Parameters:
        `required` - If true, an exception will be thrown if no strings remain; otherwise null be be returned.
      Returns:
        The byte array containing the decoded strings, or null if there were no strings to decode.
      Throws:
        `TextParseException` - The input was invalid.
        `IOException` - An I/O error occurred.

    - #### getHex

          public byte[] getHex()
                        throws IOException

      Gets the remaining string tokens until an EOL/EOF is seen, concatenates them together, and converts the hex encoded data to a byte array.
      Returns:
        The byte array containing the decoded strings, or null if there were no strings to decode.
      Throws:
        `TextParseException` - The input was invalid.
        `IOException` - An I/O error occurred.

    - #### getHexString

          public byte[] getHexString()
                              throws IOException

      Gets the next token from a tokenizer and decodes it as hex.
      Returns:
        The byte array containing the decoded string.
      Throws:
        `TextParseException` - The input was invalid.
        `IOException` - An I/O error occurred.

    - #### getBase32String

          public byte[] getBase32String(base32 b32)
                                 throws IOException

      Gets the next token from a tokenizer and decodes it as base32.
      Parameters:
        `b32` - The base32 context to decode with.
      Returns:
        The byte array containing the decoded string.
      Throws:
        `TextParseException` - The input was invalid.
        `IOException` - An I/O error occurred.

    - #### exception

          public TextParseException exception(String s)

      Creates an exception which includes the current state in the error message
      Parameters:
        `s` - The error message to include.
      Returns:
        The exception to be thrown

    - #### close

          public void close()

      Closes any files opened by this tokenizer.

    - #### finalize

          protected void finalize()

      Overrides:
        `finalize` in class `Object`