## org.jdom.input
Class SAXHandler

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

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

`SAXHandler` supports SAXBuilder

Version:
  $Revision: 1.39 $, $Date: 2002/03/15 05:36:48 $
Author:
  Brett McLaughlin, Jason Hunter, Philip Nelson, Bradley S. Huffman, phil@triloggroup.com

Field Summary
`protected boolean` `atRoot` Indicator of where in the document we are
`protected java.util.LinkedList` `availableNamespaces` The namespaces in scope and actually attached to an element
`protected java.util.LinkedList` `declaredNamespaces` Temporary holder for namespaces that have been declared with startPrefixMapping, but are not yet available on the element
`protected boolean` `inCDATA` Indicator of whether we are in a CDATA
`protected boolean` `inDTD` Indicator of whether we are in the DocType.
`protected boolean` `inInternalSubset` Indicator of whether we are in the internal subset
`protected boolean` `previousCDATA` Indicator of whether we previously where in a CDATA
`protected java.util.Stack` `stack` Element stack
`protected boolean` `suppress` Indicator of whether we are actively suppressing (non-expanding) a current entity

Constructor Summary
`SAXHandler()` This will create a new `SAXHandler` that listens to SAX events and creates a JDOM Document.
`SAXHandler(Document document)` Deprecated. Deprecated in beta7, use SAXHandler() instead and let SAXHandler create the Document, then retrieve it with getDocument()
`SAXHandler(JDOMFactory factory)` This will create a new `SAXHandler` that listens to SAX events and creates a JDOM Document.

Method Summary
`protected void` `appendExternalId(java.lang.String publicID, java.lang.String systemID)` Appends an external ID to the internal subset buffer.
`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 - ignored in SAXBuilder.
`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` `endPrefixMapping(java.lang.String prefix)` This will add the prefix mapping to the JDOM `Document` object.
`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 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` `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.
`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` `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 - ignored in SAXBuilder.
`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, error, fatalError, resolveEntity, startDocument, warning`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### stack

    protected java.util.Stack stack

  Element stack

### atRoot

    protected boolean atRoot

  Indicator of where in the document we are

### inDTD

    protected boolean inDTD

  Indicator of whether we are in the DocType. Note that the DTD consists of both the internal subset (inside the tag) and the external subset (in a separate .dtd file).

### inInternalSubset

    protected boolean inInternalSubset

  Indicator of whether we are in the internal subset

### previousCDATA

    protected boolean previousCDATA

  Indicator of whether we previously where in a CDATA

### inCDATA

    protected boolean inCDATA

  Indicator of whether we are in a CDATA

### suppress

    protected boolean suppress

  Indicator of whether we are actively suppressing (non-expanding) a current entity

### declaredNamespaces

    protected java.util.LinkedList declaredNamespaces

  Temporary holder for namespaces that have been declared with startPrefixMapping, but are not yet available on the element

### availableNamespaces

    protected java.util.LinkedList availableNamespaces

  The namespaces in scope and actually attached to an element

Constructor Detail

### SAXHandler

    public SAXHandler(Document document)
               throws java.io.IOException

  Deprecated. Deprecated in beta7, use SAXHandler() instead and let SAXHandler create the Document, then retrieve it with getDocument()

  This will set the `Document` to use.

  Parameters:
    `document` - `Document` being parsed.
  Throws:
    java.io.IOException - when errors occur.

### SAXHandler

    public SAXHandler()
               throws java.io.IOException

  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.

  Throws:
    java.io.IOException - when errors occur.

### SAXHandler

    public SAXHandler(JDOMFactory factory)
               throws java.io.IOException

  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
  Throws:
    java.io.IOException - when errors occur.

Method Detail

### 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.input.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

### 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)`

### 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

### 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

### 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

### 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.)

  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.

  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.

  Overrides:
    startPrefixMapping in class org.xml.sax.helpers.DefaultHandler
  Parameters:
    `prefix` - `String` namespace prefix.
    `uri` - `String` namespace URI.

### endPrefixMapping

    public void endPrefixMapping(java.lang.String prefix)
                          throws org.xml.sax.SAXException

  This will add the prefix mapping to the JDOM `Document` object.

  Overrides:
    endPrefixMapping in class org.xml.sax.helpers.DefaultHandler
  Parameters:
    `prefix` - `String` namespace prefix.
    `uri` - `String` namespace URI.

### 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`.

  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).

  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.

### 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

### 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.

  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

### 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.

  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

### 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

### startEntity

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

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

### endEntity

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

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

### startCDATA

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

  Report a CDATA section - ignored in SAXBuilder.

  Specified by:
    startCDATA in interface org.xml.sax.ext.LexicalHandler

### endCDATA

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

  Report a CDATA section - ignored in SAXBuilder.

  Specified by:
    endCDATA in interface org.xml.sax.ext.LexicalHandler

### 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.

### 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

### 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

### appendExternalId

    protected void appendExternalId(java.lang.String publicID,
                                    java.lang.String systemID)

  Appends an external ID to the internal subset buffer. Either publicID or systemID may be null, but not both.

  Parameters:
    `publicID` - the public ID
    `systemID` - the system ID

### getCurrentElement

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

  Returns the being-parsed element.

  Returns:
    `Element` - element at the top of the stack.

### 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.

  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 © 2002 Jason Hunter, Brett McLaughlin. All Rights Reserved.