org.dmonix.xml
Class XMLUtil

java.lang.Object
  org.dmonix.xml.XMLUtil

Direct Known Subclasses:

HTMLGenerator

public class XMLUtil

extends java.lang.Object

XML utility class.
The class provides functionality for easy management of XML data

Copyright: Copyright (c) 2003

Company: dmonix.org

Version:

1.0

Author:

Peter Nerg

Constructor Summary

XMLUtil()

Method Summary

static org.w3c.dom.Element	appendChildElement(org.w3c.dom.Document doc, org.w3c.dom.Element element, java.lang.String elementName) Append a child element to the given element.
static org.w3c.dom.Element	appendChildElement(org.w3c.dom.Document doc, org.w3c.dom.Element element, java.lang.String elementName, java.lang.String elementValue) Append a child element with a single text node to the given element.
static void	appendChildElement(org.w3c.dom.Document doc, java.lang.String name, java.lang.String value) Append an element with a text node to the given document root.
static void	documentToFile(org.w3c.dom.Document doc, java.io.File file) Writes the document to a file.
static void	documentToFile(org.w3c.dom.Document doc, java.lang.String file) Writes the document to a file.
static java.util.Hashtable	documentToHashtable(org.w3c.dom.Document doc) Converts the input document into a Hashtable.
static void	documentToStream(org.w3c.dom.Document doc, java.io.OutputStream ostream) Writes the document to a given outputstream.
static void	documentToStream(org.w3c.dom.Document doc, java.io.OutputStream ostream, boolean closeStream) Writes the document to a given outputstream.
static java.lang.String	documentToString(org.w3c.dom.Document doc) Gets the string representation of an XML document.
static void	documentToWriter(org.w3c.dom.Document doc, java.io.Writer writer) Writes the document to a given writer.
static org.w3c.dom.Element	getChildElementByTagName(org.w3c.dom.Element parent, java.lang.String name) Returns the first occurens of a child element whith a specific name.
static org.w3c.dom.Element	getCreateChildElementByTagName(org.w3c.dom.Element el, java.lang.String name) Get the first occurence of an element with a specified name, if a element with the specified name can't be found it will be created.
static org.w3c.dom.Document	getDocument(java.io.File file) Parse an XML document from a file.
static org.w3c.dom.Document	getDocument(org.xml.sax.InputSource is) Parse an XML document from a file.
static org.w3c.dom.Document	getDocument(java.io.InputStream istream) Parse an XML document from an input stream.
static org.w3c.dom.Document	getDocument(java.lang.String path) Parse an XML document from a file.
static org.w3c.dom.Document	getDocument(java.net.URL url) Parse an XML document from a URL.
static org.w3c.dom.Element	getElement(org.w3c.dom.NodeList list) Returns the first element if it exist and null if it does not exist.
static org.w3c.dom.Element	getElement(org.w3c.dom.Node node, java.lang.String path)
static java.lang.String	getElementValue(org.w3c.dom.Element element) Get the value of the element.
static java.lang.String	getElementValue(org.w3c.dom.Element element, java.lang.String defaultValue) Get the value of the element.
static java.lang.String	getElementValue(org.w3c.dom.NodeList list) Get the node value from the first element in the node list.
static java.lang.String	getElementValue(org.w3c.dom.NodeList list, java.lang.String defaultValue) Get the node value from the first element in the node list.
static java.lang.String	getFirstParameterValue(org.w3c.dom.Document doc, java.lang.String name) Returns the value of the first <Paramter> element that has an name attribute maching the supplied parameter.
static java.lang.String	getFirstParameterValue(org.w3c.dom.Element parent, java.lang.String name) Returns the value of the first <Paramter> element that has an name attribute maching the supplied parameter.
static org.w3c.dom.Element[]	getParameters(org.w3c.dom.Document doc, java.lang.String name) Returns an array with all child <Parameter> elements that have a name matching the given parameter value.
static org.w3c.dom.Element[]	getParameters(org.w3c.dom.Element parent, java.lang.String name) Returns an array with all child <Parameter> elements that have a name matching the given parameter value.
static java.lang.String	getTransformerProperty(java.lang.String name) Gets a property for the XML transformer.
static boolean	isBlank(java.lang.String value) Checks if a node value is blank (contains only white spaces).
static org.w3c.dom.Document	loadFromResource(java.lang.String path) Load an XML document from a resource.
static org.w3c.dom.Document	newDocument() Creates a new empty XML document.
static org.w3c.dom.Document	newDocument(java.lang.String s) Creates a new XML document out of the provided string.
static void	nodeToStream(org.w3c.dom.Node node, java.io.OutputStream ostream) Writes the XML node to a given outputstream.
static java.lang.String	nodeToString(org.w3c.dom.Node node) Gets the string representation of an XML node.
static void	nodeToWriter(org.w3c.dom.Node node, java.io.Writer writer) Writes the XML node to a given writer.
static void	normalizeDocument(org.w3c.dom.Node node) Recursively removes all empty child text nodes.
static void	removeAllChildElements(org.w3c.dom.Element element) Removes all child elements to the given element
static void	saveToFile(org.w3c.dom.Document doc, java.io.File file) Save the specified document to file.
static void	saveToFile(org.w3c.dom.Document doc, java.lang.String path) Save the specified document to file.
static void	setElementValue(org.w3c.dom.Element el, java.lang.String value) Set the value of an element.
static org.w3c.dom.Element	setRootElement(org.w3c.dom.Document doc, java.lang.String elementName) Creates a new root element for the document.
static void	setTransformerProperty(java.lang.String name, java.lang.String value) Sets a property for the XML transformer.

