org.jdom.input
Class SAXHandler

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

public class SAXHandler
extends DefaultHandler
implements LexicalHandler, DeclHandler

SAXHandler supports SAXBuilder

Author:
Brett McLaughlin, Jason Hunter

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
 void attributeDecl(String eName, String aName, String type, String valueDefault, String value)
           
 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)
           
 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.
 Document getDocument()
           Returns the document.
 void ignorableWhitespace(char[] ch, int start, int length)
           Capture ignorable whitespace as text.
 void internalEntityDecl(String name, String value)
           
 void processingInstruction(String target, String data)
           This will indicate that a processing instruction (other than the XML declaration) has been encountered.
 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 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.
 
Methods inherited from class org.xml.sax.helpers.DefaultHandler
endDocument, error, fatalError, notationDecl, resolveEntity, setDocumentLocator, skippedEntity, startDocument, unparsedEntityDecl, warning
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

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

getDocument

public Document getDocument()

Returns the document. Should be called after parsing is complete.

Returns:
Document - Document that was built

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

externalEntityDecl

public void externalEntityDecl(String name,
                               String publicId,
                               String systemId)
                        throws SAXException
This is called when the parser encounters an external entity declaration.

Specified by:
externalEntityDecl in interface DeclHandler
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)
Specified by:
attributeDecl in interface DeclHandler

elementDecl

public void elementDecl(String name,
                        String model)
Specified by:
elementDecl in interface DeclHandler

internalEntityDecl

public void internalEntityDecl(String name,
                               String value)
Specified by:
internalEntityDecl in interface DeclHandler

processingInstruction

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

This will indicate that a processing instruction (other than the XML declaration) has been encountered.

Overrides:
processingInstruction in class DefaultHandler
Parameters:
target - String target of PI
data - StringThrows:
SAXException - when things go wrong

startPrefixMapping

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

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

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

endPrefixMapping

public void endPrefixMapping(String prefix)
                      throws SAXException

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

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

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.

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

characters

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

This will report character data (within an element).

Overrides:
characters in class DefaultHandler
Parameters:
ch - char[] character array with character data
start - int index in array where data starts.
length - int length of data.
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.

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

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.

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

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.

Specified by:
startDTD in interface LexicalHandler
Parameters:
name - String name of element listed in DTD
publicId - String public ID of DTD
systemId - String syste ID of DTD

endDTD

public void endDTD()
            throws SAXException

This signifies that the reading of the DTD is complete.

Specified by:
endDTD in interface LexicalHandler

startEntity

public void startEntity(String name)
                 throws SAXException
Specified by:
startEntity in interface LexicalHandler

endEntity

public void endEntity(String name)
               throws SAXException
Specified by:
endEntity in interface LexicalHandler

startCDATA

public void startCDATA()
                throws SAXException

Report a CDATA section - ignored in SAXBuilder.

Specified by:
startCDATA in interface LexicalHandler

endCDATA

public void endCDATA()
              throws SAXException

Report a CDATA section - ignored in SAXBuilder.

Specified by:
endCDATA in interface LexicalHandler

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.

Specified by:
comment in interface LexicalHandler
Parameters:
ch - ch[] array of comment characters.
start - int index to start reading from.
length - int length of data.


Copyright © 2001 Jason Hunter, Brett McLaughlin. All Rights Reserved.