org.jdom.input

Class SAXHandler

Implemented Interfaces:
DeclHandler, DTDHandler, LexicalHandler

public class SAXHandler
extends DefaultHandler
implements LexicalHandler, DeclHandler, DTDHandler

SAXHandler supports SAXBuilder

Version:
$Revision: 1.39 $, $Date: 2002/03/15 05:36:48 $

Authors:
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 LinkedList
availableNamespaces
The namespaces in scope and actually attached to an element
protected 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 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(String publicID, String systemID)
Appends an external ID to the internal subset buffer.
void
attributeDecl(String eName, String aName, String type, String valueDefault, 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(String name, 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(String namespaceURI, String localName, String qName)
Indicates the end of an element (</[element name]>) is reached.
void
endEntity(String name)
void
endPrefixMapping(String prefix)
This will add the prefix mapping to the JDOM Document object.
void
externalEntityDecl(String name, String publicID, 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.
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(String name, String value)
Handle an internal entity declaration in a DTD.
void
notationDecl(String name, String publicID, String systemID)
Handle the declaration of a Notation in a DTD
void
processingInstruction(String target, String data)
This will indicate that a processing instruction has been encountered.
void
setDocumentLocator(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(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(String name, String publicID, 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(String namespaceURI, String localName, String qName, Attributes atts)
This reports the occurrence of an actual element.
void
startEntity(String name)
void
startPrefixMapping(String prefix, String uri)
This will add the prefix mapping to the JDOM Document object.
void
unparsedEntityDecl(String name, String publicID, String systemID, String notationName)
Handler for unparsed entity declarations in the DTD

Field Details

atRoot

protected boolean atRoot
Indicator of where in the document we are


availableNamespaces

protected LinkedList availableNamespaces
The namespaces in scope and actually attached to an element


declaredNamespaces

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


inCDATA

protected boolean inCDATA
Indicator of whether we are in a CDATA


inDTD

protected boolean inDTD
Indicator of whether we are in the DocType. Note that the DTD consists of both the internal subset (inside the <!DOCTYPE> 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


stack

protected Stack stack
Element stack


suppress

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

Constructor Details

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.


SAXHandler

public SAXHandler(Document document)
            throws 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.


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

Method Details

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


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


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.


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.


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


endCDATA

public void endCDATA()
            throws SAXException
Report a CDATA section - ignored in SAXBuilder.


endDTD

public void endDTD()
            throws SAXException
This signifies that the reading of the DTD is complete.


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


endEntity

public void endEntity(String name)
            throws SAXException


endPrefixMapping

public void endPrefixMapping(String prefix)
            throws SAXException
This will add the prefix mapping to the JDOM Document object.

Parameters:
prefix - String namespace prefix.


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


flushCharacters

protected void flushCharacters()
            throws SAXException
This will flush any characters from SAX character calls we've been buffering.


getCurrentElement

protected Element getCurrentElement()
            throws SAXException
Returns the being-parsed element.

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


getDocument

public Document getDocument()
Returns the document. Should be called after parsing is complete.

Returns:
Document - Document that was built


getDocumentLocator

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


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)


getFactory

public JDOMFactory getFactory()
Returns the factory used for constructing objects.

Returns:
JDOMFactory - the factory used for constructing objects.

See Also:
SAXHandler(JDOMFactory)


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)


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


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


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


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.


setDocumentLocator

public void setDocumentLocator(Locator locator)

Parameters:
locator - Locator an object that can return the location of any SAX document event.


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.


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


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


startCDATA

public void startCDATA()
            throws SAXException
Report a CDATA section - ignored in SAXBuilder.


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


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


startEntity

public void startEntity(String name)
            throws SAXException


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.


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


Copyright B) 2002 Jason Hunter, Brett McLaughlin. All Rights Reserved.