anon.util
Class XMLUtil

java.lang.Object
  anon.util.XMLUtil

public class XMLUtil
extends java.lang.Object

This class provides an easy interface to XML methods.

Field Summary

private static java.lang.String	DEFAULT_FORMAT_SPACE
private static java.lang.String	HIERARCHY_REQUEST_ERR
private static boolean	m_bCheckedHumanReadableFormatting
private static boolean	m_bNeedsHumanReadableFormatting
private static javax.xml.parsers.DocumentBuilder	ms_DocumentBuilder
private static java.lang.String	PACKAGE_TRANSFORMER
private static java.lang.String	XML_STR_BOOLEAN_FALSE
private static java.lang.String	XML_STR_BOOLEAN_TRUE

Constructor Summary

XMLUtil()

Method Summary

static org.w3c.dom.Node	assertNodeName(org.w3c.dom.Node a_node, java.lang.String a_strExpectedName) Throws an XMLParseException if the given XML node has not the expected name or if it is null.
static void	assertNotNull(org.w3c.dom.Node a_node) Throws an XMLParseException if the given XML node is null.
static void	assertNotNull(org.w3c.dom.Node a_node, java.lang.String a_attribute)
static org.w3c.dom.Document	createDocument() Creates a new Document.
static org.w3c.dom.Document	formatHumanReadable(org.w3c.dom.Document a_doc) Reformats an XML document into a human readable format.
static org.w3c.dom.Element	formatHumanReadable(org.w3c.dom.Element a_element) Reformats an XML element into a human readable format.
private static int	formatHumanReadable(org.w3c.dom.Node a_element, int a_level) Reformats an element into a human readable format.
static org.w3c.dom.Node	getDocumentElement(org.w3c.dom.Node a_node) If the current node is of the type XML document, this method returns the document element.
static org.w3c.dom.Node	getFirstChildByName(org.w3c.dom.Node a_node, java.lang.String a_childname) Returns the child node of the given node with the given name.
static org.w3c.dom.Node	getFirstChildByNameUsingDeepSearch(org.w3c.dom.Node a_node, java.lang.String a_childname) Returns the child node of the given node with the given name.
private static org.w3c.dom.Node	getFirstChildByNameUsingDeepSearchInternal(org.w3c.dom.Node node, java.lang.String name) Returns a node that is equal to the given name, starting from the given node and, if it is not the node we are looking for, recursing to all its children.
static org.w3c.dom.Node	getLastChildByName(org.w3c.dom.Node n, java.lang.String name)
static java.lang.String	getXmlElementContainerName(java.lang.Class a_xmlEncodableClass) Uses Java reflection to get the static XML_ELEMENT_CONTAINER_NAME field contents if present in the given class.
static java.lang.String	getXmlElementName(java.lang.Class a_xmlEncodableClass) Uses Java reflection to get the static XML_ELEMENT_NAME field contents if present in the given class.
static org.w3c.dom.Node	importNode(org.w3c.dom.Document a_doc, org.w3c.dom.Node a_source, boolean a_bDeep) Returns a copy of the source node with the given document as owner document This method is needed as nodes cannot be appended to foreign documents by default, but only to the document by which they have been created.
static boolean	parseAttribute(org.w3c.dom.Node a_node, java.lang.String a_attribute, boolean a_default) Returns the value of the specified attribute of an XML element as boolean.
static int	parseAttribute(org.w3c.dom.Node a_node, java.lang.String a_attribute, int a_default) Returns the value of the specified attribute of an XML element as int.
static long	parseAttribute(org.w3c.dom.Node a_node, java.lang.String a_attribute, long a_default) Returns the value of the specified attribute of an XML element as long.
static java.lang.String	parseAttribute(org.w3c.dom.Node a_node, java.lang.String a_attribute, java.lang.String a_default) Returns the value of the specified attribute of an XML element as String.
static boolean	parseValue(org.w3c.dom.Node a_node, boolean a_defaultValue) Returns the value of the specified XML node as boolean.
static double	parseValue(org.w3c.dom.Node a_node, double a_defaultValue) Returns the value of the specified XML node as double.
static int	parseValue(org.w3c.dom.Node a_node, int a_defaultValue) Returns the value of the specified XML node as int.
static long	parseValue(org.w3c.dom.Node a_node, long a_defaultValue) Returns the value of the specified XML node as long.
static java.lang.String	parseValue(org.w3c.dom.Node a_node, java.lang.String a_defaultValue) Gets the content of an Element or Text Node.
static java.lang.String	quoteXML(java.lang.String text)
static org.w3c.dom.Element[]	readElementsByTagName(java.io.File a_file, java.lang.String a_tagName) Loads all elements under the root elements that have the specified tag name.
static org.w3c.dom.Document	readXMLDocument(java.io.File a_file) Reads an XML document from a file.
static org.w3c.dom.Document	readXMLDocument(org.xml.sax.InputSource a_inputSource) Reads an XML document from an input source.
static org.w3c.dom.Document	readXMLDocument(java.io.InputStream a_inputStream) Reads an XML document from an input stream.
static org.w3c.dom.Document	readXMLDocument(java.io.Reader a_reader) Reads an XML document from a Reader.
static void	removeComments(org.w3c.dom.Node a_node) Removes all comments and empty lines from a node.
private static int	removeCommentsInternal(org.w3c.dom.Node a_node, org.w3c.dom.Node a_parentNode) Removes all comments, empty lines and new lines from a node.
static void	setAttribute(org.w3c.dom.Element a_element, java.lang.String a_attribute, boolean a_value) Creates and sets an attribute with a boolean value to an XML element.
static void	setAttribute(org.w3c.dom.Element a_element, java.lang.String a_attribute, double a_value) Creates and sets an attribute with a double value to an XML element.
static void	setAttribute(org.w3c.dom.Element a_element, java.lang.String a_attribute, int a_value) Creates and sets an attribute with an int value to an XML element.
static void	setAttribute(org.w3c.dom.Element a_element, java.lang.String a_attribute, long a_value) Creates and sets an attribute with a long value to an XML element.
static void	setAttribute(org.w3c.dom.Element a_element, java.lang.String a_attribute, java.lang.String a_value) Creates and sets an attribute with a String value to an XML element.
static void	setValue(org.w3c.dom.Node a_node, boolean a_bValue) Inserts a boolean value into an XML node.
static void	setValue(org.w3c.dom.Node a_node, int a_value) Inserts an int value into an XML node.
static void	setValue(org.w3c.dom.Node a_node, long a_value) Inserts a long value into an XML node.
static void	setValue(org.w3c.dom.Node a_node, java.lang.String a_value) Inserts a String value into an XML node.
static byte[]	toByteArray(org.w3c.dom.Node a_inputNode) Creates a byte array from the abstract tree of the node.
private static java.io.ByteArrayOutputStream	toByteArrayOutputStream(org.w3c.dom.Node node) Writes an XML-Node to a String.
static java.lang.String	toString(org.w3c.dom.Node a_node) Writes an XML-Node to a String.
static org.w3c.dom.Document	toXMLDocument(byte[] a_xmlDocument) Transforms a byte array into an XML document.
static org.w3c.dom.Document	toXMLDocument(IXMLEncodable a_xmlEncodable) Transforms an IXMLEncodable object into an XML document.
static org.w3c.dom.Document	toXMLDocument(java.lang.String a_xmlDocument) Transforms a String into an XML document.
static org.w3c.dom.Element	toXMLElement(IXMLEncodable a_xmlEncodable) Transforms an IXMLEncodable object into an XML element.
static void	write(org.w3c.dom.Document a_doc, java.io.File a_file) Writes an XML document to a file.
static void	write(org.w3c.dom.Document a_doc, java.io.OutputStream a_outputStream) Writes an XML document to an output stream.
static void	write(org.w3c.dom.Document a_doc, java.io.Writer a_writer) Writes an XML document to a Writer.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_FORMAT_SPACE

