Package groovy.xml

Class XmlParser

java.lang.Object
groovy.xml.XmlParser
All Implemented Interfaces:
org.xml.sax.ContentHandler
public class XmlParser
extends java.lang.Object
implements org.xml.sax.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​(javax.xml.parsers.SAXParser parser)  
    XmlParser​(org.xml.sax.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, java.lang.Object name, java.util.Map attributes)
    Creates a new node with the given parent, name, and attributes.
    void endDocument()  
    void endElement​(java.lang.String namespaceURI, java.lang.String localName, java.lang.String qName)  
    void endPrefixMapping​(java.lang.String prefix)  
    org.xml.sax.Locator getDocumentLocator()  
    org.xml.sax.DTDHandler getDTDHandler()  
    protected java.lang.Object getElementName​(java.lang.String namespaceURI, java.lang.String localName, java.lang.String qName)
    Return a name given the namespaceURI, localName and qName.
    org.xml.sax.EntityResolver getEntityResolver()  
    org.xml.sax.ErrorHandler getErrorHandler()  
    boolean getFeature​(java.lang.String uri)  
    java.lang.Object getProperty​(java.lang.String uri)  
    protected org.xml.sax.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​(java.io.File file)
    Parses the content of the given file as XML turning it into a tree of Nodes.
    Node parse​(java.io.InputStream input)
    Parse the content of the specified input stream into a tree of Nodes.
    Node parse​(java.io.Reader in)
    Parse the content of the specified reader into a tree of Nodes.
    Node parse​(java.lang.String uri)
    Parse the content of the specified URI into a tree of Nodes.
    Node parse​(org.xml.sax.InputSource input)
    Parse the content of the specified input source into a tree of Nodes.
    Node parseText​(java.lang.String text)
    A helper method to parse the given text as XML.
    void processingInstruction​(java.lang.String target, java.lang.String data)  
    void setDocumentLocator​(org.xml.sax.Locator locator)  
    void setDTDHandler​(org.xml.sax.DTDHandler dtdHandler)  
    void setEntityResolver​(org.xml.sax.EntityResolver entityResolver)  
    void setErrorHandler​(org.xml.sax.ErrorHandler errorHandler)  
    void setFeature​(java.lang.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​(java.lang.String uri, java.lang.Object value)  
    void setTrimWhitespace​(boolean trimWhitespace)
    Sets the trim whitespace setting value.
    void skippedEntity​(java.lang.String name)  
    void startDocument()  
    void startElement​(java.lang.String namespaceURI, java.lang.String localName, java.lang.String qName, org.xml.sax.Attributes list)  
    void startPrefixMapping​(java.lang.String prefix, java.lang.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 javax.xml.parsers.ParserConfigurationException, org.xml.sax.SAXException
      Creates a non-validating and namespace-aware XmlParser which does not allow DOCTYPE declarations in documents.
      Throws:
      javax.xml.parsers.ParserConfigurationException - if no parser which satisfies the requested configuration can be created.
      org.xml.sax.SAXException - for SAX errors.

    • XmlParser

      public XmlParser​(boolean validating, boolean namespaceAware) throws javax.xml.parsers.ParserConfigurationException, org.xml.sax.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:
      javax.xml.parsers.ParserConfigurationException - if no parser which satisfies the requested configuration can be created.
      org.xml.sax.SAXException - for SAX errors.

    • XmlParser

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

    • XmlParser

      public XmlParser​(org.xml.sax.XMLReader reader)

    • XmlParser

      public XmlParser​(javax.xml.parsers.SAXParser parser) throws org.xml.sax.SAXException
      Throws:
      org.xml.sax.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​(java.io.File file) throws java.io.IOException, org.xml.sax.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:
      org.xml.sax.SAXException - Any SAX exception, possibly wrapping another exception.
      java.io.IOException - An IO exception from the parser, possibly from a byte stream or character stream supplied by the application.

    • parse

      public Node parse​(org.xml.sax.InputSource input) throws java.io.IOException, org.xml.sax.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:
      org.xml.sax.SAXException - Any SAX exception, possibly wrapping another exception.
      java.io.IOException - An IO exception from the parser, possibly from a byte stream or character stream supplied by the application.

    • parse

      public Node parse​(java.io.InputStream input) throws java.io.IOException, org.xml.sax.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:
      org.xml.sax.SAXException - Any SAX exception, possibly wrapping another exception.
      java.io.IOException - An IO exception from the parser, possibly from a byte stream or character stream supplied by the application.

    • parse

      public Node parse​(java.io.Reader in) throws java.io.IOException, org.xml.sax.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:
      org.xml.sax.SAXException - Any SAX exception, possibly wrapping another exception.
      java.io.IOException - An IO exception from the parser, possibly from a byte stream or character stream supplied by the application.

    • parse

      public Node parse​(java.lang.String uri) throws java.io.IOException, org.xml.sax.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:
      org.xml.sax.SAXException - Any SAX exception, possibly wrapping another exception.
      java.io.IOException - An IO exception from the parser, possibly from a byte stream or character stream supplied by the application.

    • parseText

      public Node parseText​(java.lang.String text) throws java.io.IOException, org.xml.sax.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:
      org.xml.sax.SAXException - Any SAX exception, possibly wrapping another exception.
      java.io.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 org.xml.sax.DTDHandler getDTDHandler()

    • getEntityResolver

      public org.xml.sax.EntityResolver getEntityResolver()

    • getErrorHandler

      public org.xml.sax.ErrorHandler getErrorHandler()

    • getFeature

      public boolean getFeature​(java.lang.String uri) throws org.xml.sax.SAXNotRecognizedException, org.xml.sax.SAXNotSupportedException
      Throws:
      org.xml.sax.SAXNotRecognizedException
      org.xml.sax.SAXNotSupportedException

    • getProperty

      public java.lang.Object getProperty​(java.lang.String uri) throws org.xml.sax.SAXNotRecognizedException, org.xml.sax.SAXNotSupportedException
      Throws:
      org.xml.sax.SAXNotRecognizedException
      org.xml.sax.SAXNotSupportedException

    • setDTDHandler

      public void setDTDHandler​(org.xml.sax.DTDHandler dtdHandler)

    • setEntityResolver

      public void setEntityResolver​(org.xml.sax.EntityResolver entityResolver)

    • setErrorHandler

      public void setErrorHandler​(org.xml.sax.ErrorHandler errorHandler)

    • setFeature

      public void setFeature​(java.lang.String uri, boolean value) throws org.xml.sax.SAXNotRecognizedException, org.xml.sax.SAXNotSupportedException
      Throws:
      org.xml.sax.SAXNotRecognizedException
      org.xml.sax.SAXNotSupportedException

    • setProperty

      public void setProperty​(java.lang.String uri, java.lang.Object value) throws org.xml.sax.SAXNotRecognizedException, org.xml.sax.SAXNotSupportedException
      Throws:
      org.xml.sax.SAXNotRecognizedException
      org.xml.sax.SAXNotSupportedException

    • startDocument

      public void startDocument() throws org.xml.sax.SAXException
      Specified by:
      startDocument in interface org.xml.sax.ContentHandler
      Throws:
      org.xml.sax.SAXException

    • endDocument

      public void endDocument() throws org.xml.sax.SAXException
      Specified by:
      endDocument in interface org.xml.sax.ContentHandler
      Throws:
      org.xml.sax.SAXException

    • startElement

      public void startElement​(java.lang.String namespaceURI, java.lang.String localName, java.lang.String qName, org.xml.sax.Attributes list) throws org.xml.sax.SAXException
      Specified by:
      startElement in interface org.xml.sax.ContentHandler
      Throws:
      org.xml.sax.SAXException

    • endElement

      public void endElement​(java.lang.String namespaceURI, java.lang.String localName, java.lang.String qName) throws org.xml.sax.SAXException
      Specified by:
      endElement in interface org.xml.sax.ContentHandler
      Throws:
      org.xml.sax.SAXException

    • characters

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

    • startPrefixMapping

      public void startPrefixMapping​(java.lang.String prefix, java.lang.String namespaceURI) throws org.xml.sax.SAXException
      Specified by:
      startPrefixMapping in interface org.xml.sax.ContentHandler
      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
      Throws:
      org.xml.sax.SAXException

    • ignorableWhitespace

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

    • 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
      Throws:
      org.xml.sax.SAXException

    • getDocumentLocator

      public org.xml.sax.Locator getDocumentLocator()

    • setDocumentLocator

      public void setDocumentLocator​(org.xml.sax.Locator locator)
      Specified by:
      setDocumentLocator in interface org.xml.sax.ContentHandler

    • skippedEntity

      public void skippedEntity​(java.lang.String name) throws org.xml.sax.SAXException
      Specified by:
      skippedEntity in interface org.xml.sax.ContentHandler
      Throws:
      org.xml.sax.SAXException

    • getXMLReader

      protected org.xml.sax.XMLReader getXMLReader()

    • addTextToNode

      protected void addTextToNode()

    • createNode

      protected Node createNode​(Node parent, java.lang.Object name, java.util.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 java.lang.Object getElementName​(java.lang.String namespaceURI, java.lang.String localName, java.lang.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