Package groovy.xml

# Class XmlParser

java.lang.Object
groovy.xml.XmlParser

All Implemented Interfaces:
  `ContentHandler`

    public class XmlParser
    extends Object
    implements ContentHandler

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:

     import groovy.xml.XmlParser
     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'] }

- ## Constructor Summary

  Constructors
  Constructor | Description
  --- | ---
  `XmlParser()` | Creates a non-validating and 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​(SAXParser parser)` |
  `XmlParser​(XMLReader reader)` |

- ## Method Summary

  Modifier and Type | Method | 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)` |
  `Locator` | `getDocumentLocator()` |
  `DTDHandler` | `getDTDHandler()` |
  `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​(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` | `parse​(InputSource input)` | Parse the content of the specified input source 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` | `setDocumentLocator​(Locator locator)` |
  `void` | `setDTDHandler​(DTDHandler dtdHandler)` |
  `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)` |

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

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

  ### Methods inherited from interface org.xml.sax.ContentHandler

  `declaration`

- ## Constructor Details

  - ### XmlParser

    public XmlParser() throws ParserConfigurationException, SAXException
    Creates a non-validating and namespace-aware `XmlParser` which does not allow DOCTYPE declarations in documents.
    Throws:
      `ParserConfigurationException` - if no parser which satisfies the requested configuration can be created.
      `SAXException` - for SAX errors.

  - ### XmlParser

    public XmlParser​(boolean validating, boolean namespaceAware) throws ParserConfigurationException, SAXException
    Creates a `XmlParser` which does not allow DOCTYPE declarations in documents.
    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.
    Throws:
      `ParserConfigurationException` - if no parser which satisfies the requested configuration can be created.
      `SAXException` - for SAX errors.

  - ### XmlParser

    public XmlParser​(boolean validating, boolean namespaceAware, boolean allowDocTypeDeclaration) throws ParserConfigurationException, SAXException
    Creates a `XmlParser`.
    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.
    Throws:
      `ParserConfigurationException` - if no parser which satisfies the requested configuration can be created.
      `SAXException` - for SAX errors.

  - ### XmlParser

    public XmlParser​(XMLReader reader)

  - ### XmlParser

    public XmlParser​(SAXParser parser) throws SAXException
    Throws:
      `SAXException`

- ## Method Details

  - ### isTrimWhitespace

    public boolean isTrimWhitespace()
    Returns the current trim whitespace setting.
    Returns:
      true if whitespace will be trimmed

  - ### setTrimWhitespace

    public void setTrimWhitespace​(boolean trimWhitespace)
    Sets the trim whitespace setting value.
    Parameters:
      `trimWhitespace` - the desired setting value

  - ### isKeepIgnorableWhitespace

    public boolean isKeepIgnorableWhitespace()
    Returns the current keep ignorable whitespace setting.
    Returns:
      true if ignorable whitespace will be kept (default false)

  - ### setKeepIgnorableWhitespace

    public void setKeepIgnorableWhitespace​(boolean keepIgnorableWhitespace)
    Sets the keep ignorable whitespace setting value.
    Parameters:
      `keepIgnorableWhitespace` - the desired new value

  - ### parse

    public Node parse​(File file) throws IOException, SAXException
    Parses the content of the given file as XML turning it into a tree of Nodes.
    Parameters:
      `file` - the File containing the XML to be parsed
    Returns:
      the root node of the parsed tree of Nodes
    Throws:
      `SAXException` - Any SAX exception, possibly wrapping another exception.
      `IOException` - An IO exception from the parser, possibly from a byte stream or character stream supplied by the application.

  - ### parse

    public Node parse​(InputSource input) throws IOException, SAXException
    Parse the content of the specified input source into a tree of Nodes.
    Parameters:
      `input` - the InputSource for the XML to parse
    Returns:
      the root node of the parsed tree of Nodes
    Throws:
      `SAXException` - Any SAX exception, possibly wrapping another exception.
      `IOException` - An IO exception from the parser, possibly from a byte stream or character stream supplied by the application.

  - ### parse

    public Node parse​(InputStream input) throws IOException, SAXException
    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

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

  - ### parse

    public Node parse​(Reader in) throws IOException, SAXException
    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

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

  - ### parse

    public Node parse​(String uri) throws IOException, SAXException
    Parse the content of the specified URI into a tree of Nodes.
    Parameters:
      `uri` - a String containing a uri pointing to the XML to be parsed
    Returns:
      the root node of the parsed tree of Nodes
    Throws:
      `SAXException` - Any SAX exception, possibly wrapping another exception.
      `IOException` - An IO exception from the parser, possibly from a byte stream or character stream supplied by the application.

  - ### parseText

    public Node parseText​(String text) throws IOException, SAXException
    A helper method to parse the given text as XML.
    Parameters:
      `text` - the XML text to parse
    Returns:
      the root node of the parsed tree of Nodes
    Throws:
      `SAXException` - Any SAX exception, possibly wrapping another exception.
      `IOException` - An IO exception from the parser, possibly from a byte stream or character stream supplied by the application.

  - ### isNamespaceAware

    public boolean isNamespaceAware()
    Determine if namespace handling is enabled.
    Returns:
      true if namespace handling is enabled

  - ### setNamespaceAware

    public void setNamespaceAware​(boolean namespaceAware)
    Enable and/or disable namespace handling.
    Parameters:
      `namespaceAware` - the new desired value

  - ### getDTDHandler

    public DTDHandler getDTDHandler()

  - ### getEntityResolver

    public EntityResolver getEntityResolver()

  - ### getErrorHandler

    public ErrorHandler getErrorHandler()

  - ### getFeature

    public boolean getFeature​(String uri) throws SAXNotRecognizedException, SAXNotSupportedException
    Throws:
      `SAXNotRecognizedException`
      `SAXNotSupportedException`

  - ### getProperty

    public Object getProperty​(String uri) throws SAXNotRecognizedException, SAXNotSupportedException
    Throws:
      `SAXNotRecognizedException`
      `SAXNotSupportedException`

  - ### setDTDHandler

    public void setDTDHandler​(DTDHandler dtdHandler)

  - ### setEntityResolver

    public void setEntityResolver​(EntityResolver entityResolver)

  - ### setErrorHandler

    public void setErrorHandler​(ErrorHandler errorHandler)

  - ### setFeature

    public void setFeature​(String uri, boolean value) throws SAXNotRecognizedException, SAXNotSupportedException
    Throws:
      `SAXNotRecognizedException`
      `SAXNotSupportedException`

  - ### setProperty

    public void setProperty​(String uri, Object value) throws SAXNotRecognizedException, SAXNotSupportedException
    Throws:
      `SAXNotRecognizedException`
      `SAXNotSupportedException`

  - ### startDocument

    public void startDocument() throws SAXException
    Specified by:
      `startDocument` in interface `ContentHandler`
    Throws:
      `SAXException`

  - ### endDocument

    public void endDocument() throws SAXException
    Specified by:
      `endDocument` in interface `ContentHandler`
    Throws:
      `SAXException`

  - ### startElement

    public void startElement​(String namespaceURI, String localName, String qName, Attributes list) throws SAXException
    Specified by:
      `startElement` in interface `ContentHandler`
    Throws:
      `SAXException`

  - ### endElement

    public void endElement​(String namespaceURI, String localName, String qName) throws SAXException
    Specified by:
      `endElement` in interface `ContentHandler`
    Throws:
      `SAXException`

  - ### characters

    public void characters​(char[] buffer, int start, int length) throws SAXException
    Specified by:
      `characters` in interface `ContentHandler`
    Throws:
      `SAXException`

  - ### startPrefixMapping

    public void startPrefixMapping​(String prefix, String namespaceURI) throws SAXException
    Specified by:
      `startPrefixMapping` in interface `ContentHandler`
    Throws:
      `SAXException`

  - ### endPrefixMapping

    public void endPrefixMapping​(String prefix) throws SAXException
    Specified by:
      `endPrefixMapping` in interface `ContentHandler`
    Throws:
      `SAXException`

  - ### ignorableWhitespace

    public void ignorableWhitespace​(char[] buffer, int start, int len) throws SAXException
    Specified by:
      `ignorableWhitespace` in interface `ContentHandler`
    Throws:
      `SAXException`

  - ### processingInstruction

    public void processingInstruction​(String target, String data) throws SAXException
    Specified by:
      `processingInstruction` in interface `ContentHandler`
    Throws:
      `SAXException`

  - ### getDocumentLocator

    public Locator getDocumentLocator()

  - ### setDocumentLocator

    public void setDocumentLocator​(Locator locator)
    Specified by:
      `setDocumentLocator` in interface `ContentHandler`

  - ### skippedEntity

    public void skippedEntity​(String name) throws SAXException
    Specified by:
      `skippedEntity` in interface `ContentHandler`
    Throws:
      `SAXException`

  - ### getXMLReader

    protected XMLReader getXMLReader()

  - ### addTextToNode

    protected void addTextToNode()

  - ### createNode

    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

  - ### getElementName

    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