# Interface TokenHandler

All Known Implementing Classes:
  `CoalescingTreeBuilder, TreeBuilder`

public interface TokenHandler
`Tokenizer` reports tokens through this interface.

Version:
  $Id$
Author:
  hsivonen

## Method Summary

Modifier and Type
Method
Description
`boolean`
`cdataSectionAllowed()`
Checks if the CDATA sections are allowed.
`void`
`characters(char[] buf, int start, int length)`
Receive character tokens.
`void`
`comment(char[] buf, int start, int length)`
Receive a comment token.
`void`
`doctype(String name, String publicIdentifier, String systemIdentifier, boolean forceQuirks)`
Receive a doctype token.
`void`
`endTag(ElementName eltName)`
Receive an end tag token.
`void`
`endTokenization()`
The perform final cleanup.
`void`
`ensureBufferSpace(int inputLength)`
Notifies the token handler of the worst case amount of data to be reported via `characters()` and `zeroOriginatingReplacementCharacter()`.
`void`
`eof()`
The end-of-file token.
`void`
`startTag(ElementName eltName, HtmlAttributes attributes, boolean selfClosing)`
Receive a start tag token.
`void`
`startTokenization(Tokenizer self)`
This method is called at the start of tokenization before any other methods on this interface are called.
`boolean`
`wantsComments()`
If this handler implementation cares about comments, return `true`.
`void`
`zeroOriginatingReplacementCharacter()`
Reports a U+0000 that's being turned into a U+FFFD.
`void`
`zeroOrReplacementCharacter()`
Emits: * U+0000 if only tokenization is being performed * U+FFFD if tree construction is being performed also

## Method Details

### startTokenization

void startTokenization(Tokenizer self) throws SAXException
This method is called at the start of tokenization before any other methods on this interface are called. Implementations should hold the reference to the `Tokenizer` in order to set the content model flag and in order to be able to query for `Locator` data.

Parameters:
  `self` - the `Tokenizer`.
Throws:
  `SAXException` - if something went wrong

### wantsComments

boolean wantsComments() throws SAXException
If this handler implementation cares about comments, return `true`. If not, return `false`.

Returns:
  whether this handler wants comments
Throws:
  `SAXException` - if something went wrong

### doctype

void doctype(String name, String publicIdentifier, String systemIdentifier, boolean forceQuirks) throws SAXException
Receive a doctype token.

Parameters:
  `name` - the name
  `publicIdentifier` - the public id
  `systemIdentifier` - the system id
  `forceQuirks` - whether the token is correct
Throws:
  `SAXException` - if something went wrong

### startTag

void startTag(ElementName eltName, HtmlAttributes attributes, boolean selfClosing) throws SAXException
Receive a start tag token.

Parameters:
  `eltName` - the tag name
  `attributes` - the attributes
  `selfClosing` - TODO
Throws:
  `SAXException` - if something went wrong

### endTag

void endTag(ElementName eltName) throws SAXException
Receive an end tag token.

Parameters:
  `eltName` - the tag name
Throws:
  `SAXException` - if something went wrong

### comment

void comment(char[] buf, int start, int length) throws SAXException
Receive a comment token. The data is junk if the `wantsComments()` returned `false`.

Parameters:
  `buf` - a buffer holding the data
  `start` - the offset into the buffer
  `length` - the number of code units to read
Throws:
  `SAXException` - if something went wrong

### characters

void characters(char[] buf, int start, int length) throws SAXException
Receive character tokens. This method has the same semantics as the SAX method of the same name.

Parameters:
  `buf` - a buffer holding the data
  `start` - offset into the buffer
  `length` - the number of code units to read
Throws:
  `SAXException` - if something went wrong
See Also:
  - `ContentHandler.characters(char[], int, int)`

### zeroOriginatingReplacementCharacter

void zeroOriginatingReplacementCharacter() throws SAXException
Reports a U+0000 that's being turned into a U+FFFD.

Throws:
  `SAXException` - if something went wrong

### zeroOrReplacementCharacter

void zeroOrReplacementCharacter() throws SAXException
Emits: * U+0000 if only tokenization is being performed * U+FFFD if tree construction is being performed also

Throws:
  `SAXException` - if something went wrong

### eof

void eof() throws SAXException
The end-of-file token.

Throws:
  `SAXException` - if something went wrong

### endTokenization

void endTokenization() throws SAXException
The perform final cleanup.

Throws:
  `SAXException` - if something went wrong

### cdataSectionAllowed

boolean cdataSectionAllowed() throws SAXException
Checks if the CDATA sections are allowed.

Returns:
  `true` if CDATA sections are allowed
Throws:
  `SAXException` - if something went wrong

### ensureBufferSpace

void ensureBufferSpace(int inputLength) throws SAXException
Notifies the token handler of the worst case amount of data to be reported via `characters()` and `zeroOriginatingReplacementCharacter()`.

Parameters:
  `inputLength` - the maximum number of chars that can be reported via `characters()` and `zeroOriginatingReplacementCharacter()` before a new call to this method.
Throws:
  `SAXException`