Package groovy.xml

Class DOMBuilder

java.lang.Object

groovy.lang.GroovyObjectSupport

groovy.util.BuilderSupport

groovy.xml.DOMBuilder

All Implemented Interfaces:

GroovyObject

public class DOMBuilder
extends BuilderSupport

A helper class for creating a W3C DOM tree

Constructor Summary

Constructors

Constructor	Description
DOMBuilder(DocumentBuilder documentBuilder)	Creates a builder that lazily creates a backing document from the supplied document builder.
DOMBuilder(Document document)	Creates a builder that appends newly created elements to the supplied document.

Method Summary

Modifier and Type	Method	Description
protected void	appendNamespaceAttributes(Element element, Map<Object,Object> attributes)	Applies namespace declaration attributes from an xmlns map to the supplied element.
protected Document	createDocument()	Creates the backing document used by subsequent builder callbacks.
protected Object	createNode(Object name)	Builder lifecycle callback that creates an element for the supplied node name.
protected Object	createNode(Object name, Object value)	Builder lifecycle callback that creates an element and adds text content to it.
protected Object	createNode(Object name, Map attributes)	Builder lifecycle callback that creates an element and applies the supplied attributes.
protected Object	createNode(Object name, Map attributes, Object value)	Builder lifecycle callback that creates an element, applies attributes and adds text content.
static DOMBuilder	newInstance()	Creates a non-validating, namespace-aware DOM builder.
static DOMBuilder	newInstance(boolean validating, boolean namespaceAware)	Creates a DOM builder using the requested parser settings.
static DOMBuilder	newInstance(boolean validating, boolean namespaceAware, boolean allowDocTypeDeclaration)	Creates a DOM builder using the requested parser settings, including whether DOCTYPE declarations are permitted in parsed documents.
static Document	parse(Reader reader)	Creates a DocumentBuilder and uses it to parse the XML text read from the given reader.
static Document	parse(Reader reader, boolean validating, boolean namespaceAware)	Creates a DocumentBuilder and uses it to parse the XML text read from the given reader, allowing parser validation and namespace awareness to be controlled.
static Document	parse(Reader reader, boolean validating, boolean namespaceAware, boolean allowDocTypeDeclaration)	Creates a DocumentBuilder and uses it to parse the XML text read from the given reader, allowing parser validation, namespace awareness and permission of DOCTYPE declarations to be controlled.
Document	parseText(String text)	A helper method to parse the given text as XML.
protected void	setParent(Object parent, Object child)	Builder lifecycle callback that attaches a completed child node to its parent node.

Methods inherited from class groovy.util.BuilderSupport

doInvokeMethod, getCurrent, getName, invokeMethod, invokeMethod, nodeCompleted, postNodeCompletion, setClosureDelegate, setCurrent

Methods inherited from class groovy.lang.GroovyObjectSupport

getMetaClass, setMetaClass

Methods inherited from class java.lang.Object

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

Methods inherited from interface groovy.lang.GroovyObject

getProperty, setProperty

Constructor Details

DOMBuilder

public DOMBuilder(Document document)

Creates a builder that appends newly created elements to the supplied document.

Parameters:

document - the target document to populate

DOMBuilder

public DOMBuilder(DocumentBuilder documentBuilder)

Creates a builder that lazily creates a backing document from the supplied document builder.

Parameters:

documentBuilder - the document builder used when a new document is required

Method Details

newInstance

public static DOMBuilder newInstance()
                              throws ParserConfigurationException

Creates a non-validating, namespace-aware DOM builder.

Returns:

a new DOM builder backed by a freshly created DocumentBuilder

Throws:

ParserConfigurationException - if the parser cannot be configured

newInstance

public static DOMBuilder newInstance(boolean validating,
 boolean namespaceAware)
                              throws ParserConfigurationException

Creates a DOM builder using the requested parser settings. The underlying parser does not allow DOCTYPE declarations.

Parameters:

validating - whether the parser should validate source documents

namespaceAware - whether the parser should be namespace aware

Returns:

a new DOM builder backed by a freshly created DocumentBuilder

Throws:

ParserConfigurationException - if the parser cannot be configured

See Also:

• newInstance(boolean, boolean, boolean)

newInstance

public static DOMBuilder newInstance(boolean validating,
 boolean namespaceAware,
 boolean allowDocTypeDeclaration)
                              throws ParserConfigurationException

