Package org.zkoss.idom.input

## Class SAXBuilder

- java.lang.Object
- - org.zkoss.idom.input.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`