Class SAXHandler
- java.lang.Object
-
- org.xml.sax.helpers.DefaultHandler
-
- org.jdom2.input.sax.SAXHandler
-
- All Implemented Interfaces:
org.xml.sax.ContentHandler
,org.xml.sax.DTDHandler
,org.xml.sax.EntityResolver
,org.xml.sax.ErrorHandler
,org.xml.sax.ext.DeclHandler
,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
A support class forSAXBuilder
which listens for SAX events.People overriding this class are cautioned to ensure that the implementation of the cleanUp() method resets to a virgin state. The cleanUp() method will be called when this SAXHandler is reset(), which may happen multiple times between parses. The cleanUp() method must ensure that there are no references remaining to any external instances.
Overriding of this class is permitted to allow for different handling of SAX events. Once you have created a subclass of this, you also need to create a custom implementation of
SAXHandlerFactory
to supply your instances toSAXBuilder
If the XMLReader producing the SAX Events supports a document Locator, then this instance will use the locator to supply the line and column data from the SAX locator to the JDOMFactory. Note: the SAX specification for the SAX Locator indicates that the line and column represent the position of the end of the SAX Event. For example, the line and column of the simple XML
<root />
would be line 1, column 9.- Author:
- Brett McLaughlin, Jason Hunter, Philip Nelson, Bradley S. Huffman, phil@triloggroup.com, Rolf Lear
- See Also:
org.jdom2.input.sax
-
-
Constructor Summary
Constructors Constructor Description SAXHandler()
This will create a newSAXHandler
that listens to SAX events and creates a JDOM Document.SAXHandler(JDOMFactory factory)
This will create a newSAXHandler
that listens to SAX events and creates a JDOM Document.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description 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 sectionvoid
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
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 void
flushCharacters(java.lang.String data)
Flush the given string into the document.Element
getCurrentElement()
Returns the being-parsed element.Document
getDocument()
Returns the document.org.xml.sax.Locator
getDocumentLocator()
Provides access to theLocator
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
getIgnoringBoundaryWhitespace()
Returns whether or not the parser will elminate element content containing only whitespace.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 DTDvoid
processingInstruction(java.lang.String target, java.lang.String data)
This will indicate that a processing instruction has been encountered.protected void
pushElement(Element element)
Pushes an element onto the tree under construction.void
reset()
Restore this SAXHandler to a clean state ready for another parse round.protected void
resetSubCLass()
Override this method if you are a subclasser, and you want to clear the state of your SAXHandler instance in preparation for a new parse.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
setIgnoringBoundaryWhitespace(boolean ignoringBoundaryWhite)
Specifies whether or not the parser should eliminate text() nodes containing only whitespace when building the document.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 sectionvoid
startDocument()
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 JDOMDocument
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 JDOMDocument
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
-
-
-
Constructor Detail
-
SAXHandler
public SAXHandler()
This will create a newSAXHandler
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 newSAXHandler
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
-
resetSubCLass
protected void resetSubCLass()
Override this method if you are a subclasser, and you want to clear the state of your SAXHandler instance in preparation for a new parse.
-
reset
public final void reset()
Restore this SAXHandler to a clean state ready for another parse round. All internal variables are cleared to an initialized state, and then the resetSubClass() method is called to clear any methods that a subclass may need to have reset.
-
pushElement
protected void pushElement(Element element)
Pushes an element onto the tree under construction. Allows subclasses to put content under a dummy root element which is useful for building content that would otherwise be a non-well formed document.- Parameters:
element
- root element under which content will be built
-
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.jdom2.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 asEntityRef
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 isfalse
.- Parameters:
ignoringWhite
- Whether to ignore ignorable whitespace
-
setIgnoringBoundaryWhitespace
public void setIgnoringBoundaryWhitespace(boolean ignoringBoundaryWhite)
Specifies whether or not the parser should eliminate text() nodes containing only whitespace when building the document. SeeSAXBuilder.setIgnoringBoundaryWhitespace(boolean)
.- Parameters:
ignoringBoundaryWhite
- Whether to ignore only whitespace content
-
getIgnoringBoundaryWhitespace
public boolean getIgnoringBoundaryWhitespace()
Returns whether or not the parser will elminate element content containing only whitespace.- Returns:
boolean
- whether only whitespace content will be ignored during build.- See Also:
setIgnoringBoundaryWhitespace(boolean)
-
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)
-
startDocument
public void startDocument()
- Specified by:
startDocument
in interfaceorg.xml.sax.ContentHandler
- Overrides:
startDocument
in classorg.xml.sax.helpers.DefaultHandler
-
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 interfaceorg.xml.sax.ext.DeclHandler
- Parameters:
name
- entity namepublicID
- public idsystemID
- 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)
This handles an attribute declaration in the internal subset.- Specified by:
attributeDecl
in interfaceorg.xml.sax.ext.DeclHandler
- Parameters:
eName
-String
element name of attributeaName
-String
attribute nametype
-String
attribute typevalueDefault
-String
default value of attributevalue
-String
value of attribute
-
elementDecl
public void elementDecl(java.lang.String name, java.lang.String model)
Handle an element declaration in a DTD.- Specified by:
elementDecl
in interfaceorg.xml.sax.ext.DeclHandler
- Parameters:
name
-String
name of elementmodel
-String
model of the element in DTD syntax
-
internalEntityDecl
public void internalEntityDecl(java.lang.String name, java.lang.String value)
Handle an internal entity declaration in a DTD.- Specified by:
internalEntityDecl
in interfaceorg.xml.sax.ext.DeclHandler
- Parameters:
name
-String
name of entityvalue
-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.)- Specified by:
processingInstruction
in interfaceorg.xml.sax.ContentHandler
- Overrides:
processingInstruction
in classorg.xml.sax.helpers.DefaultHandler
- Parameters:
target
-String
target of PIdata
-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.- Specified by:
skippedEntity
in interfaceorg.xml.sax.ContentHandler
- Overrides:
skippedEntity
in classorg.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 JDOMDocument
object.- Specified by:
startPrefixMapping
in interfaceorg.xml.sax.ContentHandler
- Overrides:
startPrefixMapping
in classorg.xml.sax.helpers.DefaultHandler
- Parameters:
prefix
-String
namespace prefix.uri
-String
namespace URI.- Throws:
org.xml.sax.SAXException
-
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 asxmlns:[namespace prefix]
andxsi:schemaLocation
.- Specified by:
startElement
in interfaceorg.xml.sax.ContentHandler
- Overrides:
startElement
in classorg.xml.sax.helpers.DefaultHandler
- Parameters:
namespaceURI
-String
namespace URI this element is associated with, or an emptyString
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).- Specified by:
characters
in interfaceorg.xml.sax.ContentHandler
- Overrides:
characters
in classorg.xml.sax.helpers.DefaultHandler
- Parameters:
ch
-char[]
character array with character datastart
-int
index in array where data starts.length
-int
length of data.- Throws:
org.xml.sax.SAXException
-
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.- Specified by:
ignorableWhitespace
in interfaceorg.xml.sax.ContentHandler
- Overrides:
ignorableWhitespace
in classorg.xml.sax.helpers.DefaultHandler
- Parameters:
ch
-[]
- char array of ignorable whitespacestart
-int
- starting position within arraylength
-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
-
flushCharacters
protected void flushCharacters(java.lang.String data) throws org.xml.sax.SAXException
Flush the given string into the document. This is a protected method so subclassers can control text handling without knowledge of the internals of this class.- Parameters:
data
- string to flush- Throws:
org.xml.sax.SAXException
- if the state of the handler does not allow this.
-
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.- Specified by:
endElement
in interfaceorg.xml.sax.ContentHandler
- Overrides:
endElement
in classorg.xml.sax.helpers.DefaultHandler
- Parameters:
namespaceURI
-String
URI of namespace this element is associated withlocalName
-String
name of element without prefixqName
-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 JDOMDocument
object.- Specified by:
startDTD
in interfaceorg.xml.sax.ext.LexicalHandler
- Parameters:
name
-String
name of element listed in DTDpublicID
-String
public ID of DTDsystemID
-String
system ID of DTD- Throws:
org.xml.sax.SAXException
-
endDTD
public void endDTD()
This signifies that the reading of the DTD is complete.- Specified by:
endDTD
in interfaceorg.xml.sax.ext.LexicalHandler
-
startEntity
public void startEntity(java.lang.String name) throws org.xml.sax.SAXException
- Specified by:
startEntity
in interfaceorg.xml.sax.ext.LexicalHandler
- Throws:
org.xml.sax.SAXException
-
endEntity
public void endEntity(java.lang.String name) throws org.xml.sax.SAXException
- Specified by:
endEntity
in interfaceorg.xml.sax.ext.LexicalHandler
- Throws:
org.xml.sax.SAXException
-
startCDATA
public void startCDATA()
Report a CDATA section- Specified by:
startCDATA
in interfaceorg.xml.sax.ext.LexicalHandler
-
endCDATA
public void endCDATA() throws org.xml.sax.SAXException
Report a CDATA section- Specified by:
endCDATA
in interfaceorg.xml.sax.ext.LexicalHandler
- Throws:
org.xml.sax.SAXException
-
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 JDOMElement
, or theDocument
itself if at that level.- Specified by:
comment
in interfaceorg.xml.sax.ext.LexicalHandler
- Parameters:
ch
-ch[]
array of comment characters.start
-int
index to start reading from.length
-int
length of data.- Throws:
org.xml.sax.SAXException
- if the state of the handler disallows this call
-
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 interfaceorg.xml.sax.DTDHandler
- Overrides:
notationDecl
in classorg.xml.sax.helpers.DefaultHandler
- Parameters:
name
- name of the notationpublicID
- the public ID of the notationsystemID
- the system ID of the notation- Throws:
org.xml.sax.SAXException
-
unparsedEntityDecl
public 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- Specified by:
unparsedEntityDecl
in interfaceorg.xml.sax.DTDHandler
- Overrides:
unparsedEntityDecl
in classorg.xml.sax.helpers.DefaultHandler
- Parameters:
name
-String
of the unparsed entity declpublicID
-String
of the unparsed entity declsystemID
-String
of the unparsed entity declnotationName
-String
of the unparsed entity decl
-
getCurrentElement
public Element getCurrentElement() throws org.xml.sax.SAXException
Returns the being-parsed element.- Returns:
Element
- element being built.- Throws:
org.xml.sax.SAXException
- if the state of the handler disallows this call
-
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 thegetDocumentLocator()
method to get access to theLocator
during parse.- Specified by:
setDocumentLocator
in interfaceorg.xml.sax.ContentHandler
- Overrides:
setDocumentLocator
in classorg.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 theLocator
object provided by the SAX parser.- Returns:
Locator
an object that can return the location of any SAX document event.
-
-