org.jdom.input

Class 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

Field Summary
protected booleanatRoot
Indicator of where in the document we are
protected LinkedListavailableNamespaces
The namespaces in scope and actually attached to an element
protected LinkedListdeclaredNamespaces
Temporary holder for namespaces that have been declared with startPrefixMapping, but are not yet available on the element
protected booleaninCDATA
Indicator of whether we are in a CDATA
protected booleaninDTD
Indicator of whether we are in the DocType.
protected booleaninInternalSubset
Indicator of whether we are in the internal subset
protected booleanpreviousCDATA
Indicator of whether we previously where in a CDATA
protected Stackstack
Element stack
protected booleansuppress
Indicator of whether we are actively suppressing (non-expanding) a current entity
Constructor Summary
SAXHandler(Document document)

This will set the Document to use.

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 voidappendExternalId(String publicID, String systemID)

Appends an external ID to the internal subset buffer.

voidattributeDecl(String eName, String aName, String type, String valueDefault, String value)

This handles an attribute declaration in the internal subset

voidcharacters(char[] ch, int start, int length)

This will report character data (within an element).

voidcomment(char[] ch, int start, int length)

This reports that a comments is parsed.

voidelementDecl(String name, String model)

Handle an element declaration in a DTD

voidendCDATA()

Report a CDATA section - ignored in SAXBuilder.

voidendDTD()

This signifies that the reading of the DTD is complete.

voidendElement(String namespaceURI, String localName, String qName)

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

voidendEntity(String name)
if stack is empty, this entity belongs to an attribute in these cases, it is an error on the part of the parser to call startEntity but this will help in some cases.
voidendPrefixMapping(String prefix)

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

voidexternalEntityDecl(String name, String publicID, String systemID)
This is called when the parser encounters an external entity declaration.
protected voidflushCharacters()

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

protected ElementgetCurrentElement()

Returns the being-parsed element.

DocumentgetDocument()

Returns the document.

LocatorgetDocumentLocator()

Provides access to the Locator object provided by the SAX parser.

booleangetExpandEntities()

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

JDOMFactorygetFactory()

Returns the factory used for constructing objects.

booleangetIgnoringElementContentWhitespace()

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

voidignorableWhitespace(char[] ch, int start, int length)

Capture ignorable whitespace as text.

voidinternalEntityDecl(String name, String value)

Handle an internal entity declaration in a DTD.

voidnotationDecl(String name, String publicID, String systemID)

Handle the declaration of a Notation in a DTD

voidprocessingInstruction(String target, String data)

This will indicate that a processing instruction has been encountered.

voidsetDocumentLocator(Locator locator)

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

voidsetExpandEntities(boolean expand)

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

voidsetIgnoringElementContentWhitespace(boolean ignoringWhite)

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

voidskippedEntity(String name)

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

voidstartCDATA()

Report a CDATA section - ignored in SAXBuilder.

voidstartDTD(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.

voidstartElement(String namespaceURI, String localName, String qName, Attributes atts)

This reports the occurrence of an actual element.

voidstartEntity(String name)
voidstartPrefixMapping(String prefix, String uri)

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

voidunparsedEntityDecl(String name, String publicID, String systemID, String notationName)

Handler for unparsed entity declarations in the DTD

Field Detail

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

SAXHandler

public SAXHandler(Document document)

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

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)

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.

Method Detail

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)

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)

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)

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)

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

Report a CDATA section - ignored in SAXBuilder.

endDTD

public void endDTD()

This signifies that the reading of the DTD is complete.

endElement

public void endElement(String namespaceURI, String localName, String qName)

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

endEntity

public void endEntity(String name)
if stack is empty, this entity belongs to an attribute in these cases, it is an error on the part of the parser to call startEntity but this will help in some cases. See org/xml/sax/ext/LexicalHandler.html#startEntity(java.lang.String) for more information

endPrefixMapping

public void endPrefixMapping(String prefix)

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

Parameters: prefix String namespace prefix. uri String namespace URI.

externalEntityDecl

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

flushCharacters

protected void flushCharacters()

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

Throws: SAXException when things go wrong

getCurrentElement

protected Element getCurrentElement()

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: SAXHandler

getFactory

public JDOMFactory getFactory()

Returns the factory used for constructing objects.

Returns: JDOMFactory - the factory used for constructing objects.

See Also: SAXHandler

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: SAXHandler

ignorableWhitespace

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

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

internalEntityDecl

public void internalEntityDecl(String name, String value)

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)

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)

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

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.

JDOMFactory implementations can use the SAXHandler method to get access to the Locator during parse.

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)

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

startCDATA

public void startCDATA()

Report a CDATA section - ignored in SAXBuilder.

startDTD

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

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)

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

startEntity

public void startEntity(String name)

startPrefixMapping

public void startPrefixMapping(String prefix, String uri)

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)

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.