marytts.util.dom

Class DomUtils

java.lang.Object

marytts.util.dom.DomUtils

Direct Known Subclasses:

MaryDomUtils

public class DomUtils
extends Object

A collection of utilities for DOM manipulation or analysis. No object of class DomUtils is created, all methods are static.

Author:

Marc Schröder, Sathish and Ingmar

Field Summary

Fields

Modifier and Type	Field and Description
protected static DocumentBuilderFactory	factory
protected static org.apache.log4j.Logger	logger
protected static DocumentBuilderFactory	validatingFactory

Constructor Summary

Constructors

Constructor and Description
DomUtils()

Method Summary

Methods

Modifier and Type	Method and Description
static Element	closestCommonAncestor(Node first, Node last)
static void	compareNodes(Node expected, Node actual, boolean trimEmptyTextNodes) Compare two DOM trees.
static org.w3c.dom.traversal.NodeIterator	createNodeIterator(Document doc, Node root, String... tagNames)
static org.w3c.dom.traversal.NodeIterator	createNodeIterator(Node root, String... tagNames)
static org.w3c.dom.traversal.TreeWalker	createTreeWalker(Document doc, Node root, String... tagNames)
static org.w3c.dom.traversal.TreeWalker	createTreeWalker(Node root, String... tagNames)
static void	document2File(Document document, File file) Write a DOM document into a file.
static void	document2Stream(Document document, OutputStream target) Write a DOM document into an output stream.
static String	document2String(Document document) Write a DOM document into a string.
static Element	encloseNodesWithNewElement(Node first, Node last, String newElementName) Create a new Element placed in the document tree such that it encloses two existing Nodes.
static Node	getAncestor(Node node, String ancestorName) If node has an ancestor with name ancestorName, return that ancestor.
static Node	getAncestor(Node node, String[] ancestorNames) If node has an ancestor with one of the names in ancestorNames, return the closest of these ancestors.
static String	getAttributeFromClosestAncestorOfAnyKind(Node node, String attributeName) Climb through node's ancestors, looking for one with an attribute named attributeName, irrespective of the respective ancestorName, and return the attribute's value
static Element	getClosestAncestorWithAttribute(Node node, String ancestorName, String attributeName) Search upwards through the ancestors of node with name ancestorName, and return the first ancestor for which an attribute named attributeName is present.
static Element	getFirstChildElement(Element e) Get the first child of e which is an element, or null if there is no such element.
static Element	getFirstElementByTagName(Node n, String name) Get the first child element with the given tag name, or null if there is no such element.
static Node	getHighestLevelAncestor(Node node, String ancestorName) If node has ancestors with name ancestorName, return the one closest to the root.
static Element	getLastChildElement(Element e) Get the last child of e which is an element, or null if there is no such element.
static Element	getLastElementByTagName(Element e, String name) Get the last descendant element with the given tag name, or null if there is no such element.
static Element	getNextOfItsKindIn(Element element, Element root) Find the Element with the same tag name as element following element within the same subtree under root.
static Element	getNextSiblingElement(Element e) Get the next sibling of e which is an element, or null if there is no such element.
static Element	getNextSiblingElementByTagName(Element e, String name) Get the next sibling of e which is an element and has tag name name, or null if there is no such element.
static List<Node>	getNodeListAsList(NodeList nl)
static String	getPlainTextBelow(Node n) Return the concatenation of the values of all text nodes below the given node.
static Element	getPreviousOfItsKindIn(Element element, Element root) Find the Element with the same tag name as element preceding element within the same subtree under root.
static Element	getPreviousSiblingElement(Element e) Get the previous sibling of e which is an element, or null if there is no such element.
static Element	getPreviousSiblingElementByTagName(Element e, String name) Get the previous sibling of e which is an element and has tag name name, or null if there is no such element.
static boolean	hasAncestor(Node node, String ancestorName) Verify if node has an ancestor with name ancestorName
static void	insertAfter(Node newNode, Node refNode) Analogous to the Node.insertBefore() method, insert a newNode after a refNode.
static boolean	isAncestor(Node ancestor, Node node) Verify if ancestor is an ancestor of node
static boolean	isFirstOfItsKindIn(Node node, Node ancestor)
static boolean	isFirstOfItsKindIn(Node node, String ancestorName)
static boolean	isLastOfItsKindIn(Node node, Node ancestor)
static boolean	isLastOfItsKindIn(Node node, String ancestorName)
static Document	parseDocument(File file) DOM-parse the given input data.
static Document	parseDocument(File file, boolean validating) Parse XML data into a DOM representation, taking local resources and Schemas into account.
static Document	parseDocument(InputStream inputData) DOM-parse the given input data.
static Document	parseDocument(InputStream is, boolean validating) Parse XML data into a DOM representation, taking local resources and Schemas into account.
static Document	parseDocument(Reader inputData) DOM-parse the given input data.
static Document	parseDocument(Reader inputData, boolean validating) Parse XML data into a DOM representation, taking local resources and Schemas into account.
static Document	parseDocument(String inputData) DOM-parse the given input data.
static Document	parseDocument(String inputData, boolean validating) Parse XML data into a DOM representation, taking local resources and Schemas into account.
static void	replaceElement(Element oldElement, NodeList newNodes)
static String	serializeToString(Document doc) Serialize a Document to a String.
static void	trimAllTextNodes(Node root) Go through all text nodes below this node, and replace their text with a trimmed version of their text.
static void	trimEmptyTextNodes(Node node) Remove any empty text nodes below node.

