    All Packages  Class Hierarchy  This Package  Previous  Next  Index

# Class org.jdom.input.SAXHandler

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

public class SAXHandler
extends DefaultHandler
implements LexicalHandler, DeclHandler, 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

##

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

##

SAXHandler()

  This will create a new `SAXHandler` that listens to SAX events and creates a JDOM Document.

SAXHandler(Document)

  This will set the `Document` to use. Deprecated.

SAXHandler(JDOMFactory)

  This will create a new `SAXHandler` that listens to SAX events and creates a JDOM Document.

##

appendExternalId(String, String)

  Appends an external ID to the internal subset buffer.

attributeDecl(String, String, String, String, String)

  This handles an attribute declaration in the internal subset

characters(char[], int, int)

  This will report character data (within an element).

comment(char[], int, int)

  This reports that a comments is parsed.

elementDecl(String, String)

  Handle an element declaration in a DTD

endCDATA()

  Report a CDATA section - ignored in SAXBuilder.

endDTD()

  This signifies that the reading of the DTD is complete.

endElement(String, String, String)

  Indicates the end of an element (`</[element name]>`) is reached.

endEntity(String)
endPrefixMapping(String)

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

externalEntityDecl(String, String, String)
  This is called when the parser encounters an external entity declaration.
flushCharacters()

  This will flush any characters from SAX character calls we've been buffering.

getCurrentElement()

  Returns the being-parsed element.

getDocument()

  Returns the document.