private static final java.lang.String DEFAULT_FORMAT_SPACE

See Also:

Constant Field Values

XML_STR_BOOLEAN_TRUE

private static final java.lang.String XML_STR_BOOLEAN_TRUE

See Also:

Constant Field Values

XML_STR_BOOLEAN_FALSE

private static final java.lang.String XML_STR_BOOLEAN_FALSE

See Also:

Constant Field Values

PACKAGE_TRANSFORMER

private static final java.lang.String PACKAGE_TRANSFORMER

See Also:

Constant Field Values

HIERARCHY_REQUEST_ERR

private static final java.lang.String HIERARCHY_REQUEST_ERR

See Also:

Constant Field Values

ms_DocumentBuilder

private static javax.xml.parsers.DocumentBuilder ms_DocumentBuilder

m_bCheckedHumanReadableFormatting

private static boolean m_bCheckedHumanReadableFormatting

m_bNeedsHumanReadableFormatting

private static boolean m_bNeedsHumanReadableFormatting

Constructor Detail

XMLUtil

public XMLUtil()

Method Detail

assertNotNull

public static void assertNotNull(org.w3c.dom.Node a_node)
                          throws XMLParseException

Throws an XMLParseException if the given XML node is null.

Parameters:

a_node - an XML node

Throws:

