SAXHandler (JDOM v1.1.1)
Date: 2019-09-02

org.jdom.input

## Class SAXHandler

- java.lang.Object
- - org.xml.sax.helpers.DefaultHandler
  - - org.jdom.input.SAXHandler

- All Implemented Interfaces:
    org.xml.sax.ContentHandler, org.xml.sax.DTDHandler, org.xml.sax.EntityResolver, org.xml.sax.ErrorHandler, org.xml.sax.ext.DeclHandler, org.xml.sax.ext.LexicalHandler

      public class SAXHandler
      extends org.xml.sax.helpers.DefaultHandler
      implements org.xml.sax.ext.LexicalHandler, org.xml.sax.ext.DeclHandler, org.xml.sax.DTDHandler

  A support class for `SAXBuilder`.
  Version:
    $Revision: 1.73 $, $Date: 2007/11/10 05:29:00 $
  Author:
    Brett McLaughlin, Jason Hunter, Philip Nelson, Bradley S. Huffman, phil@triloggroup.com

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `SAXHandler()` This will create a new `SAXHandler` that listens to SAX events and creates a JDOM Document.
    `SAXHandler(JDOMFactory factory)` This will create a new `SAXHandler` that listens to SAX events and creates a JDOM Document.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `attributeDecl(java.lang.String eName, java.lang.String aName, java.lang.String type, java.lang.String valueDefault, java.lang.String value)` This handles an attribute declaration in the internal subset.
    `void` | `characters(char[] ch, int start, int length)` This will report character data (within an element).
    `void` | `comment(char[] ch, int start, int length)` This reports that a comments is parsed.
    `void` | `elementDecl(java.lang.String name, java.lang.String model)` Handle an element declaration in a DTD.
    `void` | `endCDATA()` Report a CDATA section
    `void` | `endDTD()` This signifies that the reading of the DTD is complete.
    `void` | `endElement(java.lang.String namespaceURI, java.lang.String localName, java.lang.String qName)` Indicates the end of an element (`</[element name]>`) is reached.
    `void` | `endEntity(java.lang.String name)`
    `void` | `externalEntityDecl(java.lang.String name, java.lang.String publicID, java.lang.String systemID)` This is called when the parser encounters an external entity declaration.
    `protected void` | `flushCharacters()` This will flush any characters from SAX character calls we've been buffering.
    `protected void` | `flushCharacters(java.lang.String data)` Flush the given string into the document.
    `Element` | `getCurrentElement()` Returns the being-parsed element.
    `Document` | `getDocument()` Returns the document.
    `org.xml.sax.Locator` | `getDocumentLocator()` Provides access to the `Locator` object provided by the SAX parser.
    `boolean` | `getExpandEntities()` Returns whether or not entities will be expanded during the build.
    `JDOMFactory` | `getFactory()` Returns the factory used for constructing objects.
    `boolean` | `getIgnoringBoundaryWhitespace()` Returns whether or not the parser will elminate element content containing only whitespace.
    `boolean` | `getIgnoringElementContentWhitespace()` Returns whether or not the parser will elminate whitespace in element content (sometimes known as "ignorable whitespace") when building the document.
    `void` | `ignorableWhitespace(char[] ch, int start, int length)` Capture ignorable whitespace as text.
    `void` | `internalEntityDecl(java.lang.String name, java.lang.String value)` Handle an internal entity declaration in a DTD.
    `void` | `notationDecl(java.lang.String name, java.lang.String publicID, java.lang.String systemID)` Handle the declaration of a Notation in a DTD
    `void` | `processingInstruction(java.lang.String target, java.lang.String data)` This will indicate that a processing instruction has been encountered.
    `protected void` | `pushElement(Element element)` Pushes an element onto the tree under construction.
    `void` | `setDocumentLocator(org.xml.sax.Locator locator)` Receives an object for locating the origin of SAX document events.
    `void` | `setExpandEntities(boolean expand)` This sets whether or not to expand entities during the build.
    `void` | `setIgnoringBoundaryWhitespace(boolean ignoringBoundaryWhite)` Specifies whether or not the parser should elminate text() nodes containing only whitespace when building the document.
    `void` | `setIgnoringElementContentWhitespace(boolean ignoringWhite)` Specifies whether or not the parser should elminate whitespace in element content (sometimes known as "ignorable whitespace") when building the document.
    `void` | `skippedEntity(java.lang.String name)` This indicates that an unresolvable entity reference has been encountered, normally because the external DTD subset has not been read.
    `void` | `startCDATA()` Report a CDATA section
    `void` | `startDocument()`
    `void` | `startDTD(java.lang.String name, java.lang.String publicID, java.lang.String systemID)` This will signify that a DTD is being parsed, and can be used to ensure that comments and other lexical structures in the DTD are not added to the JDOM `Document` object.
    `void` | `startElement(java.lang.String namespaceURI, java.lang.String localName, java.lang.String qName, org.xml.sax.Attributes atts)` This reports the occurrence of an actual element.
    `void` | `startEntity(java.lang.String name)`
    `void` | `startPrefixMapping(java.lang.String prefix, java.lang.String uri)` This will add the prefix mapping to the JDOM `Document` object.
    `void` | `unparsedEntityDecl(java.lang.String name, java.lang.String publicID, java.lang.String systemID, java.lang.String notationName)` Handler for unparsed entity declarations in the DTD

    - ### Methods inherited from class org.xml.sax.helpers.DefaultHandler

      `endDocument, endPrefixMapping, error, fatalError, resolveEntity, warning`

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

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

