Package org.zkoss.idom.input

Class SAXBuilder

  • public class SAXBuilder
extends java.lang.Object
    The builder based on SAX parsers.

    A new instance of SAXHandler is created and configured each time one of the build methods is called.

    Author:
    tomyeh
    See Also:
    SAXHandler

    • Constructor Summary

      Constructors 
      Constructor Description
      SAXBuilder​(boolean nsaware, boolean validate)
      Constructor that creates the parser on-the-fly.
      SAXBuilder​(boolean nsaware, boolean validate, boolean smartIgnore)
      Constructor that creates the parser on-the-fly, that accepts an additional option, smartIgnore.
      SAXBuilder​(javax.xml.parsers.SAXParser parser)
      Constructor which reuses a parser.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      Document build​(java.io.File src)
      Build an iDOM tree from a file.
      Document build​(java.io.InputStream src)
      Build an iDOM tree from a input stream.
      Document build​(java.io.Reader src)
      Build an iDOM tree from a Reader.
      Document build​(java.lang.String uri)
      Build an iDOM tree from a URI string.
      Document build​(java.net.URL url)
      Build an iDOM tree from a URL.
      Document build​(org.xml.sax.InputSource src)
      Build an iDOM tree from a input source.
      org.xml.sax.EntityResolver getEntityResolver()
      Gets the org.xml.sax.EntityResolver.
      org.xml.sax.ErrorHandler getErrorHandler()
      Gets the org.xml.sax.ErrorHandler.
      IDOMFactory getIDOMFactory()
      Gets the iDOM factory.
      javax.xml.parsers.SAXParser getParser()
      Gets the SAX parser.
      boolean isCoalescing()
      Indicates whether or not the factory is configured to produce parsers which converts CDATA to Text and appends it to the adjacent (if any) Text node.
      boolean isExpandEntityReferences()
      Tests whether to expand entity reference nodes.
      boolean isIgnoringComments()
      Indicates whether or not the factory is configured to produce parsers which ignores comments.
      boolean isIgnoringElementContentWhitespace()
      Tests whether to ignore whitespaces in element content.
      boolean isNamespaceAware()
      Tests whether or not this parser is configured to understand namespaces.
      boolean isValidating()
      Tests whether or not this parser is configured to validate XML documents.
      protected SAXHandler newHandler()
      Creates a SAX Handler.
      void setCoalescing​(boolean coalescing)
      Specifies that the parser produced by this code will convert CDATA to Text and append it to the adjacent (if any) text.
      void setEntityResolver​(org.xml.sax.EntityResolver er)
      Specifies the org.xml.sax.EntityResolver to be used to resolve entities present in the XML document to be parsed.
      void setErrorHandler​(org.xml.sax.ErrorHandler eh)
      Specifies the org.xml.sax.ErrorHandler to be used to report errors present in the XML document to be parsed.
      void setExpandEntityReferences​(boolean expand)
      Sets whether to expand entities during parsing.
      void setIDOMFactory​(IDOMFactory factory)
      Sets the iDOM factory.
      void setIgnoringComments​(boolean ignoreComments)
      Specifies that the parser produced by this code will ignore comments.
      void setIgnoringElementContentWhitespace​(boolean ignore)
      Sets whether the parser should eliminate whitespace in element content.

      • Methods inherited from class java.lang.Object

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

    • Constructor Detail

      • SAXBuilder

        public SAXBuilder​(javax.xml.parsers.SAXParser parser)
        Constructor which reuses a parser.

      • SAXBuilder

        public SAXBuilder​(boolean nsaware,
                  boolean validate)
           throws javax.xml.parsers.ParserConfigurationException,
                  org.xml.sax.SAXException
        Constructor that creates the parser on-the-fly.
        Parameters:
        nsaware - whether the parser is namespace aware
        validate - whether the parser shall validate the document
        Throws:
        javax.xml.parsers.ParserConfigurationException - if a parser cannot be created which satisfies the requested configuration.
        org.xml.sax.SAXException
        See Also:
        SAXBuilder(boolean, boolean, boolean)

      • SAXBuilder

        public SAXBuilder​(boolean nsaware,
                  boolean validate,
                  boolean smartIgnore)
           throws javax.xml.parsers.ParserConfigurationException,
                  org.xml.sax.SAXException
        Constructor that creates the parser on-the-fly, that accepts an additional option, smartIgnore.

        When parsing XML for input purpose only, it is better to use this constructor with smartIgnore true, and then comments will be ignored CDATA will be coalesced with TEXT. A smaller DOM tree is formed.

        Parameters:
        nsaware - whether the parser is namespace aware
        validate - whether the parser shall validate the document
        smartIgnore - whether to ignore comments and ignorable-whitespace (if validate is true), and to coalesce
        Throws:
        javax.xml.parsers.ParserConfigurationException - if a parser cannot be created which satisfies the requested configuration.
        org.xml.sax.SAXException

    • Method Detail

      • isIgnoringElementContentWhitespace

        public final boolean isIgnoringElementContentWhitespace()
        Tests whether to ignore whitespaces in element content.

      • setIgnoringElementContentWhitespace

        public final void setIgnoringElementContentWhitespace​(boolean ignore)
        Sets whether the parser should eliminate whitespace in element content. They are known as "ignorable whitespace". Only whitespace which is contained within element content that has an element only content model will be eliminated (see XML Rec 2.10).

        For this setting to take effect requires that validation be turned on.

        Default: false.

        Parameters:
        ignore - Whether to ignore whitespaces in element content.

      • isExpandEntityReferences

        public final boolean isExpandEntityReferences()
        Tests whether to expand entity reference nodes.

      • setExpandEntityReferences

        public final void setExpandEntityReferences​(boolean expand)
        Sets whether to expand entities during parsing. A true means to expand entities as normal content. A false means to leave entities unexpanded as EntityReference objects.

        Default: true.

        Parameters:
        expand - whether entity expansion should occur.

      • isCoalescing

        public final boolean isCoalescing()
        Indicates whether or not the factory is configured to produce parsers which converts CDATA to Text and appends it to the adjacent (if any) Text node.

        Default: false.

        Returns:
        true if the factory is configured to produce parsers which converts CDATA nodes to Text nodes and appends it to the adjacent (if any) Text node; false otherwise.

      • setCoalescing

        public final void setCoalescing​(boolean coalescing)
        Specifies that the parser produced by this code will convert CDATA to Text and append it to the adjacent (if any) text.

        Default: false.

      • isIgnoringComments

        public final boolean isIgnoringComments()
        Indicates whether or not the factory is configured to produce parsers which ignores comments.

        Default: false.

        Returns:
        true if the factory is configured to produce parsers which ignores comments; false otherwise.

      • setIgnoringComments

        public final void setIgnoringComments​(boolean ignoreComments)
        Specifies that the parser produced by this code will ignore comments.

        Default: false.

      • setErrorHandler

        public final void setErrorHandler​(org.xml.sax.ErrorHandler eh)
        Specifies the org.xml.sax.ErrorHandler to be used to report errors present in the XML document to be parsed.

        Default: null -- to use the default implementation and behavior.

      • getErrorHandler

        public final org.xml.sax.ErrorHandler getErrorHandler()
        Gets the org.xml.sax.ErrorHandler.
        Returns:
        the error handler; null to use the default implementation

      • setEntityResolver

        public final void setEntityResolver​(org.xml.sax.EntityResolver er)
        Specifies the org.xml.sax.EntityResolver to be used to resolve entities present in the XML document to be parsed.

        Default: null -- to use the default implementation and behavior.

      • getEntityResolver

        public final org.xml.sax.EntityResolver getEntityResolver()
        Gets the org.xml.sax.EntityResolver.
        Returns:
        the entity resolver; null to use the default implementation

      • isNamespaceAware

        public final boolean isNamespaceAware()
        Tests whether or not this parser is configured to understand namespaces.

      • isValidating

        public final boolean isValidating()
        Tests whether or not this parser is configured to validate XML documents.

      • getIDOMFactory

        public final IDOMFactory getIDOMFactory()
        Gets the iDOM factory. Null for DefaultIDOMFactory.THE.

      • setIDOMFactory

        public final void setIDOMFactory​(IDOMFactory factory)
        Sets the iDOM factory. Null for DefaultIDOMFactory.THE.

      • getParser

        public final javax.xml.parsers.SAXParser getParser()
        Gets the SAX parser.

      • build

        public final Document build​(java.io.File src)
                     throws org.xml.sax.SAXException,
                            java.io.IOException
        Build an iDOM tree from a file.
        Throws:
        org.xml.sax.SAXException
        java.io.IOException

      • build

        public final Document build​(java.io.InputStream src)
                     throws org.xml.sax.SAXException,
                            java.io.IOException
        Build an iDOM tree from a input stream.
        Throws:
        org.xml.sax.SAXException
        java.io.IOException

      • build

        public final Document build​(org.xml.sax.InputSource src)
                     throws org.xml.sax.SAXException,
                            java.io.IOException
        Build an iDOM tree from a input source.
        Throws:
        org.xml.sax.SAXException
        java.io.IOException

      • build

        public final Document build​(java.lang.String uri)
                     throws org.xml.sax.SAXException,
                            java.io.IOException
        Build an iDOM tree from a URI string.
        Throws:
        org.xml.sax.SAXException
        java.io.IOException

      • build

        public final Document build​(java.net.URL url)
                     throws org.xml.sax.SAXException,
                            java.io.IOException
        Build an iDOM tree from a URL.
        Throws:
        org.xml.sax.SAXException
        java.io.IOException

      • build

        public final Document build​(java.io.Reader src)
                     throws org.xml.sax.SAXException,
                            java.io.IOException
        Build an iDOM tree from a Reader.
        Throws:
        org.xml.sax.SAXException
        java.io.IOException

      • newHandler

        protected SAXHandler newHandler()
                         throws org.xml.sax.SAXException
        Creates a SAX Handler. Deriving class might override to provide a subclass of SAXHandler.
        Throws:
        org.xml.sax.SAXException