Methods inherited from class java.lang.Object

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

Field Detail

factory

protected static DocumentBuilderFactory factory

validatingFactory

protected static DocumentBuilderFactory validatingFactory

logger

protected static org.apache.log4j.Logger logger

Constructor Detail

DomUtils

public DomUtils()

Method Detail

parseDocument

public static Document parseDocument(String inputData,
                     boolean validating)
                              throws ParserConfigurationException,
                                     SAXException,
                                     IOException

Parse XML data into a DOM representation, taking local resources and Schemas into account.

Parameters:

inputData - a string representation of the XML data to be parsed.

validating - whether to Schema-validate the XML data

Returns:

the DOM document resulting from the parse

Throws:

ParserConfigurationException - if no parser could be created

SAXException - if there was a parse error

IOException - if there was a problem reading from the string

parseDocument

public static Document parseDocument(Reader inputData,
                     boolean validating)
                              throws ParserConfigurationException,
                                     SAXException,
                                     IOException

Parse XML data into a DOM representation, taking local resources and Schemas into account.

Parameters:

inputData - a reader from which the XML data is to be read.

validating - whether to Schema-validate the XML data

Returns:

the DOM document resulting from the parse

Throws:

ParserConfigurationException - if no parser could be created

SAXException - if there was a parse error

IOException - if there was a problem reading from the reader

parseDocument

public static Document parseDocument(File file,
                     boolean validating)
                              throws ParserConfigurationException,
                                     SAXException,
                                     IOException

Parse XML data into a DOM representation, taking local resources and Schemas into account.

Parameters:

file - a file from which the XML data is to be read.

validating - whether to Schema-validate the XML data

Returns:

the DOM document resulting from the parse

Throws:

ParserConfigurationException - if no parser could be created

SAXException - if there was a parse error

IOException - if there was a problem reading from the file

parseDocument

public static Document parseDocument(InputStream is,
                     boolean validating)
                              throws ParserConfigurationException,
                                     SAXException,
                                     IOException

Parse XML data into a DOM representation, taking local resources and Schemas into account.

Parameters:

is - an input stream from which the XML data is to be read.

validating - whether to Schema-validate the XML data

Returns:

the DOM document resulting from the parse

Throws:

ParserConfigurationException - if no parser could be created

SAXException - if there was a parse error

IOException - if there was a problem reading from the stream

parseDocument

public static Document parseDocument(String inputData)
                              throws ParserConfigurationException,
                                     SAXException,
                                     IOException

DOM-parse the given input data. Namespace-aware but non-validating.

Parameters:

inputData - inputData

Returns:

parseDocument(inputData, false)

Throws:

ParserConfigurationException - ParserConfigurationException

SAXException - SAXException

IOException - IOException

parseDocument

public static Document parseDocument(Reader inputData)
                              throws ParserConfigurationException,
                                     SAXException,
                                     IOException

DOM-parse the given input data. Namespace-aware but non-validating.

Parameters:

inputData - inputData

Returns:

parseDocument(inputData, false)

Throws:

ParserConfigurationException - ParserConfigurationException

SAXException - SAXException

IOException - IOException

parseDocument

public static Document parseDocument(File file)
                              throws ParserConfigurationException,
                                     SAXException,
                                     IOException

DOM-parse the given input data. Namespace-aware but non-validating.

Parameters:

file - file

Returns:

parseDocument(file, false)

Throws:

ParserConfigurationException - ParserConfigurationException