XMLParseException - if the given XML node is null

assertNotNull

public static void assertNotNull(org.w3c.dom.Node a_node,
                                 java.lang.String a_attribute)
                          throws XMLParseException

Throws:

XMLParseException

assertNodeName

public static org.w3c.dom.Node assertNodeName(org.w3c.dom.Node a_node,
                                              java.lang.String a_strExpectedName)
                                       throws XMLParseException

Throws an XMLParseException if the given XML node has not the expected name or if it is null. If the given node is an XML document, the document element is returned. Otherwise, the given node is returned.

Parameters:

a_node - an XML node

a_strExpectedName - the node`s expected name

Returns:

If the given node is an XML document, the document element is returned. Otherwise, the given node is returned.

Throws:

XMLParseException - if the given node has not the expected name or if it is null

getDocumentElement

public static org.w3c.dom.Node getDocumentElement(org.w3c.dom.Node a_node)

If the current node is of the type XML document, this method returns the document element. Otherwise, the node is returned unchanged.

Parameters:

a_node - an XML node

Returns:

if the current node is of the type XML document, this method returns the document element; otherwise, the node is returned unchanged

parseValue

public static int parseValue(org.w3c.dom.Node a_node,
                             int a_defaultValue)

Returns the value of the specified XML node as int.

Parameters:

a_node - an XML node

a_defaultValue - the default value

Returns:

the value of the specified node as boolean if the element`s value is of type int; otherwise, the default value is returned

parseValue

public static long parseValue(org.w3c.dom.Node a_node,
                              long a_defaultValue)

Returns the value of the specified XML node as long.

Parameters:

a_node - an XML node

a_defaultValue - the default value

Returns:

the value of the specified node as boolean if the element`s value is of type long; otherwise, the default value is returned

parseValue

public static double parseValue(org.w3c.dom.Node a_node,
                                double a_defaultValue)

Returns the value of the specified XML node as double.

Parameters:

a_node - an XML node

a_defaultValue - the default value

Returns:

the value of the specified node as double if the element`s value is of type double; otherwise, the default value is returned

parseAttribute

public static java.lang.String parseAttribute(org.w3c.dom.Node a_node,
                                              java.lang.String a_attribute,
                                              java.lang.String a_default)

Returns the value of the specified attribute of an XML element as String.

Parameters:

a_node - an XML node

a_attribute - an attribute`s name

a_default - the default value

Returns:

the value of the specified attribute as String if the element has this attribute; otherwise, the default value is returned

parseAttribute

public static boolean parseAttribute(org.w3c.dom.Node a_node,
                                     java.lang.String a_attribute,
                                     boolean a_default)

Returns the value of the specified attribute of an XML element as boolean.

Parameters:

a_node - an XML node

a_attribute - an attribute`s name

a_default - the default value

Returns:

the value of the specified attribute as boolean if the element has this attribute; otherwise, the default value is returned

parseAttribute

public static int parseAttribute(org.w3c.dom.Node a_node,
                                 java.lang.String a_attribute,
                                 int a_default)

Returns the value of the specified attribute of an XML element as int.

Parameters:

a_node - an XML node

a_attribute - an attribute`s name

a_default - the default value

Returns:

the value of the specified attribute as int if the element has this attribute; otherwise, the default value is returned

parseAttribute

public static long parseAttribute(org.w3c.dom.Node a_node,
                                  java.lang.String a_attribute,
                                  long a_default)

Returns the value of the specified attribute of an XML element as long.

Parameters:

a_node - an XML node

a_attribute - an attribute`s name

