Class 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 for SAXBuilder 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 to SAXBuilder

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

      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 section
      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 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 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 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 DTD
      void 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 section
      void 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 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, endPrefixMapping, error, fatalError, resolveEntity, warning
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • 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

      • 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
      • 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
      • setIgnoringBoundaryWhitespace

        public void setIgnoringBoundaryWhitespace​(boolean ignoringBoundaryWhite)
        Specifies whether or not the parser should eliminate text() nodes containing only whitespace when building the document. See SAXBuilder.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 interface org.xml.sax.ContentHandler
        Overrides:
        startDocument in class org.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 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)
        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)
        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)
        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.)
        Specified by:
        processingInstruction in interface org.xml.sax.ContentHandler
        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.
        Specified by:
        skippedEntity in interface org.xml.sax.ContentHandler
        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.
        Specified by:
        startPrefixMapping in interface org.xml.sax.ContentHandler
        Overrides:
        startPrefixMapping in class org.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 as xmlns:[namespace prefix] and xsi:schemaLocation.
        Specified by:
        startElement in interface org.xml.sax.ContentHandler
        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).
        Specified by:
        characters in interface org.xml.sax.ContentHandler
        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.
        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 interface org.xml.sax.ContentHandler
        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
      • 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 interface org.xml.sax.ContentHandler
        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
        Throws:
        org.xml.sax.SAXException
      • endDTD

        public void endDTD()
        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
        Throws:
        org.xml.sax.SAXException
      • endEntity

        public void endEntity​(java.lang.String name)
                       throws org.xml.sax.SAXException
        Specified by:
        endEntity in interface org.xml.sax.ext.LexicalHandler
        Throws:
        org.xml.sax.SAXException
      • startCDATA

        public void startCDATA()
        Report a CDATA section
        Specified by:
        startCDATA in interface org.xml.sax.ext.LexicalHandler
      • endCDATA

        public void endCDATA()
                      throws org.xml.sax.SAXException
        Report a CDATA section
        Specified by:
        endCDATA in interface org.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 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.
        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 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
        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 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
      • 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 the getDocumentLocator() method to get access to the Locator during parse.

        Specified by:
        setDocumentLocator in interface org.xml.sax.ContentHandler
        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.