SAXException - SAXException

IOException - IOException

parseDocument

public static Document parseDocument(InputStream inputData)
                              throws ParserConfigurationException,
                                     SAXException,
                                     IOException

DOM-parse the given input data. Namespace-aware but non-validating.

Parameters:

inputData - inputData

Returns:

parseDocument(inputData, false)

Throws:

ParserConfigurationException - ParserConfigurationException

SAXException - SAXException

IOException - IOException

isAncestor

public static boolean isAncestor(Node ancestor,
                 Node node)

Verify if ancestor is an ancestor of node

Parameters:

ancestor - ancestor

node - node

Returns:

true if ancestor equals to p, false otherwise

hasAncestor

public static boolean hasAncestor(Node node,
                  String ancestorName)

Verify if node has an ancestor with name ancestorName

Parameters:

node - node

ancestorName - ancestorName

Returns:

true if p.getNodeName equals ancestorName, false otherwise

getAncestor

public static Node getAncestor(Node node,
               String ancestorName)

If node has an ancestor with name ancestorName, return that ancestor. Else return null.

Parameters:

node - node

ancestorName - ancestorName

Returns:

p if p.getNodeName equals ancestorName

getAncestor

public static Node getAncestor(Node node,
               String[] ancestorNames)

If node has an ancestor with one of the names in ancestorNames, return the closest of these ancestors. Else return null.

Parameters:

node - node

ancestorNames - ancestorNames

Returns:

closestAncestor

getClosestAncestorWithAttribute

public static Element getClosestAncestorWithAttribute(Node node,
                                      String ancestorName,
                                      String attributeName)

Search upwards through the ancestors of node with name ancestorName, and return the first ancestor for which an attribute named attributeName is present. Return null if no such ancestor exists.

Parameters:

node - node

ancestorName - ancestorName

attributeName - attributeName

Returns:

(Element) a

getAttributeFromClosestAncestorOfAnyKind

public static String getAttributeFromClosestAncestorOfAnyKind(Node node,
                                              String attributeName)

Climb through node's ancestors, looking for one with an attribute named attributeName, irrespective of the respective ancestorName, and return the attribute's value

Parameters:

node - node

attributeName - attributeName

Returns:

value of attribute from closest ancestor with that attribute, or the empty string if no ancestor has that attribute.

getHighestLevelAncestor

public static Node getHighestLevelAncestor(Node node,
                           String ancestorName)

If node has ancestors with name ancestorName, return the one closest to the root. If there is no ancestor with that name, return null.

Parameters:

node - node

ancestorName - ancestorName

Returns:

highest

getNextSiblingElement

public static Element getNextSiblingElement(Element e)

Get the next sibling of e which is an element, or null if there is no such element.

Parameters:

e - e

Returns:

null if n is e, true otherwise

getPreviousSiblingElement

public static Element getPreviousSiblingElement(Element e)

Get the previous sibling of e which is an element, or null if there is no such element.

Parameters:

e - e

Returns:

null if n is null, true otherwise

getNextSiblingElementByTagName

public static Element getNextSiblingElementByTagName(Element e,
                                     String name)

Get the next sibling of e which is an element and has tag name name, or null if there is no such element.

Parameters:

e - e

name - name

Returns:

null if n is null, true otherwise

getPreviousSiblingElementByTagName

public static Element getPreviousSiblingElementByTagName(Element e,
                                         String name)

Get the previous sibling of e which is an element and has tag name name, or null if there is no such element.

Parameters:

e - e

name - name

Returns:

null if n is null

getFirstChildElement

public static Element getFirstChildElement(Element e)

Get the first child of e which is an element, or null if there is no such element.

Parameters:

e - e

Returns:

n

getLastChildElement

public static Element getLastChildElement(Element e)

Get the last child of e which is an element, or null if there is no such element.

Parameters:

e - e

Returns:

n

getFirstElementByTagName

public static Element getFirstElementByTagName(Node n,
                               String name)

Get the first child element with the given tag name, or null if there is no such element.

Parameters:

n - n

name - name

Returns:

tx.nextNode

getLastElementByTagName

public static Element getLastElementByTagName(Element e,
                              String name)

Get the last descendant element with the given tag name, or null if there is no such element.

Parameters:

e - e

name - name

Returns:

previous

isFirstOfItsKindIn

public static boolean isFirstOfItsKindIn(Node node,
                         String ancestorName)

isFirstOfItsKindIn

