Package org.zkoss.idom.input

## Class SAXHandler

- java.lang.Object
- - org.xml.sax.helpers.DefaultHandler
  - - org.zkoss.idom.input.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

  The SAX Handler. It implements ContentHandler, LexicalHandler and DeclHandler. It is the caller's job to set up this handler properly if required.

  This class doesn't depend on SAXBuilder, so it can be used in any other place, e.g., javax.xml.transform.sax.SAXResult.

  Author:
    tomyeh
  See Also:
    `SAXBuilder`

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected java.util.List<Namespace>` | `_declNamespaces` | The namespaces in between startPrefixMapping and endPrefixMapping.
    `protected Document` | `_doc` | The Document being created.
    `protected IDOMFactory` | `_factory` | The iDOM factory.
    `protected boolean` | `_inCData` | Indicator of whether we are in a CDATA.
    `protected boolean` | `_inDTD` | Indicator of whether we are in a DTD.
    `protected org.xml.sax.Locator` | `_loc` | Locator.
    `protected java.util.Stack<Group>` | `_stack` | The Group stack.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `SAXHandler()` | Constructor.
    `SAXHandler​(IDOMFactory factory)` | Constructor.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `protected void` | `addToCurrentGroup​(Item vtx)` | Adds the item to the current group; also attach the locator.
    `protected void` | `attachLocator​(Item vtx)` | Attaches the locator to the item.
    `void` | `attributeDecl​(java.lang.String eName, java.lang.String aName, java.lang.String type, java.lang.String valueDefault, java.lang.String value)` |
    `void` | `characters​(char[] ch, int start, int length)` |
    `void` | `comment​(char[] ch, int start, int length)` |
    `protected org.xml.sax.InputSource` | `defaultResolveEntity​(java.lang.String publicId, java.lang.String systemId)` | The default entity resolver.
    `void` | `elementDecl​(java.lang.String name, java.lang.String model)` |
    `void` | `endCDATA()` |
    `void` | `endDocument()` |
    `void` | `endDTD()` |
    `void` | `endElement​(java.lang.String nsURI, java.lang.String lname, java.lang.String tname)` |
    `void` | `endEntity​(java.lang.String name)` |
    `void` | `endPrefixMapping​(java.lang.String prefix)` |
    `void` | `error​(org.xml.sax.SAXParseException ex)` |
    `void` | `externalEntityDecl​(java.lang.String name, java.lang.String pubId, java.lang.String sysId)` |
    `void` | `fatalError​(org.xml.sax.SAXParseException ex)` |
    `Document` | `getDocument()` | Gets the document being created.
    `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.
    `protected Group` | `getTopGroup()` | Returns the top group, or null if not available.
    `void` | `ignorableWhitespace​(char[] ch, int start, int length)` |
    `void` | `internalEntityDecl​(java.lang.String name, java.lang.String value)` |
    `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.
    `void` | `notationDecl​(java.lang.String name, java.lang.String publicID, java.lang.String systemID)` |
    `protected void` | `popGroup()` | Pops out the current group, and the one under it becomes the new current group.
    `void` | `processingInstruction​(java.lang.String target, java.lang.String data)` |
    `protected void` | `pushGroup​(Group group)` | Adds a new group to the current group as a child, and pushes the new group to be the new current group.
    `org.xml.sax.InputSource` | `resolveEntity​(java.lang.String publicId, java.lang.String systemId)` |
    `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` | `setDocumentLocator​(org.xml.sax.Locator locator)` |
    `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.
    `void` | `startCDATA()` |
    `void` | `startDocument()` |
    `void` | `startDTD​(java.lang.String name, java.lang.String pubId, java.lang.String sysId)` |
    `void` | `startElement​(java.lang.String nsURI, java.lang.String lname, java.lang.String tname, org.xml.sax.Attributes attrs)` |
    `void` | `startEntity​(java.lang.String name)` |
    `void` | `startPrefixMapping​(java.lang.String prefix, java.lang.String uri)` |
    `void` | `unparsedEntityDecl​(java.lang.String name, java.lang.String pubId, java.lang.String sysId, java.lang.String notationName)` |
    `void` | `warning​(org.xml.sax.SAXParseException ex)` |

    - ### Methods inherited from class org.xml.sax.helpers.DefaultHandler

      `skippedEntity`

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### _factory

          protected IDOMFactory _factory

      The iDOM factory.

    - #### _doc

          protected Document _doc

      The Document being created.

    - #### _loc

          protected org.xml.sax.Locator _loc

      Locator.

    - #### _inDTD

          protected boolean _inDTD

      Indicator of whether we are in a DTD.

    - #### _inCData

          protected boolean _inCData

      Indicator of whether we are in a CDATA.

    - #### _stack

          protected java.util.Stack<Group> _stack

      The Group stack. The top one is the current group being processed.

    - #### _declNamespaces

          protected java.util.List<Namespace> _declNamespaces

      The namespaces in between startPrefixMapping and endPrefixMapping.

  - ### Constructor Detail

    - #### SAXHandler

          public SAXHandler​(IDOMFactory factory)

      Constructor.
      Parameters:
        `factory` - the iDOM factory; null for DefaultIDOMFactory.

    - #### SAXHandler

          public SAXHandler()

      Constructor.

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

    - #### getDocument

          public final Document getDocument()

      Gets the document being created. Called to retrieve the iDOM tree after parsed.

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

    - #### attachLocator

          protected final void attachLocator​(Item vtx)

      Attaches the locator to the item.

    - #### getTopGroup

          protected final Group getTopGroup()

      Returns the top group, or null if not available.

    - #### addToCurrentGroup

          protected final void addToCurrentGroup​(Item vtx)

      Adds the item to the current group; also attach the locator.

    - #### pushGroup

          protected final void pushGroup​(Group group)

      Adds a new group to the current group as a child, and pushes the new group to be the new current group.

    - #### popGroup

          protected final void popGroup()

      Pops out the current group, and the one under it becomes the new current group.

    - #### externalEntityDecl

          public void externalEntityDecl​(java.lang.String name,
                                         java.lang.String pubId,
                                         java.lang.String sysId)
                                  throws org.xml.sax.SAXException

      Specified by:
        `externalEntityDecl` in interface `org.xml.sax.ext.DeclHandler`
      Throws:
        `org.xml.sax.SAXException`

    - #### internalEntityDecl

          public void internalEntityDecl​(java.lang.String name,
                                         java.lang.String value)
                                  throws org.xml.sax.SAXException

      Specified by:
        `internalEntityDecl` in interface `org.xml.sax.ext.DeclHandler`
      Throws:
        `org.xml.sax.SAXException`

    - #### attributeDecl

          public void attributeDecl​(java.lang.String eName,
                                    java.lang.String aName,
                                    java.lang.String type,
                                    java.lang.String valueDefault,
                                    java.lang.String value)
                             throws org.xml.sax.SAXException

      Specified by:
        `attributeDecl` in interface `org.xml.sax.ext.DeclHandler`
      Throws:
        `org.xml.sax.SAXException`

    - #### elementDecl

          public void elementDecl​(java.lang.String name,
                                  java.lang.String model)
                           throws org.xml.sax.SAXException

      Specified by:
        `elementDecl` in interface `org.xml.sax.ext.DeclHandler`
      Throws:
        `org.xml.sax.SAXException`

    - #### startDTD

          public void startDTD​(java.lang.String name,
                               java.lang.String pubId,
                               java.lang.String sysId)
                        throws org.xml.sax.SAXException

      Specified by:
        `startDTD` in interface `org.xml.sax.ext.LexicalHandler`
      Throws:
        `org.xml.sax.SAXException`

    - #### endDTD

          public void endDTD()
                      throws org.xml.sax.SAXException

      Specified by:
        `endDTD` in interface `org.xml.sax.ext.LexicalHandler`
      Throws:
        `org.xml.sax.SAXException`

    - #### 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()
                          throws org.xml.sax.SAXException

      Specified by:
        `startCDATA` in interface `org.xml.sax.ext.LexicalHandler`
      Throws:
        `org.xml.sax.SAXException`

    - #### endCDATA

          public void endCDATA()
                        throws org.xml.sax.SAXException

      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

      Specified by:
        `comment` in interface `org.xml.sax.ext.LexicalHandler`
      Throws:
        `org.xml.sax.SAXException`

    - #### startDocument

          public void startDocument()
                             throws org.xml.sax.SAXException

      Specified by:
        `startDocument` in interface `org.xml.sax.ContentHandler`
      Overrides:
        `startDocument` in class `org.xml.sax.helpers.DefaultHandler`
      Throws:
        `org.xml.sax.SAXException`

    - #### endDocument

          public void endDocument()
                           throws org.xml.sax.SAXException

      Specified by:
        `endDocument` in interface `org.xml.sax.ContentHandler`
      Overrides:
        `endDocument` in class `org.xml.sax.helpers.DefaultHandler`
      Throws:
        `org.xml.sax.SAXException`

    - #### setDocumentLocator

          public void setDocumentLocator​(org.xml.sax.Locator locator)

      Specified by:
        `setDocumentLocator` in interface `org.xml.sax.ContentHandler`
      Overrides:
        `setDocumentLocator` in class `org.xml.sax.helpers.DefaultHandler`

    - #### processingInstruction

          public void processingInstruction​(java.lang.String target,
                                            java.lang.String data)
                                     throws org.xml.sax.SAXException

      Specified by:
        `processingInstruction` in interface `org.xml.sax.ContentHandler`
      Overrides:
        `processingInstruction` in class `org.xml.sax.helpers.DefaultHandler`
      Throws:
        `org.xml.sax.SAXException`

    - #### startPrefixMapping

          public void startPrefixMapping​(java.lang.String prefix,
                                         java.lang.String uri)
                                  throws org.xml.sax.SAXException

      Specified by:
        `startPrefixMapping` in interface `org.xml.sax.ContentHandler`
      Overrides:
        `startPrefixMapping` in class `org.xml.sax.helpers.DefaultHandler`
      Throws:
        `org.xml.sax.SAXException`

    - #### endPrefixMapping

          public void endPrefixMapping​(java.lang.String prefix)
                                throws org.xml.sax.SAXException

      Specified by:
        `endPrefixMapping` in interface `org.xml.sax.ContentHandler`
      Overrides:
        `endPrefixMapping` in class `org.xml.sax.helpers.DefaultHandler`
      Throws:
        `org.xml.sax.SAXException`

    - #### startElement

          public void startElement​(java.lang.String nsURI,
                                   java.lang.String lname,
                                   java.lang.String tname,
                                   org.xml.sax.Attributes attrs)
                            throws org.xml.sax.SAXException

      Specified by:
        `startElement` in interface `org.xml.sax.ContentHandler`
      Overrides:
        `startElement` in class `org.xml.sax.helpers.DefaultHandler`
      Throws:
        `org.xml.sax.SAXException`

    - #### endElement

          public void endElement​(java.lang.String nsURI,
                                 java.lang.String lname,
                                 java.lang.String tname)
                          throws org.xml.sax.SAXException

      Specified by:
        `endElement` in interface `org.xml.sax.ContentHandler`
      Overrides:
        `endElement` in class `org.xml.sax.helpers.DefaultHandler`
      Throws:
        `org.xml.sax.SAXException`

    - #### characters

          public void characters​(char[] ch,
                                 int start,
                                 int length)
                          throws org.xml.sax.SAXException

      Specified by:
        `characters` in interface `org.xml.sax.ContentHandler`
      Overrides:
        `characters` in class `org.xml.sax.helpers.DefaultHandler`
      Throws:
        `org.xml.sax.SAXException`

    - #### ignorableWhitespace

          public void ignorableWhitespace​(char[] ch,
                                          int start,
                                          int length)
                                   throws org.xml.sax.SAXException

      Specified by:
        `ignorableWhitespace` in interface `org.xml.sax.ContentHandler`
      Overrides:
        `ignorableWhitespace` in class `org.xml.sax.helpers.DefaultHandler`
      Throws:
        `org.xml.sax.SAXException`

    - #### notationDecl

          public void notationDecl​(java.lang.String name,
                                   java.lang.String publicID,
                                   java.lang.String systemID)
                            throws org.xml.sax.SAXException

      Specified by:
        `notationDecl` in interface `org.xml.sax.DTDHandler`
      Overrides:
        `notationDecl` in class `org.xml.sax.helpers.DefaultHandler`
      Throws:
        `org.xml.sax.SAXException`

    - #### unparsedEntityDecl

          public void unparsedEntityDecl​(java.lang.String name,
                                         java.lang.String pubId,
                                         java.lang.String sysId,
                                         java.lang.String notationName)
                                  throws org.xml.sax.SAXException

      Specified by:
        `unparsedEntityDecl` in interface `org.xml.sax.DTDHandler`
      Overrides:
        `unparsedEntityDecl` in class `org.xml.sax.helpers.DefaultHandler`
      Throws:
        `org.xml.sax.SAXException`

    - #### resolveEntity

          public org.xml.sax.InputSource resolveEntity​(java.lang.String publicId,
                                                       java.lang.String systemId)
                                                throws org.xml.sax.SAXException

      Specified by:
        `resolveEntity` in interface `org.xml.sax.EntityResolver`
      Overrides:
        `resolveEntity` in class `org.xml.sax.helpers.DefaultHandler`
      Throws:
        `org.xml.sax.SAXException`

    - #### defaultResolveEntity

          protected org.xml.sax.InputSource defaultResolveEntity​(java.lang.String publicId,
                                                                 java.lang.String systemId)
                                                          throws org.xml.sax.SAXException

      The default entity resolver. It is used if `setEntityResolver(org.xml.sax.EntityResolver)` is not called. This implementation searches the class path under /metainfo/xml.

      For example, http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd is asked. It searches from classpath for /metainfo/xml/java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd and /metainfo/xml/portlet-app_1_0.xsd

      Throws:
        `org.xml.sax.SAXException`

    - #### warning

          public void warning​(org.xml.sax.SAXParseException ex)
                       throws org.xml.sax.SAXException

      Specified by:
        `warning` in interface `org.xml.sax.ErrorHandler`
      Overrides:
        `warning` in class `org.xml.sax.helpers.DefaultHandler`
      Throws:
        `org.xml.sax.SAXException`

    - #### error

          public void error​(org.xml.sax.SAXParseException ex)
                     throws org.xml.sax.SAXException

      Specified by:
        `error` in interface `org.xml.sax.ErrorHandler`
      Overrides:
        `error` in class `org.xml.sax.helpers.DefaultHandler`
      Throws:
        `org.xml.sax.SAXException`

    - #### fatalError

          public void fatalError​(org.xml.sax.SAXParseException ex)
                          throws org.xml.sax.SAXException

      Specified by:
        `fatalError` in interface `org.xml.sax.ErrorHandler`
      Overrides:
        `fatalError` in class `org.xml.sax.helpers.DefaultHandler`
      Throws:
        `org.xml.sax.SAXException`