Methods inherited from class java.lang.Object

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

Constructor Detail

XMLUtil

public XMLUtil()

Method Detail

newDocument

public static org.w3c.dom.Document newDocument()

Creates a new empty XML document.

Returns:

the document

newDocument

public static org.w3c.dom.Document newDocument(java.lang.String s)
                                        throws java.io.IOException,
                                               org.xml.sax.SAXException

Creates a new XML document out of the provided string.

Parameters:

s - The string to parse

Returns:

the document

Throws:

java.io.IOException

org.xml.sax.SAXException

nodeToStream

public static void nodeToStream(org.w3c.dom.Node node,
                                java.io.OutputStream ostream)
                         throws java.io.IOException,
                                javax.xml.transform.TransformerException

Writes the XML node to a given outputstream.

Parameters:

node - The node

ostream - The target stream

Throws:

java.io.IOException

javax.xml.transform.TransformerException

nodeToString

public static java.lang.String nodeToString(org.w3c.dom.Node node)

Gets the string representation of an XML node. The resulting string is trimmed to remove redundant white spaces from the beginning and end of the string.

Parameters:

node - The node

Returns:

The string representation of the node, null if an error occurred

See Also:

documentToWriter(Document, Writer)

nodeToWriter

public static void nodeToWriter(org.w3c.dom.Node node,
                                java.io.Writer writer)
                         throws java.io.IOException,
                                javax.xml.transform.TransformerException

Writes the XML node to a given writer.

Parameters:

node - The node

writer - The target writer

Throws:

java.io.IOException

javax.xml.transform.TransformerException

normalizeDocument

public static void normalizeDocument(org.w3c.dom.Node node)

Recursively removes all empty child text nodes.
The method will also trim the non empty text nodes, i.e. any white spaces in the beginning and the end of the text node will be removed.

Parameters:

node - The node to normalize

setRootElement

public static org.w3c.dom.Element setRootElement(org.w3c.dom.Document doc,
                                                 java.lang.String elementName)

Creates a new root element for the document.
Any existing root element will be overwritten, thus descarding any previous data in the document.

Parameters:

doc - the document to which to append the root element

elementName - the name of the root element

Returns:

the created root element

setTransformerProperty

public static void setTransformerProperty(java.lang.String name,
                                          java.lang.String value)

Sets a property for the XML transformer.

Parameters:

name - Property name

value - Property value

See Also:

OutputKeys

getTransformerProperty

public static java.lang.String getTransformerProperty(java.lang.String name)

Gets a property for the XML transformer.

Parameters:

name - Property name

Returns:

The value of the requested property

See Also:

OutputKeys

getCreateChildElementByTagName

public static org.w3c.dom.Element getCreateChildElementByTagName(org.w3c.dom.Element el,
                                                                 java.lang.String name)

Get the first occurence of an element with a specified name, if a element with the specified name can't be found it will be created.

Parameters:

el - the parent element

name - the name of the child element

Returns:

a childe element with the name

getChildElementByTagName

public static org.w3c.dom.Element getChildElementByTagName(org.w3c.dom.Element parent,
                                                           java.lang.String name)

Returns the first occurens of a child element whith a specific name.

Parameters:

parent - the parent element

name - the name of the child element to look for

Returns:

the first occurenc of the the name

getElement

public static org.w3c.dom.Element getElement(org.w3c.dom.NodeList list)

Returns the first element if it exist and null if it does not exist.

Parameters:

list - the list

Returns:

the first element in the list

getElement

public static org.w3c.dom.Element getElement(org.w3c.dom.Node node,
                                             java.lang.String path)