- - ### Constructor Detail

    - #### SAXHandler

          public SAXHandler()

      This will create a new `SAXHandler` that listens to SAX events and creates a JDOM Document. The objects will be constructed using the default factory.

    - #### SAXHandler

          public SAXHandler(JDOMFactory factory)

      This will create a new `SAXHandler` that listens to SAX events and creates a JDOM Document. The objects will be constructed using the provided factory.
      Parameters:
        `factory` - `JDOMFactory` to be used for constructing objects

  - ### Method Detail

    - #### pushElement

          protected void pushElement(Element element)

      Pushes an element onto the tree under construction. Allows subclasses to put content under a dummy root element which is useful for building content that would otherwise be a non-well formed document.
      Parameters:
        `element` - root element under which content will be built

    - #### getDocument

          public Document getDocument()

      Returns the document. Should be called after parsing is complete.
      Returns:
        `Document` - Document that was built

    - #### getFactory

          public JDOMFactory getFactory()

      Returns the factory used for constructing objects.
      Returns:
        `JDOMFactory` - the factory used for constructing objects.
      See Also:
        `SAXHandler(org.jdom.JDOMFactory)`

    - #### setExpandEntities

          public void setExpandEntities(boolean expand)

      This sets whether or not to expand entities during the build. A true means to expand entities as normal content. A false means to leave entities unexpanded as `EntityRef` objects. The default is true.
      Parameters:
        `expand` - `boolean` indicating whether entity expansion should occur.

    - #### getExpandEntities

          public boolean getExpandEntities()

      Returns whether or not entities will be expanded during the build.
      Returns:
        `boolean` - whether entity expansion will occur during build.
      See Also:
        `setExpandEntities(boolean)`

    - #### setIgnoringElementContentWhitespace

          public void setIgnoringElementContentWhitespace(boolean ignoringWhite)

      Specifies whether or not the parser should elminate whitespace in element content (sometimes known as "ignorable whitespace") when building the document. Only whitespace which is contained within element content that has an element only content model will be eliminated (see XML Rec 3.2.1). For this setting to take effect requires that validation be turned on. The default value of this setting is `false`.
      Parameters:
        `ignoringWhite` - Whether to ignore ignorable whitespace

    - #### setIgnoringBoundaryWhitespace

          public void setIgnoringBoundaryWhitespace(boolean ignoringBoundaryWhite)

      Specifies whether or not the parser should elminate text() nodes containing only whitespace when building the document. See `SAXBuilder.setIgnoringBoundaryWhitespace(boolean)`.
      Parameters:
        `ignoringBoundaryWhite` - Whether to ignore only whitespace content

    - #### getIgnoringBoundaryWhitespace

          public boolean getIgnoringBoundaryWhitespace()

      Returns whether or not the parser will elminate element content containing only whitespace.
      Returns:
        `boolean` - whether only whitespace content will be ignored during build.
      See Also:
        `setIgnoringBoundaryWhitespace(boolean)`

    - #### getIgnoringElementContentWhitespace

          public boolean getIgnoringElementContentWhitespace()

      Returns whether or not the parser will elminate whitespace in element content (sometimes known as "ignorable whitespace") when building the document.
      Returns:
        `boolean` - whether ignorable whitespace will be ignored during build.
      See Also:
        `setIgnoringElementContentWhitespace(boolean)`

    - #### startDocument

          public void startDocument()

      Specified by:
        `startDocument` in interface `org.xml.sax.ContentHandler`
      Overrides:
        `startDocument` in class `org.xml.sax.helpers.DefaultHandler`

    - #### externalEntityDecl

          public void externalEntityDecl(java.lang.String name,
                                         java.lang.String publicID,
                                         java.lang.String systemID)
                                  throws org.xml.sax.SAXException

      This is called when the parser encounters an external entity declaration.
      Specified by:
        `externalEntityDecl` in interface `org.xml.sax.ext.DeclHandler`
      Parameters:
        `name` - entity name
        `publicID` - public id
        `systemID` - system id
      Throws:
        `org.xml.sax.SAXException` - when things go wrong

    - #### attributeDecl

          public void attributeDecl(java.lang.String eName,
                                    java.lang.String aName,
                                    java.lang.String type,
                                    java.lang.String valueDefault,
                                    java.lang.String value)
                             throws org.xml.sax.SAXException

      This handles an attribute declaration in the internal subset.
      Specified by:
        `attributeDecl` in interface `org.xml.sax.ext.DeclHandler`
      Parameters:
        `eName` - `String` element name of attribute
        `aName` - `String` attribute name
        `type` - `String` attribute type
        `valueDefault` - `String` default value of attribute
        `value` - `String` value of attribute
      Throws:
        `org.xml.sax.SAXException`

    - #### elementDecl

          public void elementDecl(java.lang.String name,
                                  java.lang.String model)
                           throws org.xml.sax.SAXException

      Handle an element declaration in a DTD.
      Specified by:
        `elementDecl` in interface `org.xml.sax.ext.DeclHandler`
      Parameters:
        `name` - `String` name of element
        `model` - `String` model of the element in DTD syntax
      Throws:
        `org.xml.sax.SAXException`

    - #### internalEntityDecl

          public void internalEntityDecl(java.lang.String name,
                                         java.lang.String value)
                                  throws org.xml.sax.SAXException

      Handle an internal entity declaration in a DTD.
      Specified by:
        `internalEntityDecl` in interface `org.xml.sax.ext.DeclHandler`
      Parameters:
        `name` - `String` name of entity
        `value` - `String` value of the entity
      Throws:
        `org.xml.sax.SAXException`

    - #### processingInstruction

          public void processingInstruction(java.lang.String target,
                                            java.lang.String data)
                                     throws org.xml.sax.SAXException

      This will indicate that a processing instruction has been encountered. (The XML declaration is not a processing instruction and will not be reported.)
      Specified by:
        `processingInstruction` in interface `org.xml.sax.ContentHandler`
      Overrides:
        `processingInstruction` in class `org.xml.sax.helpers.DefaultHandler`
      Parameters:
        `target` - `String` target of PI
        `data` - `String` containing all data sent to the PI. This typically looks like one or more attribute value pairs.
      Throws:
        `org.xml.sax.SAXException` - when things go wrong

    - #### skippedEntity

          public void skippedEntity(java.lang.String name)
                             throws org.xml.sax.SAXException

      This indicates that an unresolvable entity reference has been encountered, normally because the external DTD subset has not been read.
      Specified by:
        `skippedEntity` in interface `org.xml.sax.ContentHandler`
      Overrides:
        `skippedEntity` in class `org.xml.sax.helpers.DefaultHandler`
      Parameters:
        `name` - `String` name of entity
      Throws:
        `org.xml.sax.SAXException` - when things go wrong

    - #### startPrefixMapping

          public void startPrefixMapping(java.lang.String prefix,
                                         java.lang.String uri)
                                  throws org.xml.sax.SAXException

      This will add the prefix mapping to the JDOM `Document` object.
      Specified by:
        `startPrefixMapping` in interface `org.xml.sax.ContentHandler`
      Overrides:
        `startPrefixMapping` in class `org.xml.sax.helpers.DefaultHandler`
      Parameters:
        `prefix` - `String` namespace prefix.
        `uri` - `String` namespace URI.
      Throws:
        `org.xml.sax.SAXException`

    - #### startElement

          public void startElement(java.lang.String namespaceURI,
                                   java.lang.String localName,
                                   java.lang.String qName,
                                   org.xml.sax.Attributes atts)
                            throws org.xml.sax.SAXException

      This reports the occurrence of an actual element. It will include the element's attributes, with the exception of XML vocabulary specific attributes, such as `xmlns:[namespace prefix]` and `xsi:schemaLocation`.
      Specified by:
        `startElement` in interface `org.xml.sax.ContentHandler`
      Overrides:
        `startElement` in class `org.xml.sax.helpers.DefaultHandler`
      Parameters:
        `namespaceURI` - `String` namespace URI this element is associated with, or an empty `String`
        `localName` - `String` name of element (with no namespace prefix, if one is present)
        `qName` - `String` XML 1.0 version of element name: [namespace prefix]:[localName]
        `atts` - `Attributes` list for this element
      Throws:
        `org.xml.sax.SAXException` - when things go wrong

    - #### characters

          public void characters(char[] ch,
                                 int start,
                                 int length)
                          throws org.xml.sax.SAXException

      This will report character data (within an element).
      Specified by:
        `characters` in interface `org.xml.sax.ContentHandler`
      Overrides:
        `characters` in class `org.xml.sax.helpers.DefaultHandler`
      Parameters:
        `ch` - `char[]` character array with character data
        `start` - `int` index in array where data starts.
        `length` - `int` length of data.
      Throws:
        `org.xml.sax.SAXException`

    - #### ignorableWhitespace

          public void ignorableWhitespace(char[] ch,
                                          int start,
                                          int length)
                                   throws org.xml.sax.SAXException

      Capture ignorable whitespace as text. If setIgnoringElementContentWhitespace(true) has been called then this method does nothing.
      Specified by:
        `ignorableWhitespace` in interface `org.xml.sax.ContentHandler`
      Overrides:
        `ignorableWhitespace` in class `org.xml.sax.helpers.DefaultHandler`
      Parameters:
        `ch` - `[]` - char array of ignorable whitespace
        `start` - `int` - starting position within array
        `length` - `int` - length of whitespace after start
      Throws:
        `org.xml.sax.SAXException` - when things go wrong

    - #### flushCharacters

          protected void flushCharacters()
                                  throws org.xml.sax.SAXException

      This will flush any characters from SAX character calls we've been buffering.
      Throws:
        `org.xml.sax.SAXException` - when things go wrong

    - #### flushCharacters

          protected void flushCharacters(java.lang.String data)
                                  throws org.xml.sax.SAXException

      Flush the given string into the document. This is a protected method so subclassers can control text handling without knowledge of the internals of this class.
      Parameters:
        `data` - string to flush
      Throws:
        `org.xml.sax.SAXException`

    - #### endElement

          public void endElement(java.lang.String namespaceURI,
                                 java.lang.String localName,
                                 java.lang.String qName)
                          throws org.xml.sax.SAXException

      Indicates the end of an element (`</[element name]>`) is reached. Note that the parser does not distinguish between empty elements and non-empty elements, so this will occur uniformly.
      Specified by:
        `endElement` in interface `org.xml.sax.ContentHandler`
      Overrides:
        `endElement` in class `org.xml.sax.helpers.DefaultHandler`
      Parameters:
        `namespaceURI` - `String` URI of namespace this element is associated with
        `localName` - `String` name of element without prefix
        `qName` - `String` name of element in XML 1.0 form
      Throws:
        `org.xml.sax.SAXException` - when things go wrong

    - #### startDTD

          public void startDTD(java.lang.String name,
                               java.lang.String publicID,
                               java.lang.String systemID)
                        throws org.xml.sax.SAXException

      This will signify that a DTD is being parsed, and can be used to ensure that comments and other lexical structures in the DTD are not added to the JDOM `Document` object.
      Specified by:
        `startDTD` in interface `org.xml.sax.ext.LexicalHandler`
      Parameters:
        `name` - `String` name of element listed in DTD
        `publicID` - `String` public ID of DTD
        `systemID` - `String` system ID of DTD
      Throws:
        `org.xml.sax.SAXException`

    - #### endDTD

          public void endDTD()
                      throws org.xml.sax.SAXException

      This signifies that the reading of the DTD is complete.
      Specified by:
        `endDTD` in interface `org.xml.sax.ext.LexicalHandler`
      Throws:
        `org.xml.sax.SAXException`

    - #### startEntity

          public void startEntity(java.lang.String name)
                           throws org.xml.sax.SAXException

      Specified by:
        `startEntity` in interface `org.xml.sax.ext.LexicalHandler`
      Throws:
        `org.xml.sax.SAXException`

    - #### endEntity

          public void endEntity(java.lang.String name)
                         throws org.xml.sax.SAXException

      Specified by:
        `endEntity` in interface `org.xml.sax.ext.LexicalHandler`
      Throws:
        `org.xml.sax.SAXException`

    - #### startCDATA

          public void startCDATA()
                          throws org.xml.sax.SAXException

      Report a CDATA section
      Specified by:
        `startCDATA` in interface `org.xml.sax.ext.LexicalHandler`
      Throws:
        `org.xml.sax.SAXException`

    - #### endCDATA

          public void endCDATA()
                        throws org.xml.sax.SAXException

      Report a CDATA section
      Specified by:
        `endCDATA` in interface `org.xml.sax.ext.LexicalHandler`
      Throws:
        `org.xml.sax.SAXException`

    - #### comment

          public void comment(char[] ch,
                              int start,
                              int length)
                       throws org.xml.sax.SAXException

      This reports that a comments is parsed. If not in the DTD, this comment is added to the current JDOM `Element`, or the `Document` itself if at that level.
      Specified by:
        `comment` in interface `org.xml.sax.ext.LexicalHandler`
      Parameters:
        `ch` - `ch[]` array of comment characters.
        `start` - `int` index to start reading from.
        `length` - `int` length of data.
      Throws:
        `org.xml.sax.SAXException`

    - #### notationDecl

          public void notationDecl(java.lang.String name,
                                   java.lang.String publicID,
                                   java.lang.String systemID)
                            throws org.xml.sax.SAXException

      Handle the declaration of a Notation in a DTD
      Specified by:
        `notationDecl` in interface `org.xml.sax.DTDHandler`
      Overrides:
        `notationDecl` in class `org.xml.sax.helpers.DefaultHandler`
      Parameters:
        `name` - name of the notation
        `publicID` - the public ID of the notation
        `systemID` - the system ID of the notation
      Throws:
        `org.xml.sax.SAXException`

    - #### unparsedEntityDecl

          public void unparsedEntityDecl(java.lang.String name,
                                         java.lang.String publicID,
                                         java.lang.String systemID,
                                         java.lang.String notationName)
                                  throws org.xml.sax.SAXException

      Handler for unparsed entity declarations in the DTD
      Specified by:
        `unparsedEntityDecl` in interface `org.xml.sax.DTDHandler`
      Overrides:
        `unparsedEntityDecl` in class `org.xml.sax.helpers.DefaultHandler`
      Parameters:
        `name` - `String` of the unparsed entity decl
        `publicID` - `String` of the unparsed entity decl
        `systemID` - `String` of the unparsed entity decl
        `notationName` - `String` of the unparsed entity decl
      Throws:
        `org.xml.sax.SAXException`

    - #### getCurrentElement

          public Element getCurrentElement()
                                    throws org.xml.sax.SAXException

      Returns the being-parsed element.
      Returns:
        `Element` - element being built.
      Throws:
        `org.xml.sax.SAXException`

    - #### setDocumentLocator

          public void setDocumentLocator(org.xml.sax.Locator locator)

      Receives an object for locating the origin of SAX document events. This method is invoked by the SAX parser.

      `JDOMFactory` implementations can use the `getDocumentLocator()` method to get access to the `Locator` during parse.

      Specified by:
        `setDocumentLocator` in interface `org.xml.sax.ContentHandler`
      Overrides:
        `setDocumentLocator` in class `org.xml.sax.helpers.DefaultHandler`
      Parameters:
        `locator` - `Locator` an object that can return the location of any SAX document event.

    - #### getDocumentLocator

          public org.xml.sax.Locator getDocumentLocator()

      Provides access to the `Locator` object provided by the SAX parser.
      Returns:
        `Locator` an object that can return the location of any SAX document event.

Copyright ? 2007 Jason Hunter, Brett McLaughlin. All Rights Reserved.