Package com.microstrategy.utils.xml

Class SAXSupport

  • public abstract class SAXSupport
extends java.lang.Object
    This is a wrapper around the SAX parser that provides the following services:
    • Hides the actual parser implementation
    • Maintains the stack of active ContentHandlers
    • Provide set of static helper methods for dealing with XML content

    This class is not thread-safe.

    Since:
    MicroStrategy Web 7.3.1 or earlier

    • Constructor Summary

      Constructors 
      Constructor Description
      SAXSupport()  

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      static boolean getBoolAttribute​(org.xml.sax.Attributes attrs, java.lang.String name)
      This method returns true if specified attribute is present in attrs collection and has value "1".
      static boolean getBoolAttribute​(org.xml.sax.Attributes attrs, java.lang.String name, boolean defaultVal)
      If specified attribute is present in attrs collection this method will return true if the attribute hase value "1" and false if it has value "0".
      java.lang.Object getContextObject​(java.lang.String key)  
      static javax.xml.parsers.SAXParserFactory getDefaultFactory()
      Returns default SAXParserFactory that is used to create SAXParsers in the getInstance() method.
      static SAXSupport getInstance()
      A factory method that returns new SAXSupport instance.
      static SAXSupport getInstance​(java.util.Set<java.lang.String> allowEntityPath)
      A factory method that returns new SAXSupport instance.
      static SAXSupport getInstance​(javax.xml.parsers.SAXParserFactory factory)
      A factory method that returns new SAXSupport instance.
      static SAXSupport getInstance​(javax.xml.parsers.SAXParserFactory factory, java.util.Set<java.lang.String> allowEntityPath)
      A factory method that returns new SAXSupport instance.
      static int getIntAttribute​(java.lang.String tag, org.xml.sax.Attributes attrs, java.lang.String name)
      This method returns attribute value from the attrs collection converted to the integer.
      static int getIntAttribute​(java.lang.String tag, org.xml.sax.Attributes attrs, java.lang.String name, int defaultVal)
      This method returns attribute value from the attrs collection converted to the integer or defaultVal if the attribute does not exist.
      abstract javax.xml.parsers.SAXParser getParser()
      Returns SAXParser associated with this object.
      static java.lang.String getStrAttribute​(java.lang.String tag, org.xml.sax.Attributes attrs, java.lang.String name)
      This method returns attribute value from the attrs collection.
      static java.lang.String getStrAttribute​(org.xml.sax.Attributes attrs, java.lang.String name, java.lang.String defaultVal)
      This method returns attribute value from the attrs collection or defaultVal if the attribute does not exist.
      abstract org.xml.sax.XMLReader getXMLReader()  
      static void invalidAttrFormat​(java.lang.String tag, java.lang.String name, java.lang.String val)
      Throws SAXSupportException exception with "Invalid attribute value format" message
      static void missingAttribute​(java.lang.String tag, java.lang.String name)
      Throws SAXSupportException exception with "Missing attribute" message
      static javax.xml.parsers.SAXParserFactory newSAXParserFactory()
      Returns SAXParserFactory with doctype disabled by default to avoid XXE attack.
      abstract void parse​(java.io.File xmlFile, org.xml.sax.ContentHandler contHandler)
      Parses XML file using specified content handler
      abstract void parse​(java.io.InputStream inputStream, org.xml.sax.ContentHandler contHandler)
      Parses XML presented by inputStream using specified content handler
      abstract void parse​(java.lang.String xml, org.xml.sax.ContentHandler contHandler)
      Parses XML string using specified content handler
      abstract void parse​(org.xml.sax.InputSource iSrc, org.xml.sax.ContentHandler contHandler)
      Parses XML presented by iSrc using specified content handler
      abstract org.xml.sax.ContentHandler popContentHandler​(java.lang.String uri, java.lang.String local, java.lang.String qName)
      This method shall be called from the content handler's endElelment method to reattach the parent content handler to the xmlReader.
      abstract void pushContentHandler​(AbstractHandler contHandler)
      This method shall be called from the content handler's startElelment method to attach another content handler to the xmlReader.
      abstract void pushContentHandler​(org.xml.sax.ContentHandler contHandler)
      This method shall be called from the content handler's startElelment method to attach another content handler to the xmlReader.
      void putContextObject​(java.lang.String key, java.lang.Object value)  
      static void unexpectedElement​(java.lang.String tag, java.lang.String parent)
      Throws SAXSupportException exception with "Unexpected element" message
      static void unexpectedEndDocument​(java.lang.Object handler)
      Call this method to report unexpected end of document event.
      static void unexpectedEndElement​(java.lang.Object handler)
      Call this method to report unexpected end of element event.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Constructor Detail

      • SAXSupport

        public SAXSupport()

    • Method Detail

      • newSAXParserFactory

        public static javax.xml.parsers.SAXParserFactory newSAXParserFactory()
        Returns SAXParserFactory with doctype disabled by default to avoid XXE attack.
        Returns:
        SAXParserFactory

      • getParser

        public abstract javax.xml.parsers.SAXParser getParser()
        Returns SAXParser associated with this object. Please use getXMLReader() instead of this method as some application servers will create a XMLReader with each SAXParser.getXMLReader() invocation.
        Returns:
        SAXParser associated with this object.

      • getXMLReader

        public abstract org.xml.sax.XMLReader getXMLReader()
        Returns:
        return the underlying XMLReader instance
        Since:
        MicroStrategy Web 9.0.1

      • getContextObject

        public java.lang.Object getContextObject​(java.lang.String key)
        Since:
        MicroStrategy Web 8.0.0

      • putContextObject

        public void putContextObject​(java.lang.String key,
                             java.lang.Object value)
        Since:
        MicroStrategy Web 8.0.0

      • parse

        public abstract void parse​(java.lang.String xml,
                           org.xml.sax.ContentHandler contHandler)
                    throws org.xml.sax.SAXException
        Parses XML string using specified content handler
        Parameters:
        xml - XML string
        contHandler - a content handler
        Throws:
        org.xml.sax.SAXException - if something is wrong with the input xml

      • parse

        public abstract void parse​(java.io.File xmlFile,
                           org.xml.sax.ContentHandler contHandler)
                    throws org.xml.sax.SAXException,
                           java.io.IOException
        Parses XML file using specified content handler
        Parameters:
        xmlFile - XML file
        contHandler - a content handler
        Throws:
        org.xml.sax.SAXException - if something is wrong with the input xml
        java.io.IOException - if there are problems with input file

      • parse

        public abstract void parse​(java.io.InputStream inputStream,
                           org.xml.sax.ContentHandler contHandler)
                    throws org.xml.sax.SAXException,
                           java.io.IOException
        Parses XML presented by inputStream using specified content handler
        Parameters:
        inputStream - Input Stream presenting XML document
        contHandler - a content handler
        Throws:
        org.xml.sax.SAXException - if something is wrong with the input xml
        java.io.IOException - if there are problems with input source

      • parse

        public abstract void parse​(org.xml.sax.InputSource iSrc,
                           org.xml.sax.ContentHandler contHandler)
                    throws org.xml.sax.SAXException,
                           java.io.IOException
        Parses XML presented by iSrc using specified content handler
        Parameters:
        iSrc - input source presenting XML document
        contHandler - a content handler
        Throws:
        org.xml.sax.SAXException - if something is wrong with the input xml
        java.io.IOException - if there are problems with input source

      • pushContentHandler

        public abstract void pushContentHandler​(AbstractHandler contHandler)
        This method shall be called from the content handler's startElelment method to attach another content handler to the xmlReader. It detaches the current content handler from the xmlReader and pushes it into the stack, then attaches the to the xmlReader. It also sets contHandler.parser attribute to this.
        Parameters:
        contHandler - a new content handler

      • pushContentHandler

        public abstract void pushContentHandler​(org.xml.sax.ContentHandler contHandler)
        This method shall be called from the content handler's startElelment method to attach another content handler to the xmlReader. It detaches the current content handler from the xmlReader and pushes it into the stack, then attaches the to the xmlReader.
        Parameters:
        contHandler - a new content handler
        Throws:
        java.lang.IllegalStateException - if this method is called before the parse method was called.

      • popContentHandler

        public abstract org.xml.sax.ContentHandler popContentHandler​(java.lang.String uri,
                                                             java.lang.String local,
                                                             java.lang.String qName)
                                                      throws org.xml.sax.SAXException,
                                                             java.lang.IllegalStateException
        This method shall be called from the content handler's endElelment method to reattach the parent content handler to the xmlReader. Detaches the current content handler from the xmlReader. Pop's from the stack a "parent" content handler, and attaches it to the xmlReader.

        The endElement method is called on the new content handler before attaching it to the xmlReader. It is done to allow it to adjust it's level count properly and to do other actions, if any.

        Parameters:
        uri - The Namespace URI, or the empty string if the element has no Namespace URI or if Namespace processing is not being performed.
        local - The local name (without prefix), or the empty string if Namespace processing is not being performed.
        qName - The qualified name (with prefix), or the empty string if qualified names are not available.
        Returns:
        an old content handler
        Throws:
        java.lang.IllegalStateException - if the handler stack is empty
        org.xml.sax.SAXException - can be thrown from the endElement method

      • getInstance

        public static SAXSupport getInstance()
                              throws org.xml.sax.SAXException,
                                     XMLSupportRuntimeException
        A factory method that returns new SAXSupport instance. The default factory will be used to create the SAXParser associated with the instance.
        Returns:
        new SAXSupport instance.
        Throws:
        XMLSupportRuntimeException - if a parser cannot be created which satisfies the requested configuration.
        org.xml.sax.SAXException - If error occurs during create the parser or the xml reader.

      • getInstance

        public static SAXSupport getInstance​(java.util.Set<java.lang.String> allowEntityPath)
                              throws org.xml.sax.SAXException,
                                     XMLSupportRuntimeException
        A factory method that returns new SAXSupport instance. The default factory will be used to create the SAXParser associated with the instance.
        Parameters:
        allowEntityPath - a set that includes the paths which are allowed to be used in external entities.
        Returns:
        new SAXSupport instance.
        Throws:
        XMLSupportRuntimeException - if a parser cannot be created which satisfies the requested configuration.
        org.xml.sax.SAXException - If error occurs during create the parser or the xml reader.

      • getInstance

        public static SAXSupport getInstance​(javax.xml.parsers.SAXParserFactory factory)
                              throws org.xml.sax.SAXException,
                                     XMLSupportRuntimeException
        A factory method that returns new SAXSupport instance.
        Parameters:
        factory - a factory that shall be used to create SAXParser associated with the instance.
        Returns:
        new SAXSupport instance.
        Throws:
        XMLSupportRuntimeException - if a parser cannot be created which satisfies the requested configuration.
        org.xml.sax.SAXException - If error occurs during create the parser or the xml reader.

      • getInstance

        public static SAXSupport getInstance​(javax.xml.parsers.SAXParserFactory factory,
                                     java.util.Set<java.lang.String> allowEntityPath)
                              throws org.xml.sax.SAXException,
                                     XMLSupportRuntimeException
        A factory method that returns new SAXSupport instance.
        Parameters:
        factory - a factory that shall be used to create SAXParser associated with the instance.
        allowEntityPath - a set that includes the paths which are allowed to be used in external entities.
        Returns:
        new SAXSupport instance.
        Throws:
        XMLSupportRuntimeException - if a parser cannot be created which satisfies the requested configuration.
        org.xml.sax.SAXException - If error occurs during create the parser or the xml reader.

      • getDefaultFactory

        public static javax.xml.parsers.SAXParserFactory getDefaultFactory()
        Returns default SAXParserFactory that is used to create SAXParsers in the getInstance() method.
        Returns:
        default SAXParserFactory

      • unexpectedEndDocument

        public static void unexpectedEndDocument​(java.lang.Object handler)
                                  throws java.lang.IllegalStateException
        Call this method to report unexpected end of document event. Normally it shall be used in the endDocument methods of inner event handlers.
        Parameters:
        handler - the handler that detected the error
        Throws:
        java.lang.IllegalStateException - If the handler does not support endDocument() method.

      • unexpectedEndElement

        public static void unexpectedEndElement​(java.lang.Object handler)
                                 throws java.lang.IllegalStateException
        Call this method to report unexpected end of element event. Normally it shall be called from the endElement methods if the level count goes below zero.
        Parameters:
        handler - the handler that detected the error
        Throws:
        java.lang.IllegalStateException - If the handler does not support endElement() method.

      • getStrAttribute

        public static java.lang.String getStrAttribute​(java.lang.String tag,
                                               org.xml.sax.Attributes attrs,
                                               java.lang.String name)
                                        throws SAXSupportException
        This method returns attribute value from the attrs collection. It will throw WebSAXException if the attribute does not exist. Use this method for mandatory attributes.
        Parameters:
        tag - element's tag name. Used in the diagnostic message.
        attrs - attribute collection
        name - attribute name
        Returns:
        attribute value
        Throws:
        SAXSupportException - if attribute does not exists in the collection

      • getStrAttribute

        public static java.lang.String getStrAttribute​(org.xml.sax.Attributes attrs,
                                               java.lang.String name,
                                               java.lang.String defaultVal)
        This method returns attribute value from the attrs collection or defaultVal if the attribute does not exist. Use this method for optional attributes.
        Parameters:
        attrs - attribute collection
        name - attribute name
        defaultVal - default value to be used if the attribute does not exist
        Returns:
        attribute value

      • getIntAttribute

        public static int getIntAttribute​(java.lang.String tag,
                                  org.xml.sax.Attributes attrs,
                                  java.lang.String name)
                           throws SAXSupportException
        This method returns attribute value from the attrs collection converted to the integer. It will throw SAXSupportException if the attribute does not exist. Use this method for mandatory attributes.
        Parameters:
        tag - element's tag name. Used in the diagnostic message.
        attrs - attribute collection
        name - attribute name
        Returns:
        attribute value
        Throws:
        SAXSupportException - if attribute does not exists in the collection or if its value is not an integer

      • getIntAttribute

        public static int getIntAttribute​(java.lang.String tag,
                                  org.xml.sax.Attributes attrs,
                                  java.lang.String name,
                                  int defaultVal)
                           throws SAXSupportException
        This method returns attribute value from the attrs collection converted to the integer or defaultVal if the attribute does not exist. Use this method for optional attributes.
        Parameters:
        tag - element's tag name. Used in the diagnostic message.
        attrs - attribute collection
        name - attribute name
        defaultVal - default value to be used if the attribute does not exist
        Returns:
        attribute value
        Throws:
        SAXSupportException - if attribute value is not an integer

      • getBoolAttribute

        public static boolean getBoolAttribute​(org.xml.sax.Attributes attrs,
                                       java.lang.String name)
                                throws SAXSupportException
        This method returns true if specified attribute is present in attrs collection and has value "1". It returns false if the attribute is absent or if it has value "0". It will throw SAXSupportException in any other case.

        Use this method for boolean attributes that can be present with both "1" and "0" values

        Parameters:
        attrs - attribute collection
        name - attribute name
        Returns:
        true or false.
        Throws:
        SAXSupportException - if attribute value is not "0" or "1"

      • getBoolAttribute

        public static boolean getBoolAttribute​(org.xml.sax.Attributes attrs,
                                       java.lang.String name,
                                       boolean defaultVal)
                                throws SAXSupportException
        If specified attribute is present in attrs collection this method will return true if the attribute hase value "1" and false if it has value "0". If the attribute is absent then the method will return defaultVal.
        Parameters:
        attrs - attribute collection
        name - attribute name
        defaultVal - a default value
        Returns:
        true or false.
        Throws:
        SAXSupportException - if attribute value is not "0" or "1"

      • missingAttribute

        public static void missingAttribute​(java.lang.String tag,
                                    java.lang.String name)
                             throws SAXSupportException
        Throws SAXSupportException exception with "Missing attribute" message
        Parameters:
        tag - tag name
        name - attribute name
        Throws:
        SAXSupportException - exception with "Missing attribute" message.

      • invalidAttrFormat

        public static void invalidAttrFormat​(java.lang.String tag,
                                     java.lang.String name,
                                     java.lang.String val)
                              throws SAXSupportException
        Throws SAXSupportException exception with "Invalid attribute value format" message
        Parameters:
        tag - tag name
        name - attribute name
        val - value
        Throws:
        SAXSupportException - exception with "Invalid attribute value format" message

      • unexpectedElement

        public static void unexpectedElement​(java.lang.String tag,
                                     java.lang.String parent)
                              throws SAXSupportException
        Throws SAXSupportException exception with "Unexpected element" message
        Parameters:
        tag - tag name
        parent - parent tag name
        Throws:
        SAXSupportException - exception with "Unexpected element" message