Parameters:

node - -

path - -

Returns:

-

appendChildElement

public static org.w3c.dom.Element appendChildElement(org.w3c.dom.Document doc,
                                                     org.w3c.dom.Element element,
                                                     java.lang.String elementName,
                                                     java.lang.String elementValue)

Append a child element with a single text node to the given element.

Parameters:

doc - the document

element - the element to append the child to

elementName - the name of the element

elementValue - the value of the element

Returns:

the appended child element

appendChildElement

public static org.w3c.dom.Element appendChildElement(org.w3c.dom.Document doc,
                                                     org.w3c.dom.Element element,
                                                     java.lang.String elementName)

Append a child element to the given element.

Parameters:

doc - the document

element - the element to append the child to

elementName - the name of the element

Returns:

the appended child element

appendChildElement

public static void appendChildElement(org.w3c.dom.Document doc,
                                      java.lang.String name,
                                      java.lang.String value)

Append an element with a text node to the given document root.

Parameters:

doc - The document to append the element to

name - The name of the new element

value - The textual value of the element

documentToHashtable

public static java.util.Hashtable documentToHashtable(org.w3c.dom.Document doc)

Converts the input document into a Hashtable.
The name of each found element will be the key in the Hashtable and the value of the element will be the value in the Hashtable.
I case the same element occurrs several time, the latest value will take precedence.

Parameters:

doc - The input document

Returns:

The Hashtable, empty if no elements were found

documentToString

public static java.lang.String documentToString(org.w3c.dom.Document doc)

Gets the string representation of an XML document. The resulting string is trimmed to remove redundant white spaces from the begining and end of the string.

Parameters:

doc - The document

Returns:

The string representation of the document, null if an error occurred

See Also:

documentToWriter(Document, Writer)

documentToFile

public static void documentToFile(org.w3c.dom.Document doc,
                                  java.io.File file)
                           throws java.io.IOException,
                                  javax.xml.transform.TransformerException

Writes the document to a file.

Parameters:

doc - The document

file - The target file

Throws:

java.io.IOException

javax.xml.transform.TransformerException

See Also:

documentToStream(Document, OutputStream)

documentToFile

public static void documentToFile(org.w3c.dom.Document doc,
                                  java.lang.String file)
                           throws java.io.IOException,
                                  javax.xml.transform.TransformerException

Writes the document to a file.

Parameters:

doc - The document

file - The target file name

Throws:

java.io.IOException

javax.xml.transform.TransformerException

See Also:

documentToStream(Document, OutputStream)

documentToStream

public static void documentToStream(org.w3c.dom.Document doc,
                                    java.io.OutputStream ostream)
                             throws java.io.IOException,
                                    javax.xml.transform.TransformerException

Writes the document to a given outputstream.

Parameters:

doc - The document

ostream - The target stream

Throws:

java.io.IOException

javax.xml.transform.TransformerException

documentToStream

public static void documentToStream(org.w3c.dom.Document doc,
                                    java.io.OutputStream ostream,
                                    boolean closeStream)
                             throws java.io.IOException,
                                    javax.xml.transform.TransformerException

Writes the document to a given outputstream.

Parameters:

doc - The document

ostream - The target stream

closeStream - If the outputstream is to be closed after write

Throws:

java.io.IOException

javax.xml.transform.TransformerException

documentToWriter

public static void documentToWriter(org.w3c.dom.Document doc,
                                    java.io.Writer writer)
                             throws java.io.IOException,
                                    javax.xml.transform.TransformerException

Writes the document to a given writer.

Parameters:

doc - The document

writer - The target writer

Throws:

java.io.IOException

javax.xml.transform.TransformerException

getElementValue

public static java.lang.String getElementValue(org.w3c.dom.Element element,
                                               java.lang.String defaultValue)

Get the value of the element.
The method expects the element to have a single TEXT node as child, if so the value of the text node is returned otherwise an empty String is returned.

Parameters:

element - The element

defaultValue - The value to return in case no value was found

Returns:

The value

getElementValue

public static java.lang.String getElementValue(org.w3c.dom.Element element)

Get the value of the element.
The method expects the element to have a single TEXT node as child, if so the value of the text node is returned otherwise an empty String is returned.

Parameters:

element - The element

Returns:

The valeu

getElementValue

public static java.lang.String getElementValue(org.w3c.dom.NodeList list,
                                               java.lang.String defaultValue)

Get the node value from the first element in the node list.
The method expects that the nodes in the list are elements and that they have a a child node of the type Text that may be extracted.

Parameters:

list - The node list

defaultValue - The value to return in case no value was found