a_default - the default value

Returns:

the value of the specified attribute as long if the element has this attribute; otherwise, the default value is returned

parseValue

public static boolean parseValue(org.w3c.dom.Node a_node,
                                 boolean a_defaultValue)

Returns the value of the specified XML node as boolean.

Parameters:

a_node - an XML node

a_defaultValue - the default value

Returns:

the value of the specified node as boolean if the element`s value is of type boolean; otherwise, the default value is returned

parseValue

public static java.lang.String parseValue(org.w3c.dom.Node a_node,
                                          java.lang.String a_defaultValue)

Gets the content of an Element or Text Node. The "content" of an Element Node is the text between the opening and closing Element Tag. The content of an attribute node is the value of the attribute.

Parameters:

a_node - text node, element node or attribute node

a_defaultValue - value returned, if an error occured

Returns:

the "content" of the node or the default value, if the node has no value or an error occured

getXmlElementContainerName

public static java.lang.String getXmlElementContainerName(java.lang.Class a_xmlEncodableClass)

Uses Java reflection to get the static XML_ELEMENT_CONTAINER_NAME field contents if present in the given class.

Parameters:

a_xmlEncodableClass - a Class (should be an IXMLEncodable)

Returns:

the static XML_ELEMENT_CONTAINER_NAME field contents if present in the given class or null if the field was not found

getXmlElementName

public static java.lang.String getXmlElementName(java.lang.Class a_xmlEncodableClass)

Uses Java reflection to get the static XML_ELEMENT_NAME field contents if present in the given class.

Parameters:

a_xmlEncodableClass - a Class (should be an IXMLEncodable)

Returns:

the static XML_ELEMENT_NAME field contents if present in the given class or null if the field was not found

readElementsByTagName

public static org.w3c.dom.Element[] readElementsByTagName(java.io.File a_file,
                                                          java.lang.String a_tagName)

Loads all elements under the root elements that have the specified tag name.

Parameters:

a_file - a file to load the elements from

a_tagName - the tag that specifies the elemetns to load

Returns:

the elements read from the given file or an empty array if no elements were read

getFirstChildByName

public static org.w3c.dom.Node getFirstChildByName(org.w3c.dom.Node a_node,
                                                   java.lang.String a_childname)

Returns the child node of the given node with the given name.

Parameters:

a_node - the node from that the search starts

a_childname - the childnode we are looking for

Returns:

the child node of the given node with the given name or null if it was not found

getFirstChildByNameUsingDeepSearch

public static org.w3c.dom.Node getFirstChildByNameUsingDeepSearch(org.w3c.dom.Node a_node,
                                                                  java.lang.String a_childname)

Returns the child node of the given node with the given name. If the node is not found in the direct children of the parent node, then all child nodes will be searched and then their child nodes and so on until either the requested child has been found or all nodes in the XML structure have been traversed.

Parameters:

a_node - the node from that the search starts

a_childname - the childnode we are looking for

Returns:

the child node of the given node with the given name or null if it was not found

getLastChildByName

public static org.w3c.dom.Node getLastChildByName(org.w3c.dom.Node n,
                                                  java.lang.String name)

setValue

public static void setValue(org.w3c.dom.Node a_node,
                            java.lang.String a_value)

Inserts a String value into an XML node. If a_value==NULL nothing is done.

Parameters:

a_node - an XML node

a_value - a String

setValue

public static void setValue(org.w3c.dom.Node a_node,
                            int a_value)

Inserts an int value into an XML node.

Parameters:

a_node - an XML node

a_value - an int value

setValue

public static void setValue(org.w3c.dom.Node a_node,
                            long a_value)

Inserts a long value into an XML node.

Parameters:

a_node - an XML node

a_value - a long value

setValue

public static void setValue(org.w3c.dom.Node a_node,
                            boolean a_bValue)

Inserts a boolean value into an XML node.

Parameters:

a_node - an XML node

a_bValue - a boolean value

setAttribute

public static void setAttribute(org.w3c.dom.Element a_element,
                                java.lang.String a_attribute,
                                java.lang.String a_value)

Creates and sets an attribute with a String value to an XML element. If a_attribute or a_value is NULL, than nothing is done!

Parameters:

a_element - an XML Element (not NULL)

a_attribute - an attribute name (not NULL)

a_value - a String value for the attribute (not NULL)

setAttribute

public static void setAttribute(org.w3c.dom.Element a_element,
                                java.lang.String a_attribute,
                                boolean a_value)

Creates and sets an attribute with a boolean value to an XML element.

Parameters:

a_element - an XML Element

a_attribute - an attribute name

a_value - a boolean value for the attribute

setAttribute

public static void setAttribute(org.w3c.dom.Element a_element,
                                java.lang.String a_attribute,
                                int a_value)

Creates and sets an attribute with an int value to an XML element.

Parameters:

a_element - an XML Element

a_attribute - an attribute name

a_value - an int value for the attribute

setAttribute

public static void setAttribute(org.w3c.dom.Element a_element,
                                java.lang.String a_attribute,
                                double a_value)

Creates and sets an attribute with a double value to an XML element.

Parameters:

a_element - an XML Element

a_attribute - an attribute name

a_value - a double value for the attribute

setAttribute

public static void setAttribute(org.w3c.dom.Element a_element,
                                java.lang.String a_attribute,
                                long a_value)

Creates and sets an attribute with a long value to an XML element.

Parameters:

a_element - an XML Element

a_attribute - an attribute name

a_value - a long value for the attribute

createDocument

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

Creates a new Document.

Returns:

a new Document

importNode

public static org.w3c.dom.Node importNode(org.w3c.dom.Document a_doc,
                                          org.w3c.dom.Node a_source,
                                          boolean a_bDeep)
                                   throws XMLParseException

Returns a copy of the source node with the given document as owner document This method is needed as nodes cannot be appended to foreign documents by default, but only to the document by which they have been created.

Parameters:

a_doc - the new owner document of the copied source node

a_source - the source XML node

a_bDeep - true if the source node should be copied with all children, the chlidren`s children and so on; false, if only the direct children of the source node should be copied