public static boolean isFirstOfItsKindIn(Node node,
                         Node ancestor)

isLastOfItsKindIn

public static boolean isLastOfItsKindIn(Node node,
                        String ancestorName)

isLastOfItsKindIn

public static boolean isLastOfItsKindIn(Node node,
                        Node ancestor)

getPreviousOfItsKindIn

public static Element getPreviousOfItsKindIn(Element element,
                             Element root)

Find the Element with the same tag name as element preceding element within the same subtree under root. Precondition: root must be an ancestor of element.

Parameters:

element - element

root - root

Returns:

that Element, or null if there is no such Element.

getNextOfItsKindIn

public static Element getNextOfItsKindIn(Element element,
                         Element root)

Find the Element with the same tag name as element following element within the same subtree under root. Precondition: root must be an ancestor of element.

Parameters:

element - element

root - root

Returns:

that Element, or null if there is no such Element.

closestCommonAncestor

public static Element closestCommonAncestor(Node first,
                            Node last)

encloseNodesWithNewElement

public static Element encloseNodesWithNewElement(Node first,
                                 Node last,
                                 String newElementName)

Create a new Element placed in the document tree such that it encloses two existing Nodes. The new element will have the same namespace as the document element.

Algorithm:

1. Find closest common ancestor a
2. Identify first (childA) and last (childZ) of a's children that need to be enclosed by the new Element
3. Insert a new Element node before the first of these children
4. Move all children between childA and childZ into the new Element.

Parameters:

first - first

last - last

newElementName - new element name

Returns:

The new element, or null if it could not be created.

getNodeListAsList

public static List<Node> getNodeListAsList(NodeList nl)

getPlainTextBelow

public static String getPlainTextBelow(Node n)

Return the concatenation of the values of all text nodes below the given node. One space character is inserted between adjacent text nodes.

Parameters:

n - n

Returns:

null if n is null

insertAfter

public static void insertAfter(Node newNode,
               Node refNode)
                        throws DOMException

Analogous to the Node.insertBefore() method, insert a newNode after a refNode.

Parameters:

newNode - new node

refNode - ref node

Throws:

DOMException - DOMException

trimAllTextNodes

public static void trimAllTextNodes(Node root)

Go through all text nodes below this node, and replace their text with a trimmed version of their text. This changes the DOM document.

Parameters:

root - root

serializeToString

public static String serializeToString(Document doc)

Serialize a Document to a String.

Parameters:

doc - doc

Returns:

string

document2String

public static String document2String(Document document)
                              throws MaryConfigurationException

Write a DOM document into a string.

Parameters:

document - the document to be written

Returns:

the string containing the DOM document

Throws:

MaryConfigurationException - if the DOM document cannot be serialized

document2File

public static void document2File(Document document,
                 File file)
                          throws MaryConfigurationException,
                                 IOException

Write a DOM document into a file.

Parameters:

document - the document to be written

file - where to write it.

Throws:

MaryConfigurationException - if the DOM document cannot be serialized

IOException - if there is a problem accessing the file

document2Stream

public static void document2Stream(Document document,
                   OutputStream target)
                            throws MaryConfigurationException

Write a DOM document into an output stream.

Parameters:

document - the document to be written

target - where to write it.

Throws:

MaryConfigurationException - if the DOM document cannot be serialized

replaceElement

public static void replaceElement(Element oldElement,
                  NodeList newNodes)

createTreeWalker

public static org.w3c.dom.traversal.TreeWalker createTreeWalker(Document doc,
                                                Node root,
                                                String... tagNames)

createTreeWalker

public static org.w3c.dom.traversal.TreeWalker createTreeWalker(Node root,
                                                String... tagNames)

createNodeIterator

public static org.w3c.dom.traversal.NodeIterator createNodeIterator(Document doc,
                                                    Node root,
                                                    String... tagNames)

createNodeIterator

public static org.w3c.dom.traversal.NodeIterator createNodeIterator(Node root,
                                                    String... tagNames)

trimEmptyTextNodes

public static void trimEmptyTextNodes(Node node)

Remove any empty text nodes below node. Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Parameters:

node - the node below which to trim.

compareNodes

public static void compareNodes(Node expected,
                Node actual,
                boolean trimEmptyTextNodes)
                         throws Exception

Compare two DOM trees. if they are not equal, throw an exception providing a description of the the reason why they differ. Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Parameters:

expected - expected

actual - actual

trimEmptyTextNodes - whether or not to remove any empty text nodes

Throws:

Exception - Exception