Package com.mediaworx.xmlutils

Class XmlHelper

java.lang.Object

com.mediaworx.xmlutils.XmlHelper

public class XmlHelper
extends Object

Class used to create helper objects that simplify parsing and modifying XML files. To retrieve single nodes or multiple nodes from the XML XPath is used, see the Java API documentation on XPath for more information.

Author:

Kai Widmann, mediaworx Berlin AG

Field Summary

Fields

Modifier and Type	Field	Description
static final String	DEFAULT_ENCODING	Default encoding that is used if no encoding is given

Constructor Summary

Constructors

Constructor	Description
XmlHelper()	Creates and initializes a new XmlHelper instance.

Method Summary

Modifier and Type	Method	Description
void	appendFileAsNode(Node parent, String newChildFilePath, Map<String,String> replacements)	parses and appends the content of a file as a child node to the given parent node
void	appendNode(Node parent, Node newChild)	Appends a new child node to a parent node.
static void	cleanEmptyTextNodes(Node parentNode)	Removes text nodes that are empty or contain whitespace only if the parent node has at least one child of any of the following types: ELEMENT, CDATA, COMMENT.
int	getIntValueForXpath(Node ancestorNode, String xPath)	Retrieves the content of the node at the given XPath as int.
NodeList	getNodeListForXPath(Node ancestorNode, String xPath)	Retrieves the NodeList for the given XPath from the given ancestor Node.
Node	getSingleNodeForXPath(Node ancestorNode, String xPath)	Retrieves a single node at a given XPath from the given ancestor node.
String	getStringValueForXpath(Node ancestorNode, String xPath)	Retrieves the String content of a node at the given XPath.
String	getXmlStringFromDocument(Document document, String[] cdataElements)	Converts the document to a formatted XML String (indentation level is 4) using default encoding (UTF-8).
String	getXmlStringFromDocument(Document document, String[] cdataElements, String encoding)	Converts the document to a formatted XML String (indentation level is 4) using the given encoding.
Document	parseFile(File file)	Parses the XML content of the file at the given path using the default encoding (UTF-8).
Document	parseFile(File file, Map<String,String> replacements)	Parses the XML content of the file at the given path using the default encoding (UTF-8).
Document	parseFile(File file, Map<String,String> replacements, String encoding)	Parses the XML content of the file at the given path using the default encoding (UTF-8).
Document	parseFile(String path)	Parses the XML content of the file at the given path using the default encoding (UTF-8).
Document	parseFile(String path, Map<String,String> replacements)	Parses the XML content of the file at the given path using the default encoding (UTF-8).
Document	parseFile(String path, Map<String,String> replacements, String encoding)	Parses the XML content of the file at the given path using the given encoding.

Methods inherited from class java.lang.Object

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

Field Details

DEFAULT_ENCODING

public static final String DEFAULT_ENCODING

Default encoding that is used if no encoding is given

See Also:

• Constant Field Values

Constructor Details

XmlHelper

public XmlHelper()
          throws ParserConfigurationException

Creates and initializes a new XmlHelper instance.

Throws:

ParserConfigurationException - if for some reason the DocumentBuilder used to parse the XML can't be initialized

Method Details

parseFile

public Document parseFile(String path)
                   throws IOException,
SAXException

Parses the XML content of the file at the given path using the default encoding (UTF-8). Empty text nodes or text noes containing whitespace only are removed.

Parameters:

path - the XML file's path

Returns:

the parsed XML document

Throws:

IOException - if there's a problem accessing the file

SAXException - if the file content can't be parsed

parseFile

public Document parseFile(String path,
 Map<String,String> replacements)
                   throws IOException,
SAXException

Parses the XML content of the file at the given path using the default encoding (UTF-8). Empty text nodes or text noes containing whitespace only are removed. If a replacement map is provided, each key in the map is replaced by the corresponding value in the file's content.

Parameters:

path - the XML file's path

replacements - Map containing replacement strings, key: string to be replaced, value: replacement string (if the map is null, no replacements are made)

Returns:

the parsed XML document

Throws:

IOException - if there's a problem accessing the file

SAXException - if the file content can't be parsed

parseFile

public Document parseFile(String path,
 Map<String,String> replacements,
 String encoding)
                   throws IOException,
SAXException

Parses the XML content of the file at the given path using the given encoding. Empty text nodes or text noes containing whitespace only are removed. If a replacement map is provided, each key in the map is replaced by the corresponding value in the file's content.

Parameters:

path - the XML file's path

replacements - Map containing replacement strings, key: string to be replaced, value: replacement string (if the map is null, no replacements are made)

encoding - the encoding to be used to parse the file (must be a valid encoding like "UTF-8")

Returns:

the parsed XML document

Throws:

IOException - if there's a problem accessing the file

SAXException - if the file content can't be parsed

parseFile

public Document parseFile(File file)
                   throws IOException,
SAXException

Parses the XML content of the file at the given path using the default encoding (UTF-8). Empty text nodes or text noes containing whitespace only are removed.

Parameters:

file - the file containing the XML

Returns:

the parsed XML document

Throws:

IOException - if there's a problem accessing the file

