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.ext.DeclHandler, org.xml.sax.DTDHandler, org.xml.sax.EntityResolver, org.xml.sax.ErrorHandler, 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

SAXHandler supports SAXBuilder

Version:

$Revision: 1.44 $, $Date: 2002/04/12 14:02:43 $

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

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

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.

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

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

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.