Package: groovy.util

## [Java] Class XmlParser

- groovy.util.XmlParser

- All Implemented Interfaces and Traits:
    ContentHandler

      public class XmlParser
      extends Object

  A helper class for parsing XML into a tree of Node instances for a simple way of processing XML. This parser does not preserve the XML InfoSet - if that's what you need try using W3C DOM, dom4j, JDOM, XOM etc. This parser ignores comments and processing instructions and converts the XML into a Node for each element in the XML with attributes and child Nodes and Strings. This simple model is sufficient for most simple use cases of processing XML.

  Example usage:

       def xml = '<root><one a1="uno!"/><two>Some text!</two></root>'
       def rootNode = new XmlParser().parseText(xml)
       assert rootNode.name() == 'root'
       assert rootNode.one[0].@a1 == 'uno!'
       assert rootNode.two.text() == 'Some text!'
       rootNode.children().each { assert it.name() in ['one','two'] }

  Authors:
    James Strachan
    Paul King

- - ### Constructor Summary

    Constructors
    Constructor and description
    `XmlParser ()` Creates a non-validating and non-namespace-aware `XmlParser` which does not allow DOCTYPE declarations in documents.
    `XmlParser (boolean validating, boolean namespaceAware)` Creates a `XmlParser` which does not allow DOCTYPE declarations in documents.
    `XmlParser (boolean validating, boolean namespaceAware, boolean allowDocTypeDeclaration)` Creates a `XmlParser`.
    `XmlParser (XMLReader reader)`
    `XmlParser (SAXParser parser)`

  - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `protected void` | `addTextToNode()`
    `` | `void` | `characters(char[] buffer, int start, int length)`
    `` | `protected Node` | `createNode(Node parent, Object name, Map attributes)` Creates a new node with the given parent, name, and attributes.
    `` | `void` | `endDocument()`
    `` | `void` | `endElement(String namespaceURI, String localName, String qName)`
    `` | `void` | `endPrefixMapping(String prefix)`
    `` | `DTDHandler` | `getDTDHandler()`
    `` | `Locator` | `getDocumentLocator()`
    `` | `protected Object` | `getElementName(String namespaceURI, String localName, String qName)` Return a name given the namespaceURI, localName and qName.
    `` | `EntityResolver` | `getEntityResolver()`
    `` | `ErrorHandler` | `getErrorHandler()`
    `` | `boolean` | `getFeature(String uri)`
    `` | `Object` | `getProperty(String uri)`
    `` | `protected XMLReader` | `getXMLReader()`
    `` | `void` | `ignorableWhitespace(char[] buffer, int start, int len)`
    `` | `boolean` | `isKeepIgnorableWhitespace()` Returns the current keep ignorable whitespace setting.
    `` | `boolean` | `isNamespaceAware()` Determine if namespace handling is enabled.
    `` | `boolean` | `isTrimWhitespace()` Returns the current trim whitespace setting.
    `` | `Node` | `parse(File file)` Parses the content of the given file as XML turning it into a tree of Nodes.
    `` | `Node` | `parse(InputSource input)` Parse the content of the specified input source into a tree of Nodes.
    `` | `Node` | `parse(InputStream input)` Parse the content of the specified input stream into a tree of Nodes.
    `` | `Node` | `parse(Reader in)` Parse the content of the specified reader into a tree of Nodes.
    `` | `Node` | `parse(String uri)` Parse the content of the specified URI into a tree of Nodes.
    `` | `Node` | `parseText(String text)` A helper method to parse the given text as XML.
    `` | `void` | `processingInstruction(String target, String data)`
    `` | `void` | `setDTDHandler(DTDHandler dtdHandler)`
    `` | `void` | `setDocumentLocator(Locator locator)`
    `` | `void` | `setEntityResolver(EntityResolver entityResolver)`
    `` | `void` | `setErrorHandler(ErrorHandler errorHandler)`
    `` | `void` | `setFeature(String uri, boolean value)`
    `` | `void` | `setKeepIgnorableWhitespace(boolean keepIgnorableWhitespace)` Sets the keep ignorable whitespace setting value.
    `` | `void` | `setNamespaceAware(boolean namespaceAware)` Enable and/or disable namespace handling.
    `` | `void` | `setProperty(String uri, Object value)`
    `` | `void` | `setTrimWhitespace(boolean trimWhitespace)` Sets the trim whitespace setting value.
    `` | `void` | `skippedEntity(String name)`
    `` | `void` | `startDocument()`
    `` | `void` | `startElement(String namespaceURI, String localName, String qName, Attributes list)`
    `` | `void` | `startPrefixMapping(String prefix, String namespaceURI)`

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class Object` | `equals, toString, hashCode, getClass, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### public XmlParser()

      Creates a non-validating and non-namespace-aware `XmlParser` which does not allow DOCTYPE declarations in documents.

      throws:
        ParserConfigurationException if no parser which satisfies the requested configuration can be created.
      throws:
        SAXException for SAX errors.

    - #### public XmlParser(boolean validating, boolean namespaceAware)

      Creates a `XmlParser` which does not allow DOCTYPE declarations in documents.

      throws:
        ParserConfigurationException if no parser which satisfies the requested configuration can be created.
      throws:
        SAXException for SAX errors.
      Parameters:
        `validating` - `true` if the parser should validate documents as they are parsed; false otherwise.
        `namespaceAware` - `true` if the parser should provide support for XML namespaces; `false` otherwise.

    - #### public XmlParser(boolean validating, boolean namespaceAware, boolean allowDocTypeDeclaration)

      Creates a `XmlParser`.

      throws:
        ParserConfigurationException if no parser which satisfies the requested configuration can be created.
      throws:
        SAXException for SAX errors.
      Parameters:
        `validating` - `true` if the parser should validate documents as they are parsed; false otherwise.
        `namespaceAware` - `true` if the parser should provide support for XML namespaces; `false` otherwise.
        `allowDocTypeDeclaration` - `true` if the parser should provide support for DOCTYPE declarations; `false` otherwise.

    - #### public XmlParser(XMLReader reader)

    - #### public XmlParser(SAXParser parser)

  - ### Method Detail

    - #### protected void addTextToNode()

    - #### public void characters(char[] buffer, int start, int length)

    - #### protected Node createNode(Node parent, Object name, Map attributes)

      Creates a new node with the given parent, name, and attributes. The default implementation returns an instance of `groovy.util.Node`.

      Parameters:
        `parent` - the parent node, or null if the node being created is the root node
        `name` - an Object representing the name of the node (typically an instance of QName)
        `attributes` - a Map of attribute names to attribute values
      Returns:
        a new Node instance representing the current node

    - #### public void endDocument()

    - #### public void endElement(String namespaceURI, String localName, String qName)

    - #### public void endPrefixMapping(String prefix)

    - #### public DTDHandler getDTDHandler()

    - #### public Locator getDocumentLocator()

    - #### protected Object getElementName(String namespaceURI, String localName, String qName)

      Return a name given the namespaceURI, localName and qName.

      Parameters:
        `namespaceURI` - the namespace URI
        `localName` - the local name
        `qName` - the qualified name
      Returns:
        the newly created representation of the name

    - #### public EntityResolver getEntityResolver()

    - #### public ErrorHandler getErrorHandler()

    - #### public boolean getFeature(String uri)

    - #### public Object getProperty(String uri)

    - #### protected XMLReader getXMLReader()

    - #### public void ignorableWhitespace(char[] buffer, int start, int len)

    - #### public boolean isKeepIgnorableWhitespace()

      Returns the current keep ignorable whitespace setting.

      Returns:
        true if ignorable whitespace will be kept (default false)

    - #### public boolean isNamespaceAware()

      Determine if namespace handling is enabled.

      Returns:
        true if namespace handling is enabled

    - #### public boolean isTrimWhitespace()

      Returns the current trim whitespace setting.

      Returns:
        true if whitespace will be trimmed

    - #### public Node parse(File file)

      Parses the content of the given file as XML turning it into a tree of Nodes.

      throws:
        SAXException Any SAX exception, possibly wrapping another exception.
      throws:
        IOException An IO exception from the parser, possibly from a byte stream or character stream supplied by the application.
      Parameters:
        `file` - the File containing the XML to be parsed
      Returns:
        the root node of the parsed tree of Nodes

    - #### public Node parse(InputSource input)

      Parse the content of the specified input source into a tree of Nodes.

      throws:
        SAXException Any SAX exception, possibly wrapping another exception.
      throws:
        IOException An IO exception from the parser, possibly from a byte stream or character stream supplied by the application.
      Parameters:
        `input` - the InputSource for the XML to parse
      Returns:
        the root node of the parsed tree of Nodes

    - #### public Node parse(InputStream input)

      Parse the content of the specified input stream into a tree of Nodes.

      Note that using this method will not provide the parser with any URI for which to find DTDs etc

      throws:
        SAXException Any SAX exception, possibly wrapping another exception.
      throws:
        IOException An IO exception from the parser, possibly from a byte stream or character stream supplied by the application.
      Parameters:
        `input` - an InputStream containing the XML to be parsed
      Returns:
        the root node of the parsed tree of Nodes

    - #### public Node parse(Reader in)

      Parse the content of the specified reader into a tree of Nodes.

      Note that using this method will not provide the parser with any URI for which to find DTDs etc

      throws:
        SAXException Any SAX exception, possibly wrapping another exception.
      throws:
        IOException An IO exception from the parser, possibly from a byte stream or character stream supplied by the application.
      Parameters:
        `in` - a Reader to read the XML to be parsed
      Returns:
        the root node of the parsed tree of Nodes

    - #### public Node parse(String uri)

      Parse the content of the specified URI into a tree of Nodes.

      throws:
        SAXException Any SAX exception, possibly wrapping another exception.
      throws:
        IOException An IO exception from the parser, possibly from a byte stream or character stream supplied by the application.
      Parameters:
        `uri` - a String containing a uri pointing to the XML to be parsed
      Returns:
        the root node of the parsed tree of Nodes

    - #### public Node parseText(String text)

      A helper method to parse the given text as XML.

      throws:
        SAXException Any SAX exception, possibly wrapping another exception.
      throws:
        IOException An IO exception from the parser, possibly from a byte stream or character stream supplied by the application.
      Parameters:
        `text` - the XML text to parse
      Returns:
        the root node of the parsed tree of Nodes

    - #### public void processingInstruction(String target, String data)

    - #### public void setDTDHandler(DTDHandler dtdHandler)

    - #### public void setDocumentLocator(Locator locator)

    - #### public void setEntityResolver(EntityResolver entityResolver)

    - #### public void setErrorHandler(ErrorHandler errorHandler)

    - #### public void setFeature(String uri, boolean value)

    - #### public void setKeepIgnorableWhitespace(boolean keepIgnorableWhitespace)

      Sets the keep ignorable whitespace setting value.

      Parameters:
        `keepIgnorableWhitespace` - the desired new value

    - #### public void setNamespaceAware(boolean namespaceAware)

      Enable and/or disable namespace handling.

      Parameters:
        `namespaceAware` - the new desired value

    - #### public void setProperty(String uri, Object value)

    - #### public void setTrimWhitespace(boolean trimWhitespace)

      Sets the trim whitespace setting value.

      Parameters:
        `trimWhitespace` - the desired setting value

    - #### public void skippedEntity(String name)

    - #### public void startDocument()

    - #### public void startElement(String namespaceURI, String localName, String qName, Attributes list)

    - #### public void startPrefixMapping(String prefix, String namespaceURI)