Returns:

a copy of the source node with the given document as owner document

Throws:

java.lang.Exception - if an error occurs

XMLParseException

toByteArray

public static byte[] toByteArray(org.w3c.dom.Node a_inputNode)

Creates a byte array from the abstract tree of the node.

Parameters:

a_inputNode - The node (incl. the whole tree) which is flattened to a byte array.

Returns:

the node as a byte array (incl. the whole tree).

toString

public static java.lang.String toString(org.w3c.dom.Node a_node)

Writes an XML-Node to a String. If the node is a Document then the header is included. Since writing was not standardized until JAXP 1.1 different Methods are tried

Parameters:

a_node - an XML Node

Returns:

an XML Node in a String representation or null if no transformation could be done

quoteXML

public static java.lang.String quoteXML(java.lang.String text)

removeComments

public static void removeComments(org.w3c.dom.Node a_node)

Removes all comments and empty lines from a node. Does nothing if the node is a comment node.

Parameters:

a_node - a node

formatHumanReadable

public static org.w3c.dom.Document formatHumanReadable(org.w3c.dom.Document a_doc)

Reformats an XML document into a human readable format.

Parameters:

a_doc - an xml document

formatHumanReadable

public static org.w3c.dom.Element formatHumanReadable(org.w3c.dom.Element a_element)

Reformats an XML element into a human readable format.

Parameters:

a_element - an xml element

readXMLDocument

public static org.w3c.dom.Document readXMLDocument(org.xml.sax.InputSource a_inputSource)
                                            throws java.io.IOException,
                                                   XMLParseException

Reads an XML document from an input source.

Parameters:

a_inputSource - an input source

Returns:

the XML document that was read from the input source

Throws:

java.io.IOException - if an I/O error occurs

XMLParseException - if the input stream could not be parsed correctly

readXMLDocument

public static org.w3c.dom.Document readXMLDocument(java.io.InputStream a_inputStream)
                                            throws java.io.IOException,
                                                   XMLParseException

Reads an XML document from an input stream.

Parameters:

a_inputStream - an input stream

Returns:

the XML document that was read from the input stream

Throws:

java.io.IOException - if an I/O error occurs

XMLParseException - if the input stream could not be parsed correctly

readXMLDocument

public static org.w3c.dom.Document readXMLDocument(java.io.Reader a_reader)
                                            throws java.io.IOException,
                                                   XMLParseException