Returns:

The node value of the node, empty String if not found or the method fails

getElementValue

public static java.lang.String getElementValue(org.w3c.dom.NodeList list)

Get the node value from the first element in the node list.
The method expects that the nodes in the list are elements and that they have a a child node of the type Text that may be extracted.

Parameters:

list - The node list

Returns:

The node value of the node, empty String if not found or the method fails

getFirstParameterValue

public static java.lang.String getFirstParameterValue(org.w3c.dom.Document doc,
                                                      java.lang.String name)

Returns the value of the first <Paramter> element that has an name attribute maching the supplied parameter.

Parameters:

doc - The input Document

name - Name of the paramter to find

Returns:

The value of the parameter, null if not found.

getFirstParameterValue

public static java.lang.String getFirstParameterValue(org.w3c.dom.Element parent,
                                                      java.lang.String name)

Returns the value of the first <Paramter> element that has an name attribute maching the supplied parameter.

Parameters:

parent - The input Element

name - Name of the paramter to find

Returns:

The value of the parameter, null if not found.

setElementValue

public static void setElementValue(org.w3c.dom.Element el,
                                   java.lang.String value)

Set the value of an element.

Parameters:

el - the element

value - the value

loadFromResource

public static org.w3c.dom.Document loadFromResource(java.lang.String path)
                                             throws java.io.IOException,
                                                    org.xml.sax.SAXException,
                                                    javax.xml.parsers.ParserConfigurationException

Load an XML document from a resource.

Parameters:

path - the path to load from

Returns:

the document

Throws:

java.io.IOException

org.xml.sax.SAXException

javax.xml.parsers.ParserConfigurationException

getParameters

public static org.w3c.dom.Element[] getParameters(org.w3c.dom.Document doc,
                                                  java.lang.String name)

Returns an array with all child <Parameter> elements that have a name matching the given parameter value.

Parameters:

doc - Input document

name - value of the name attribute

Returns:

The array

getParameters

public static org.w3c.dom.Element[] getParameters(org.w3c.dom.Element parent,
                                                  java.lang.String name)

Returns an array with all child <Parameter> elements that have a name matching the given parameter value.

Parameters:

parent - Input element

name - value of the name attribute

Returns:

The array

isBlank

public static boolean isBlank(java.lang.String value)

Checks if a node value is blank (contains only white spaces).

Parameters:

value - The value to check

Returns:

false if the value is null or a non white space character is found

getDocument

public static org.w3c.dom.Document getDocument(java.io.File file)
                                        throws java.io.IOException,
                                               org.xml.sax.SAXException

Parse an XML document from a file.

Parameters:

file - The file

Returns:

The document

Throws:

java.io.IOException

org.xml.sax.SAXException

getDocument

public static org.w3c.dom.Document getDocument(org.xml.sax.InputSource is)
                                        throws java.io.IOException,
                                               org.xml.sax.SAXException

Parse an XML document from a file.

Parameters:

is - The input source

Returns:

The document

Throws:

java.io.IOException

org.xml.sax.SAXException

getDocument

public static org.w3c.dom.Document getDocument(java.lang.String path)
                                        throws java.lang.Exception

Parse an XML document from a file.

Parameters:

path - the file

Returns:

the parsed document

Throws:

java.lang.Exception

getDocument

public static org.w3c.dom.Document getDocument(java.net.URL url)
                                        throws java.io.IOException,
                                               org.xml.sax.SAXException

Parse an XML document from a URL.

Parameters:

url - The URL from where to parse the document

Returns:

The document

Throws:

java.io.IOException

org.xml.sax.SAXException

getDocument

public static org.w3c.dom.Document getDocument(java.io.InputStream istream)
                                        throws java.io.IOException,
                                               org.xml.sax.SAXException

Parse an XML document from an input stream.

Parameters:

istream - The stream from where to parse the document

Returns:

The document

Throws:

java.io.IOException

org.xml.sax.SAXException

removeAllChildElements

public static void removeAllChildElements(org.w3c.dom.Element element)

Removes all child elements to the given element

Parameters:

element - The element

saveToFile

public static void saveToFile(org.w3c.dom.Document doc,
                              java.lang.String path)

Save the specified document to file.

Parameters:

doc - the document to save

path - the path to the file

See Also:

saveToFile(Document, File)

saveToFile

public static void saveToFile(org.w3c.dom.Document doc,
                              java.io.File file)

Save the specified document to file.
If the file already exists a backup of the file will be made.
Also a comment will be added to the saved document, stating that the file must not be manually edited.

Parameters:

doc - the document to save

file - the file to save to