Creates a DOM builder using the requested parser settings, including whether DOCTYPE declarations are permitted in parsed documents.

Parameters:

validating - whether the parser should validate source documents

namespaceAware - whether the parser should be namespace aware

allowDocTypeDeclaration - whether the parser should allow DOCTYPE declarations

Returns:

a new DOM builder backed by a freshly created DocumentBuilder

Throws:

ParserConfigurationException - if the parser cannot be configured

Since:

6.0.0

parse

public static Document parse(Reader reader)
                      throws SAXException,
IOException,
ParserConfigurationException

Creates a DocumentBuilder and uses it to parse the XML text read from the given reader. A non-validating, namespace aware parser which does not allow DOCTYPE declarations is used.

Parameters:

reader - the reader to read the XML text from

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.

ParserConfigurationException - if a DocumentBuilder cannot be created which satisfies the configuration requested.

See Also:

• parse(Reader, boolean, boolean)

parse

public static Document parse(Reader reader,
 boolean validating,
 boolean namespaceAware)
                      throws SAXException,
IOException,
ParserConfigurationException

Creates a DocumentBuilder and uses it to parse the XML text read from the given reader, allowing parser validation and namespace awareness to be controlled. Documents are not allowed to contain DOCYTYPE declarations.

Parameters:

reader - the reader to read the XML text from

validating - whether to validate the XML

namespaceAware - whether the parser should be namespace aware

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.

ParserConfigurationException - if a DocumentBuilder cannot be created which satisfies the configuration requested.

parse

public static Document parse(Reader reader,
 boolean validating,
 boolean namespaceAware,
 boolean allowDocTypeDeclaration)
                      throws SAXException,
IOException,
ParserConfigurationException

Creates a DocumentBuilder and uses it to parse the XML text read from the given reader, allowing parser validation, namespace awareness and permission of DOCTYPE declarations to be controlled.

Parameters:

reader - the reader to read the XML text from

validating - whether to validate the XML

namespaceAware - whether the parser should be namespace aware

allowDocTypeDeclaration - whether the parser should allow DOCTYPE declarations

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.

ParserConfigurationException - if a DocumentBuilder cannot be created which satisfies the configuration requested.

parseText

public Document parseText(String text)
                   throws SAXException,
IOException,
ParserConfigurationException

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.

ParserConfigurationException - if a DocumentBuilder cannot be created which satisfies the configuration requested.

See Also:

• parse(Reader)

setParent

protected void setParent(Object parent,
 Object child)

Builder lifecycle callback that attaches a completed child node to its parent node.

Specified by:

setParent in class BuilderSupport

Parameters:

parent - the parent Node

child - the child Node to append

createNode

protected Object createNode(Object name)

Builder lifecycle callback that creates an element for the supplied node name.

Specified by:

createNode in class BuilderSupport

Parameters:

name - the node name, either a QName or plain element name

Returns:

the created Element

createDocument

protected Document createDocument()

Creates the backing document used by subsequent builder callbacks. Subclasses may override to supply a custom document implementation.

Returns:

a new document ready to receive builder output

Throws:

IllegalArgumentException - if no DocumentBuilder is available

createNode

protected Object createNode(Object name,
 Object value)

Builder lifecycle callback that creates an element and adds text content to it.

Specified by:

createNode in class BuilderSupport

Parameters:

name - the node name, either a QName or plain element name

value - the text value to append

Returns:

the created Element

createNode

protected Object createNode(Object name,
 Map attributes,
 Object value)

Builder lifecycle callback that creates an element, applies attributes and adds text content.

Specified by:

createNode in class BuilderSupport

Parameters:

name - the node name, either a QName or plain element name

attributes - the attributes to apply to the created element

value - the text value to append

Returns:

the created Element

createNode

protected Object createNode(Object name,
 Map attributes)

Builder lifecycle callback that creates an element and applies the supplied attributes.

Specified by:

createNode in class BuilderSupport

Parameters:

name - the node name, either a QName or plain element name

attributes - the attributes to apply, including namespace declarations

Returns:

the created Element

appendNamespaceAttributes

protected void appendNamespaceAttributes(Element element,
 Map<Object,Object> attributes)

Applies namespace declaration attributes from an xmlns map to the supplied element.

Parameters:

element - the element receiving namespace attributes

attributes - the namespace attributes keyed by prefix or QName

Throws:

IllegalArgumentException - if an entry has a null value or an unsupported key type