Reads an XML document from a Reader.

Parameters:

a_reader - a Reader.

Returns:

the XML document that was read from the Reader

Throws:

java.io.IOException - if an I/O error occurs

XMLParseException - if the input stream could not be parsed correctly

readXMLDocument

public static org.w3c.dom.Document readXMLDocument(java.io.File a_file)
                                            throws java.io.IOException,
                                                   XMLParseException

Reads an XML document from a file.

Parameters:

a_file - a file

Returns:

the XML document that was read from the file

Throws:

java.io.IOException - if an I/O error occurs

XMLParseException - if the file could not be parsed correctly

write

public static void write(org.w3c.dom.Document a_doc,
                         java.io.OutputStream a_outputStream)
                  throws java.io.IOException

Writes an XML document to an output stream.

Parameters:

a_doc - an XML document

a_outputStream - an output stream

Throws:

java.io.IOException - if an I/O error occurs

write

public static void write(org.w3c.dom.Document a_doc,
                         java.io.Writer a_writer)
                  throws java.io.IOException

Writes an XML document to a Writer.

Parameters:

a_doc - an XML document

a_writer - a Writer

Throws:

java.io.IOException - if an I/O error occurs

write

public static void write(org.w3c.dom.Document a_doc,
                         java.io.File a_file)
                  throws java.io.IOException

Writes an XML document to a file.

Parameters:

a_doc - an XML document

a_file - a file

Throws:

java.io.IOException - if an I/O error occurs

toXMLDocument

public static org.w3c.dom.Document toXMLDocument(java.lang.String a_xmlDocument)
                                          throws XMLParseException

Transforms a String into an XML document. The String must be a valid XML document in String representation.

Parameters:

a_xmlDocument - a valid XML document in String representation

Returns:

an XML document

Throws:

XMLParseException - if the given String is no valid XML document

toXMLDocument

public static org.w3c.dom.Document toXMLDocument(byte[] a_xmlDocument)
                                          throws XMLParseException

Transforms a byte array into an XML document. The byte array must be a valid XML document in byte representation.

Parameters:

a_xmlDocument - a valid XML document in byte representation

Returns:

an XML document

Throws:

XMLParseException - if the given byte array is no valid XML document

toXMLDocument

public static org.w3c.dom.Document toXMLDocument(IXMLEncodable a_xmlEncodable)

Transforms an IXMLEncodable object into an XML document.

Parameters:

a_xmlEncodable - an IXMLEncodable

Returns:

an XML document

toXMLElement

public static org.w3c.dom.Element toXMLElement(IXMLEncodable a_xmlEncodable)

Transforms an IXMLEncodable object into an XML element.

Parameters:

a_xmlEncodable - an IXMLEncodable

Returns:

an XML element

toByteArrayOutputStream

private static java.io.ByteArrayOutputStream toByteArrayOutputStream(org.w3c.dom.Node node)

Writes an XML-Node to a String. If the node is a Document then the header is included. Since writing was not standardized until JAXP 1.1 different Methods are tried

Parameters:

node - an XML Node

Returns:

an XML Node in a ByteArrayOutputStream representation or null if no transformation could be done

getFirstChildByNameUsingDeepSearchInternal

private static org.w3c.dom.Node getFirstChildByNameUsingDeepSearchInternal(org.w3c.dom.Node node,
                                                                           java.lang.String name)

Returns a node that is equal to the given name, starting from the given node and, if it is not the node we are looking for, recursing to all its children.

Parameters:

node - the node from that the search starts

name - the node we are looking for

Returns:

Node the node with the given name or null if it was not found

formatHumanReadable

private static int formatHumanReadable(org.w3c.dom.Node a_element,
                                       int a_level)

Reformats an element into a human readable format. This is a recursive function.

Parameters:

a_element - an xml element

a_level - the level of this element

Returns:

the number of nodes added (0 or 1)

removeCommentsInternal

private static int removeCommentsInternal(org.w3c.dom.Node a_node,
                                          org.w3c.dom.Node a_parentNode)

Removes all comments, empty lines and new lines from a node. This is a recursive function.

Parameters:

a_node - a node

a_parentNode - the node`s parent node

Returns:

the number of children removed (0 or 1)