SAXException - if the file content can't be parsed

parseFile

public Document parseFile(File file,
 Map<String,String> replacements)
                   throws IOException,
SAXException

Parses the XML content of the file at the given path using the default encoding (UTF-8). Empty text nodes or text noes containing whitespace only are removed. If a replacement map is provided, each key in the map is replaced by the corresponding value in the file's content.

Parameters:

file - the file containing the XML

replacements - Map containing replacement strings, key: string to be replaced, value: replacement string (if the map is null, no replacements are made)

Returns:

the parsed XML document

Throws:

IOException - if there's a problem accessing the file

SAXException - if the file content can't be parsed

parseFile

public Document parseFile(File file,
 Map<String,String> replacements,
 String encoding)
                   throws IOException,
SAXException

Parses the XML content of the file at the given path using the default encoding (UTF-8). Empty text nodes or text nodes containing whitespace only are removed. If a replacement map is provided, each key in the map is replaced by the corresponding value in the file's content.

Parameters:

file - the file containing the XML

replacements - Map containing replacement strings, key: string to be replaced, value: replacement string (if the map is null, no replacements are made)

encoding - the encoding to be used to parse the file (must be a valid encoding like "UTF-8")

Returns:

the parsed XML document

Throws:

IOException - if there's a problem accessing the file

SAXException - if the file content can't be parsed

getNodeListForXPath

public NodeList getNodeListForXPath(Node ancestorNode,
 String xPath)
                             throws XPathExpressionException

Retrieves the NodeList for the given XPath from the given ancestor Node.

Parameters:

ancestorNode - the node from which the NodeList is to be read

xPath - the XPath (relative to the ancestor node)

Returns:

the NodeList for the given XPath

Throws:

XPathExpressionException - if the given XPath can't be evaluated (e.g. because it does not exist)

getSingleNodeForXPath

public Node getSingleNodeForXPath(Node ancestorNode,
 String xPath)
                           throws XPathExpressionException

Retrieves a single node at a given XPath from the given ancestor node.

Parameters:

ancestorNode - the node from which the Node is to be read

xPath - the XPath (relative to the ancestor node)

Returns:

the Node for the given XPath

Throws:

XPathExpressionException - if the given XPath can't be evaluated (e.g. because it does not exist or because it does not point to a single node)

getStringValueForXpath

public String getStringValueForXpath(Node ancestorNode,
 String xPath)
                              throws XPathExpressionException

Retrieves the String content of a node at the given XPath.

Parameters:

ancestorNode - the parent node from which the Node content is to be read

xPath - the XPath (relative to the ancestor node)

Returns:

the String content of the node at the given XPath

Throws:

XPathExpressionException - if the given XPath can't be evaluated (e.g. because it does not exist or because it does not point to a single node)

getIntValueForXpath

public int getIntValueForXpath(Node ancestorNode,
 String xPath)
                        throws XPathExpressionException,
NumberFormatException

Retrieves the content of the node at the given XPath as int.

Parameters:

ancestorNode - the parent node from which the Node content is to be read

xPath - the XPath (relative to the ancestor node)

Returns:

the content of the node at the given XPath as int

Throws:

XPathExpressionException - if the given XPath can't be evaluated (e.g. because it does not exist or because it does not point to a single node)

NumberFormatException - if the content of the node at the XPath can't be converted to int

appendNode

public void appendNode(Node parent,
 Node newChild)

Appends a new child node to a parent node.

Parameters:

parent - the parent node

newChild - the child node to be appended

appendFileAsNode

public void appendFileAsNode(Node parent,
 String newChildFilePath,
 Map<String,String> replacements)
                      throws IOException,
SAXException

parses and appends the content of a file as a child node to the given parent node

Parameters:

parent - the parent node

newChildFilePath - the path to the file whose content is to be added as a child node

replacements - Map containing replacement strings, key: string to be replaced, value: replacement string

Throws:

IOException - if there's a problem accessing the file

SAXException - if the file can't be parsed

getXmlStringFromDocument

public String getXmlStringFromDocument(Document document,
 String[] cdataElements)

Converts the document to a formatted XML String (indentation level is 4) using default encoding (UTF-8).

Parameters:

document - The document to be converted to String

cdataElements - String array containing the names of all elements that are to be added within CDATA sections

Returns:

the String representation of the given Document

getXmlStringFromDocument

public String getXmlStringFromDocument(Document document,
 String[] cdataElements,
 String encoding)

Converts the document to a formatted XML String (indentation level is 4) using the given encoding.

Parameters:

document - The document to be converted to String

cdataElements - String array containing the names of all elements that are to be added within CDATA sections

encoding - encoding to be used (added in the XML declaration)

Returns:

the String representation of the given Document

cleanEmptyTextNodes

public static void cleanEmptyTextNodes(Node parentNode)

Removes text nodes that are empty or contain whitespace only if the parent node has at least one child of any of the following types: ELEMENT, CDATA, COMMENT. This is used to improve the XML format when using a transformer to do the formatting (whitespace nodes are interfering with indentation and line breaks). This method was modeled after a method by "user2401669" found on StackOverflow.