getDocumentLocator()

  Provides access to the {

getExpandEntities()

  Returns whether or not entities will be expanded during the build.

getFactory()

  Returns the factory used for constructing objects.

getIgnoringElementContentWhitespace()

  Returns whether or not the parser will elminate whitespace in element content (sometimes known as "ignorable whitespace") when building the document.

ignorableWhitespace(char[], int, int)

  Capture ignorable whitespace as text.

internalEntityDecl(String, String)

  Handle an internal entity declaration in a DTD.

notationDecl(String, String, String)

  Handle the declaration of a Notation in a DTD

processingInstruction(String, String)

  This will indicate that a processing instruction has been encountered.

setDocumentLocator(Locator)

  Receives an object for locating the origin of SAX document events.

setExpandEntities(boolean)

  This sets whether or not to expand entities during the build.

setIgnoringElementContentWhitespace(boolean)

  Specifies whether or not the parser should elminate whitespace in element content (sometimes known as "ignorable whitespace") when building the document.

skippedEntity(String)

  This indicates that an unresolvable entity reference has been encountered, normally because the external DTD subset has not been read.

startCDATA()

  Report a CDATA section - ignored in SAXBuilder.

startDTD(String, String, String)

  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.

startElement(String, String, String, Attributes)

  This reports the occurrence of an actual element.

startEntity(String)
startPrefixMapping(String, String)

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

unparsedEntityDecl(String, String, String, String)

  Handler for unparsed entity declarations in the DTD

##

stack

     protected 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 LinkedList declaredNamespaces

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

availableNamespaces

     protected LinkedList availableNamespaces

  The namespaces in scope and actually attached to an element

##

SAXHandler

     public SAXHandler(Document document) throws IOException

  Note: SAXHandler() is 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: IOException
    when errors occur.

SAXHandler

     public SAXHandler() throws 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: IOException
    when errors occur.

SAXHandler

     public SAXHandler(JDOMFactory factory) throws 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: IOException
    when errors occur.

##

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

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

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

externalEntityDecl

     public void externalEntityDecl(String name,
                                    String publicID,
                                    String systemID) throws SAXException

  This is called when the parser encounters an external entity declaration.

  Parameters:
    name - entity name
    publicID - public id
    systemID - system id
  Throws: SAXException
    when things go wrong

attributeDecl

     public void attributeDecl(String eName,
                               String aName,
                               String type,
                               String valueDefault,
                               String value) throws SAXException

  This handles an attribute declaration in the internal subset

  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(String name,
                             String model) throws SAXException

  Handle an element declaration in a DTD

  Parameters:
    name - `String` name of element
    model - `String` model of the element in DTD syntax

internalEntityDecl

     public void internalEntityDecl(String name,
                                    String value) throws SAXException

  Handle an internal entity declaration in a DTD.

  Parameters:
    name - `String` name of entity
    value - `String` value of the entity

processingInstruction

     public void processingInstruction(String target,
                                       String data) throws SAXException

  This will indicate that a processing instruction has been encountered. (The XML declaration is not a processing instruction and will not be reported.)

  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: SAXException
    when things go wrong
  Overrides:
    processingInstruction in class DefaultHandler

skippedEntity

     public void skippedEntity(String name) throws SAXException

  This indicates that an unresolvable entity reference has been encountered, normally because the external DTD subset has not been read.

  Parameters:
    name - `String` name of entity
  Throws: SAXException
    when things go wrong
  Overrides:
    skippedEntity in class DefaultHandler

startPrefixMapping

     public void startPrefixMapping(String prefix,
                                    String uri) throws SAXException

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

  Parameters:
    prefix - `String` namespace prefix.
    uri - `String` namespace URI.
  Overrides:
    startPrefixMapping in class DefaultHandler

endPrefixMapping

     public void endPrefixMapping(String prefix) throws SAXException

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

  Parameters:
    prefix - `String` namespace prefix.
    uri - `String` namespace URI.
  Overrides:
    endPrefixMapping in class DefaultHandler

startElement

     public void startElement(String namespaceURI,
                              String localName,
                              String qName,
                              Attributes atts) throws 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`.

  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: SAXException
    when things go wrong
  Overrides:
    startElement in class DefaultHandler

characters

     public void characters(char ch[],
                            int start,
                            int length) throws SAXException

  This will report character data (within an element).

  Parameters:
    ch - `char[]` character array with character data
    start - `int` index in array where data starts.
    length - `int` length of data.
  Overrides:
    characters in class DefaultHandler

flushCharacters

     protected void flushCharacters() throws SAXException

  This will flush any characters from SAX character calls we've been buffering.

  Throws: SAXException
    when things go wrong

ignorableWhitespace

     public void ignorableWhitespace(char ch[],
                                     int start,
                                     int length) throws SAXException

  Capture ignorable whitespace as text. If setIgnoringElementContentWhitespace(true) has been called then this method does nothing.

  Parameters:
    ch - `[]` - char array of ignorable whitespace
    start - `int` - starting position within array
    length - `int` - length of whitespace after start
  Throws: SAXException
    when things go wrong
  Overrides:
    ignorableWhitespace in class DefaultHandler

endElement

     public void endElement(String namespaceURI,
                            String localName,
                            String qName) throws 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.

  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: SAXException
    when things go wrong
  Overrides:
    endElement in class DefaultHandler

startDTD

     public void startDTD(String name,
                          String publicID,
                          String systemID) throws 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.

  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 SAXException

  This signifies that the reading of the DTD is complete.

startEntity

     public void startEntity(String name) throws SAXException

endEntity

     public void endEntity(String name) throws SAXException

startCDATA

     public void startCDATA() throws SAXException

  Report a CDATA section - ignored in SAXBuilder.

endCDATA

     public void endCDATA() throws SAXException

  Report a CDATA section - ignored in SAXBuilder.

comment

     public void comment(char ch[],
                         int start,
                         int length) throws 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.

  Parameters:
    ch - `ch[]` array of comment characters.
    start - `int` index to start reading from.
    length - `int` length of data.

notationDecl

     public void notationDecl(String name,
                              String publicID,
                              String systemID) throws SAXException

  Handle the declaration of a Notation in a DTD

  Parameters:
    name - name of the notation
    publicID - the public ID of the notation
    systemID - the system ID of the notation
  Overrides:
    notationDecl in class DefaultHandler

unparsedEntityDecl

     public void unparsedEntityDecl(String name,
                                    String publicID,
                                    String systemID,
                                    String notationName) throws SAXException

  Handler for unparsed entity declarations in the DTD

  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
  Overrides:
    unparsedEntityDecl in class DefaultHandler

appendExternalId

     protected void appendExternalId(String publicID,
                                     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 SAXException

  Returns the being-parsed element.

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

setDocumentLocator

     public void setDocumentLocator(Locator locator)

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

  {@link JDOMFactory} implementations can use the {@link #getDocumentLocator} method to get access to the {@link Locator} during parse.

  Parameters:
    locator - `Locator` an object that can return the location of any SAX document event.
  Overrides:
    setDocumentLocator in class DefaultHandler

getDocumentLocator

     public Locator getDocumentLocator()

  Provides access to the {@link Locator} object provided by the SAX parser.

  Returns:
    `Locator` an object that can return the location of any SAX document event.

    All Packages  Class Hierarchy  This Package  Previous  Next  Index