DocumentParser (Java SE 26 & JDK 26)
Description: declaration: module: java.desktop, package: javax.swing.text.html.parser, class: DocumentParser
Keywords: javax.swing.text.html.parser.DocumentParser class

# Class DocumentParser

java.lang.Object
javax.swing.text.html.parser.Parser
javax.swing.text.html.parser.DocumentParser

All Implemented Interfaces:
  `DTDConstants`

public class DocumentParser extends Parser
A Parser for HTML Documents (actually, you can specify a DTD, but you should really only use this class with the html dtd in swing). Reads an InputStream of HTML and invokes the appropriate methods in the ParserCallback class. This is the default parser used by HTMLEditorKit to parse HTML url's.

This will message the callback for all valid tags, as well as tags that are implied but not explicitly specified. For example, the html string (<p>blah) only has a p tag defined. The callback will see the following methods:

1. handleStartTag(html, ...)
2. handleStartTag(head, ...)
3. handleEndTag(head)
4. handleStartTag(body, ...)
5. handleStartTag(p, ...)
6. handleText(...)
7. handleEndTag(p)
8. handleEndTag(body)
9. handleEndTag(html)

The items in italic are implied, that is, although they were not explicitly specified, to be correct html they should have been present (head isn't necessary, but it is still generated). For tags that are implied, the AttributeSet argument will have a value of `Boolean.TRUE` for the key `HTMLEditorKit.ParserCallback.IMPLIED`.

HTML.Attributes defines a type safe enumeration of html attributes. If an attribute key of a tag is defined in HTML.Attribute, the HTML.Attribute will be used as the key, otherwise a String will be used. For example <p foo=bar class=neat> has two attributes. foo is not defined in HTML.Attribute, where as class is, therefore the AttributeSet will have two values in it, HTML.Attribute.CLASS with a String value of 'neat' and the String key 'foo' with a String value of 'bar'.

The position argument will indicate the start of the tag, comment or text. Similar to arrays, the first character in the stream has a position of 0. For tags that are implied the position will indicate the location of the next encountered tag. In the first example, the implied start body and html tags will have the same position as the p tag, and the implied end p, html and body tags will all have the same position.

As html skips whitespace the position for text will be the position of the first valid character, eg in the string '\n\n\nblah' the text 'blah' will have a position of 3, the newlines are skipped.

For attributes that do not have a value, eg in the html string `<foo blah>` the attribute `blah` does not have a value, there are two possible values that will be placed in the AttributeSet's value:

- If the DTD does not contain an definition for the element, or the definition does not have an explicit value then the value in the AttributeSet will be `HTML.NULL_ATTRIBUTE_VALUE`.
- If the DTD contains an explicit value, as in: `<!ATTLIST OPTION selected (selected) #IMPLIED>` this value from the dtd (in this case selected) will be used.

Once the stream has been parsed, the callback is notified of the most likely end of line string. The end of line string will be one of \n, \r or \r\n, which ever is encountered the most in parsing the stream.

- ## Field Summary

  ### Fields declared in class Parser

  `dtd, strict`
  Modifier and Type
  Field
  Description
  `protected DTD`
  `dtd`
  The dtd.
  `protected boolean`
  `strict`
  This flag determines whether or not the Parser will be strict in enforcing SGML compatibility.

  ### Fields declared in interface DTDConstants

  `ANY, CDATA, CONREF, CURRENT, DEFAULT, EMPTY, ENDTAG, ENTITIES, ENTITY, FIXED, GENERAL, ID, IDREF, IDREFS, IMPLIED, MD, MODEL, MS, NAME, NAMES, NMTOKEN, NMTOKENS, NOTATION, NUMBER, NUMBERS, NUTOKEN, NUTOKENS, PARAMETER, PI, PUBLIC, RCDATA, REQUIRED, SDATA, STARTTAG, SYSTEM`
  Modifier and Type
  Field
  Description
  `static final int`
  `ANY`
  The DTD constant corresponds to ANY
  `static final int`
  `CDATA`
  The DTD constant corresponds to CDATA
  `static final int`
  `CONREF`
  The DTD constant corresponds to CONREF
  `static final int`
  `CURRENT`
  The DTD constant corresponds to CURRENT
  `static final int`
  `DEFAULT`
  The DTD constant corresponds to DEFAULT
  `static final int`
  `EMPTY`
  The DTD constant corresponds to EMPTY
  `static final int`
  `ENDTAG`
  The DTD constant corresponds to ENDTAG
  `static final int`
  `ENTITIES`
  The DTD constant corresponds to ENTITIES
  `static final int`
  `ENTITY`
  The DTD constant corresponds to ENTITY
  `static final int`
  `FIXED`
  The DTD constant corresponds to FIXED
  `static final int`
  `GENERAL`
  The DTD constant corresponds to GENERAL
  `static final int`
  `ID`
  The DTD constant corresponds to ID
  `static final int`
  `IDREF`
  The DTD constant corresponds to IDREF
  `static final int`
  `IDREFS`
  The DTD constant corresponds to IDREFS
  `static final int`
  `IMPLIED`
  The DTD constant corresponds to IMPLIED
  `static final int`
  `MD`
  The DTD constant corresponds to MD
  `static final int`
  `MODEL`
  The DTD constant corresponds to MODEL
  `static final int`
  `MS`
  The DTD constant corresponds to MS
  `static final int`
  `NAME`
  The DTD constant corresponds to NAME
  `static final int`
  `NAMES`
  The DTD constant corresponds to NAMES
  `static final int`
  `NMTOKEN`
  The DTD constant corresponds to NMTOKEN
  `static final int`
  `NMTOKENS`
  The DTD constant corresponds to NMTOKENS
  `static final int`
  `NOTATION`
  The DTD constant corresponds to NOTATION
  `static final int`
  `NUMBER`
  The DTD constant corresponds to NUMBER
  `static final int`
  `NUMBERS`
  The DTD constant corresponds to NUMBERS
  `static final int`
  `NUTOKEN`
  The DTD constant corresponds to NUTOKEN
  `static final int`
  `NUTOKENS`
  The DTD constant corresponds to NUTOKENS
  `static final int`
  `PARAMETER`
  The DTD constant corresponds to PARAMETER
  `static final int`
  `PI`
  The DTD constant corresponds to PI
  `static final int`
  `PUBLIC`
  The DTD constant corresponds to PUBLIC
  `static final int`
  `RCDATA`
  The DTD constant corresponds to RCDATA
  `static final int`
  `REQUIRED`
  The DTD constant corresponds to REQUIRED
  `static final int`
  `SDATA`
  The DTD constant corresponds to SDATA
  `static final int`
  `STARTTAG`
  The DTD constant corresponds to STARTTAG
  `static final int`
  `SYSTEM`
  The DTD constant corresponds to SYSTEM

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `DocumentParser(DTD dtd)`
  Creates document parser with the specified `dtd`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected void`
  `handleEmptyTag(TagElement tag)`
  Handle Empty Tag.
  `protected void`
  `handleEndTag(TagElement tag)`
  Handle End Tag.
  `protected void`
  `handleStartTag(TagElement tag)`
  Handle Start Tag.
  `protected void`
  `handleText(char[] data)`
  Handle Text.
  `void`
  `parse(Reader in, HTMLEditorKit.ParserCallback callback, boolean ignoreCharSet)`
  Parse an HTML stream, given a DTD.

  ### Methods declared in class Parser

  `endTag, error, error, error, error, flushAttributes, getAttributes, getCurrentLine, getCurrentPos, handleComment, handleEOFInComment, handleError, handleTitle, makeTag, makeTag, markFirstTime, parse, parseDTDMarkup, parseMarkupDeclarations, startTag`
  Modifier and Type
  Method
  Description
  `protected void`
  `endTag(boolean omitted)`
  Handle an end tag.
  `protected void`
  `error(String err)`
  Invokes the error handler with the 1st, 2nd and 3rd error message argument "?".
  `protected void`
  `error(String err, String arg1)`
  Invokes the error handler with the 2nd and 3rd error message argument "?".
  `protected void`
  `error(String err, String arg1, String arg2)`
  Invokes the error handler with the 3rd error message argument "?".
  `protected void`
  `error(String err, String arg1, String arg2, String arg3)`
  Invokes the error handler.
  `protected void`
  `flushAttributes()`
  Removes the current attributes.
  `protected SimpleAttributeSet`
  `getAttributes()`
  Returns attributes for the current tag.
  `protected int`
  `getCurrentLine()`
  Returns the line number of the line currently being parsed.
  `protected int`
  `getCurrentPos()`
  Returns the current position.
  `protected void`
  `handleComment(char[] text)`
  Called when an HTML comment is encountered.
  `protected void`
  `handleEOFInComment()`
  Called when the content terminates without closing the HTML comment.
  `protected void`
  `handleError(int ln, String msg)`
  An error has occurred.
  `protected void`
  `handleTitle(char[] text)`
  Called when an HTML title tag is encountered.
  `protected TagElement`
  `makeTag(Element elem)`
  Makes a TagElement.
  `protected TagElement`
  `makeTag(Element elem, boolean fictional)`
  Makes a TagElement.
  `protected void`
  `markFirstTime(Element elem)`
  Marks the first time a tag has been seen in a document
  `void`
  `parse(Reader in)`
  Parse an HTML stream, given a DTD.
  `String`
  `parseDTDMarkup()`
  Parses the Document Type Declaration markup declaration.
  `protected boolean`
  `parseMarkupDeclarations(StringBuffer strBuff)`
  Parse markup declarations.
  `protected void`
  `startTag(TagElement tag)`
  Handle a start tag.

  ### Methods declared in class Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`
  Modifier and Type
  Method
  Description
  `protected Object`
  `clone()`
  Creates and returns a copy of this object.
  `boolean`
  `equals(Object obj)`
  Indicates whether some other object is "equal to" this one.
  `protected void`
  `finalize()`
  Deprecated, for removal: This API element is subject to removal in a future version.
  Finalization is deprecated and subject to removal in a future release.
  `final Class<?>`
  `getClass()`
  Returns the runtime class of this `Object`.
  `int`
  `hashCode()`
  Returns a hash code value for this object.
  `final void`
  `notify()`
  Wakes up a single thread that is waiting on this object's monitor.
  `final void`
  `notifyAll()`
  Wakes up all threads that are waiting on this object's monitor.
  `String`
  `toString()`
  Returns a string representation of the object.
  `final void`
  `wait()`
  Causes the current thread to wait until it is awakened, typically by being notified or interrupted.
  `final void`
  `wait(long timeoutMillis)`
  Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
  `final void`
  `wait(long timeoutMillis, int nanos)`
  Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.

- ## Constructor Details

  - ### DocumentParser

    public DocumentParser(DTD dtd)
    Creates document parser with the specified `dtd`.
    Parameters:
      `dtd` - the dtd.

- ## Method Details

  - ### parse

    public void parse(Reader in, HTMLEditorKit.ParserCallback callback, boolean ignoreCharSet) throws IOException
    Parse an HTML stream, given a DTD.
    Parameters:
      `in` - the reader to read the source from
      `callback` - the callback
      `ignoreCharSet` - if `true` the charset is ignored
    Throws:
      `IOException` - if an I/O error occurs

  - ### handleStartTag

    protected void handleStartTag(TagElement tag)
    Handle Start Tag.
    Overrides:
      `handleStartTag` in class `Parser`
    Parameters:
      `tag` - the tag being handled

  - ### handleEmptyTag

    protected void handleEmptyTag(TagElement tag) throws ChangedCharSetException
    Handle Empty Tag.
    Overrides:
      `handleEmptyTag` in class `Parser`
    Parameters:
      `tag` - the tag being handled
    Throws:
      `ChangedCharSetException` - if the document charset was changed

  - ### handleEndTag

    protected void handleEndTag(TagElement tag)
    Handle End Tag.
    Overrides:
      `handleEndTag` in class `Parser`
    Parameters:
      `tag` - the tag being handled

  - ### handleText

    protected void handleText(char[] data)
    Handle Text.
    Overrides:
      `handleText` in class `Parser`
    Parameters:
      `data` - the section text