uk.org.ogsadai.common.xml
Class XMLUtilities

java.lang.Object
  |
  +--uk.org.ogsadai.common.xml.XMLUtilities

public class XMLUtilities

extends java.lang.Object

A collection of helper methods for parsing to and from XML.

Author:

The OGSA-DAI Project Team.

Field Summary

private static java.lang.String

COPYRIGHT_NOTICE Copyright statement

Constructor Summary

XMLUtilities()

Method Summary

static org.w3c.dom.Document	createEmptyDocument() Create a new empty org.w3c.dom.Document.
static java.lang.String	elementToString(org.w3c.dom.Element element) Converts an Element to its String representation.
static java.lang.String	getAttributeValue(org.w3c.dom.Document doc, java.lang.String eltName, java.lang.String attributeName) Extracts the value of a named attribute of the first element with a given name in a given doc.
static org.w3c.dom.Element	getChildElement(org.w3c.dom.Element parent, java.lang.String namespaceURI, java.lang.String childName) Gets the named child element of the specified parent.
static java.lang.String	getChildElementAttribute(org.w3c.dom.Element parent, java.lang.String namespaceURI, java.lang.String childName, java.lang.String attributeName) Gets the named attribute of the named child element of the specified parent.
static java.util.Iterator	getChildElementIterator(org.w3c.dom.Node parent) Returns an iterator over the child elements of a DOM node.
static java.util.List	getChildElements(org.w3c.dom.Element parent) Gets a list of all the child elements of the specified parent.
static java.lang.String	getChildText(org.w3c.dom.Element parent, java.lang.String namespaceURI, java.lang.String childName) Gets the concatenated text children, trimmed of surrounding whitespace, of the named child element of the specified parent.
static java.lang.String	getChildText(org.w3c.dom.Node parent) Extract the XML sub-tree beneath the given node and return as an XML string.
static org.w3c.dom.Element	getElement(org.w3c.dom.Document doc, java.lang.String eltName) Extracts the first element with a given name from a given document.
static java.lang.String	getElementValue(org.w3c.dom.Document doc, java.lang.String eltName) Extracts the value of the first element with a given name from a given document.
static java.lang.String	getTextContent(org.w3c.dom.Node node) Gets the text content below of the specified node.
static java.lang.String	parseAttribute(org.w3c.dom.Element element, java.lang.String attributeName, boolean nonEmpty) Parses the value of an attribute of an element.
static java.lang.String	parseChildElementAttribute(org.w3c.dom.Element parent, java.lang.String namespaceURI, java.lang.String childName, java.lang.String attributeName, boolean required, boolean nonEmpty) Parses the value of an attribute of a child element.
static java.lang.String	parseChildElementValue(org.w3c.dom.Element parent, java.lang.String namespaceURI, java.lang.String childName, boolean required, boolean nonEmpty) Parses the value of a child element of the specified parent.
static java.lang.String	parseElementValue(org.w3c.dom.Element element, boolean nonEmpty) Parses the specified element and returns its value.
static long	parseLong(org.w3c.dom.Element parent, java.lang.String childName, java.lang.String attributeName) Parses the values of a named attribute of an element and converts the value to a long.
static java.lang.String	replaceSpecialCharacters(java.lang.String input) Forms a new string by replacing any XML reserved characters in the given input string with their encoded equivalents.
static void	xmlDOMToFile(org.w3c.dom.Document doc, java.lang.String fileName) Puts a DOM Document into a file.
static void	xmlDOMToStream(org.w3c.dom.Node node, java.io.OutputStream stream) Serializes a DOM object to a java.io.OutputStream.
private static void	xmlDOMToStream(org.w3c.dom.Node node, java.io.OutputStream stream, java.io.Writer writer) Serializes a DOM object to a java.io.OutputStream or a java.io.Writer.
static void	xmlDOMToStream(org.w3c.dom.Node node, java.io.Writer writer) Serializes a DOM object to a java.io.Writer.
static java.lang.String	xmlDOMToString(org.w3c.dom.Node node) Serializes a DOM object to a String.
static org.w3c.dom.Document	xmlFileToDOM(java.lang.String fileName) Parses an XML file into a DOM Document and validates it against its XML Schema.
static org.w3c.dom.Document	xmlFileToDOM(java.lang.String fileName, boolean validate) Parses an XML file into a DOM Document.
static org.w3c.dom.Document	xmlReaderToDOM(java.io.Reader reader, boolean validate) Converts XML from a java.io.Reader into a DOM Document
static org.w3c.dom.Document	xmlStreamToDOM(java.io.InputStream stream) Converts XML from a java.io.InputStream into a DOM Document and validates it against its XML Schema.
static org.w3c.dom.Document	xmlStreamToDOM(java.io.InputStream stream, boolean validate) Converts XML from a java.io.InputStream into a DOM Document.
static org.w3c.dom.Document	xmlStringToDOM(java.lang.String str) Converts XML from a String into a DOM Document and validates it against its XML Schema.
static org.w3c.dom.Document	xmlStringToDOM(java.lang.String str, boolean validate) Converts XML from a String into a DOM Document.

Methods inherited from class java.lang.Object

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

Field Detail

COPYRIGHT_NOTICE

private static final java.lang.String COPYRIGHT_NOTICE

Copyright statement

See Also:

Constant Field Values

Constructor Detail

XMLUtilities

public XMLUtilities()

Method Detail

xmlFileToDOM

public static org.w3c.dom.Document xmlFileToDOM(java.lang.String fileName)
                                         throws XMLFileException,
                                                XMLDocumentException,
                                                XMLParseException

Parses an XML file into a DOM Document and validates it against its XML Schema.

Parameters:

fileName -

Returns:

DOM document

Throws:

XMLFileException

XMLDocumentException

XMLParseException

See Also:

xmlFileToDOM(java.lang.String, boolean)

xmlFileToDOM

public static org.w3c.dom.Document xmlFileToDOM(java.lang.String fileName,
                                                boolean validate)
                                         throws XMLFileException,
                                                XMLDocumentException,
                                                XMLParseException

Parses an XML file into a DOM Document.

Parameters:

fileName - Source file.

validate - A boolean flag to indicate if schema validation is required.

Returns:

Document.

Throws:

XMLFileException - if there is a problem accessing the file.

XMLDocumentException - if the document does not validate against the XML Schema.

XMLParseException - if there is a problem with the parser setup or execution.

java.lang.IllegalArgumentException - if file is null.

See Also:

xmlStreamToDOM(java.io.InputStream, boolean)

xmlStringToDOM

public static org.w3c.dom.Document xmlStringToDOM(java.lang.String str)
                                           throws XMLDocumentException,
                                                  XMLParseException

Converts XML from a String into a DOM Document and validates it against its XML Schema.

Parameters:

str - XML string

Returns:

DOM document

Throws:

XMLDocumentException

XMLParseException

See Also:

xmlStreamToDOM(java.io.InputStream, boolean)

xmlStringToDOM

public static org.w3c.dom.Document xmlStringToDOM(java.lang.String str,
                                                  boolean validate)
                                           throws XMLDocumentException,
                                                  XMLParseException

Converts XML from a String into a DOM Document.

Parameters:

str - String providing the XML.

validate - A boolean flag to indicate if schema validation is required.

Returns:

the Document.

Throws:

XMLDocumentException - if the document does not validate against the XML Schema.

XMLParseException - if there is a problem with the parser setup or execution.

java.lang.IllegalArgumentException - if string is null.

See Also:

xmlStreamToDOM(java.io.InputStream, boolean)

xmlStreamToDOM

public static org.w3c.dom.Document xmlStreamToDOM(java.io.InputStream stream)
                                           throws XMLDocumentException,
                                                  XMLParseException

Converts XML from a java.io.InputStream into a DOM Document and validates it against its XML Schema.

Parameters:

stream - XML input stream

Returns:

DOM document

Throws:

XMLDocumentException

XMLParseException

See Also:

xmlStreamToDOM(java.io.InputStream, boolean)

xmlStreamToDOM

public static org.w3c.dom.Document xmlStreamToDOM(java.io.InputStream stream,
                                                  boolean validate)
                                           throws XMLDocumentException,
                                                  XMLParseException

Converts XML from a java.io.InputStream into a DOM Document.

Parameters:

stream - InputStream providing the XML.

validate - A boolean flag to indicate if schema validation is required.

Returns:

the Document.

Throws:

XMLDocumentException - if the document does not validate against the XML Schema.

XMLParseException - if there is a problem with the parser setup or execution.

ExternalModuleException - if there is an internal problem within Xerces when creating the Document.

java.lang.IllegalArgumentException - if stream is null.

xmlReaderToDOM

public static org.w3c.dom.Document xmlReaderToDOM(java.io.Reader reader,
                                                  boolean validate)
                                           throws XMLDocumentException,
                                                  XMLParseException

Converts XML from a java.io.Reader into a DOM Document

Parameters:

reader - Reader providing the XML.

validate - A boolean flag to indicate if schema validation is required.

Returns:

the Document.

Throws:

XMLDocumentException - if the document does not validate against the XML Schema.

XMLParseException - if there is a problem with the parser setup or execution.

ExternalModuleException - if there is an internal problem within Xerces when creating the Document.

java.lang.IllegalArgumentException - if reader is null.

xmlDOMToFile

public static void xmlDOMToFile(org.w3c.dom.Document doc,
                                java.lang.String fileName)
                         throws XMLFileException,
                                XMLParseException

Puts a DOM Document into a file. If the file does not exist it will be created otherwise it will be overwritten.

Parameters:

doc - The document to write

fileName - Destination file.

Throws:

XMLFileException - if there is a problem accessing the file.

XMLParseException - if there is a problem with the parser setup or execution.

java.lang.IllegalArgumentException - if fileName or doc are null.

xmlDOMToString

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

Serializes a DOM object to a String.

Parameters:

node - DOM object to serialize.

Returns:

Serialised DOM node

Throws:

java.lang.IllegalArgumentException - if node is null.

xmlDOMToStream

public static void xmlDOMToStream(org.w3c.dom.Node node,
                                  java.io.OutputStream stream)
                           throws XMLParseException

Serializes a DOM object to a java.io.OutputStream.

Parameters:

node - DOM object to serialize.

stream - OutputStream to serialize to.

Throws:

XMLParseException - if there is a problem with the parser setup or execution.

java.lang.IllegalArgumentException - if either argument is null.

xmlDOMToStream

public static void xmlDOMToStream(org.w3c.dom.Node node,
                                  java.io.Writer writer)
                           throws XMLParseException

Serializes a DOM object to a java.io.Writer.

Parameters:

node - DOM object to serialize.

writer - Writer to serialize to - will only be used if stream is null.

Throws:

XMLParseException - if there is a problem with the parser setup or execution.

java.lang.IllegalArgumentException - if either argument is null.

xmlDOMToStream

private static void xmlDOMToStream(org.w3c.dom.Node node,
                                   java.io.OutputStream stream,
                                   java.io.Writer writer)
                            throws XMLParseException

Serializes a DOM object to a java.io.OutputStream or a java.io.Writer.

Parameters:

node - DOM object to serialize.

stream - OutputStream to serialize to.

writer - Writer to serialize to - will only be used if stream is null.

Throws:

XMLParseException - if there is a problem with the parser setup or execution.

getTextContent

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

Gets the text content below of the specified node.

This is achieved by appending the character data contained in any text or CDATA child nodes. Surrounding whitespace is trimmed and duplicate whitespace removed.

Parameters:

node - Node

Returns:

a String containing a concatenation of the text children of the specified node, or an empty string if there are no child nodes.

Throws:

java.lang.IllegalArgumentException - if node is null.

getChildElementIterator

public static java.util.Iterator getChildElementIterator(org.w3c.dom.Node parent)

Returns an iterator over the child elements of a DOM node. node.

Parameters:

parent - Parent node.

Returns:

java.util.Iterator containing Element objects.

Throws:

java.lang.IllegalArgumentException - if parent is null.

createEmptyDocument

public static org.w3c.dom.Document createEmptyDocument()
                                                throws ExternalModuleException

Create a new empty org.w3c.dom.Document.

Returns:

the new Document.

Throws:

ExternalModuleException - if there is an internal problem within Xerces when creating the Document.

replaceSpecialCharacters

public static java.lang.String replaceSpecialCharacters(java.lang.String input)

Forms a new string by replacing any XML reserved characters in the given input string with their encoded equivalents.

Parameters:

input - String to process.

Returns:

a new string compose from the input string with reserved characters replaced

getElement

public static org.w3c.dom.Element getElement(org.w3c.dom.Document doc,
                                             java.lang.String eltName)

Extracts the first element with a given name from a given document.

Parameters:

doc - Document.

eltName - Element name.

Returns:

the first element with the given name or null if there are no elements with that name.

Throws:

java.lang.IllegalArgumentException - if any argument is null.

getElementValue

public static java.lang.String getElementValue(org.w3c.dom.Document doc,
                                               java.lang.String eltName)

Extracts the value of the first element with a given name from a given document.

Parameters:

doc - Document.

eltName - Element name.

Returns:

the value of the first element with the given name or null if there are no elements with that name.

Throws:

java.lang.IllegalArgumentException - if any argument is null.

getAttributeValue

public static java.lang.String getAttributeValue(org.w3c.dom.Document doc,
                                                 java.lang.String eltName,
                                                 java.lang.String attributeName)

Extracts the value of a named attribute of the first element with a given name in a given doc.

Parameters:

doc - Document.

eltName - Element name.

attributeName - Name of attribute whose value is to be returned.

Returns:

the value of the named attribute of the first element with the given name or null if there is no such element or attribute.

Throws:

java.lang.IllegalArgumentException - if any argument is null.

parseLong

public static long parseLong(org.w3c.dom.Element parent,
                             java.lang.String childName,
                             java.lang.String attributeName)

Parses the values of a named attribute of an element and converts the value to a long.

If there is more than one child with the same name, then the value of the attribute from the first child is used. If the attribute value is not a number then -1 is returned.

Parameters:

parent - An element.

childName - Name of a child element.

attributeName - Name of attribute of child element.

Returns:

the long attribute value or -1 if the value is not set or is not a number.

Throws:

java.lang.IllegalArgumentException - if any argument is null.

parseElementValue

public static java.lang.String parseElementValue(org.w3c.dom.Element element,
                                                 boolean nonEmpty)
                                          throws XMLEmptyElementException,
                                                 XMLParseException

Parses the specified element and returns its value. The nonEmpty flag can be used to control the parsing validation.

Parameters:

element - The Element containing the value.

nonEmpty - Set to true if element must contain a value, otherwise false.

Returns:

the String value. If nonEmpty is set to false then this may be null.

Throws:

XMLEmptyElementException - If the element should not be empty but is.

XMLParseException - If there is a system problem parsing the value.

See Also:

getChildText(org.w3c.dom.Node)

parseChildElementValue

public static java.lang.String parseChildElementValue(org.w3c.dom.Element parent,
                                                      java.lang.String namespaceURI,
                                                      java.lang.String childName,
                                                      boolean required,
                                                      boolean nonEmpty)
                                               throws XMLEmptyElementException,
                                                      XMLMissingElementException,
                                                      XMLParseException

Parses the value of a child element of the specified parent. The required and nonEmpty flags should be set to control the validation during the parsing.

Parameters:

parent - The parent Element that may contain the child.

namespaceURI - The URI for the namespace of the child element.

childName - The name of the child element.

required - Set to true if the child element is required, false otherwise.

nonEmpty - Set to true if the child element is cannot be empty false otherwise.

Returns:

element value

Throws:

XMLEmptyElementException - If the element should not be empty but is.

XMLMissingElementException - If the element is missing and it shouldn't be.

XMLParseException - If there is a system problem parsing the value.

See Also:

getChildElement(Element, String, String), parseElementValue(Element, boolean)

parseAttribute

public static java.lang.String parseAttribute(org.w3c.dom.Element element,
                                              java.lang.String attributeName,
                                              boolean nonEmpty)
                                       throws XMLMissingAttributeException,
                                              XMLParseException

Parses the value of an attribute of an element.

Parameters:

element - The Element containing the attribute.

attributeName - The name of the attribute.

nonEmpty - Set to true if the attribute must have a value, false otherwise.

Returns:

Attribute value or null if there is no value

Throws:

XMLMissingAttributeException - If the attribute is missing and it shouldn't be.

XMLParseException - If there is a system problem parsing the value.

parseChildElementAttribute

public static java.lang.String parseChildElementAttribute(org.w3c.dom.Element parent,
                                                          java.lang.String namespaceURI,
                                                          java.lang.String childName,
                                                          java.lang.String attributeName,
                                                          boolean required,
                                                          boolean nonEmpty)
                                                   throws XMLEmptyElementException,
                                                          XMLMissingElementException,
                                                          XMLMissingAttributeException,
                                                          XMLParseException

Parses the value of an attribute of a child element.

Parameters:

parent - The Element that may contain the child.

namespaceURI - The URI for the namespace of the child element.

childName - The name of the child element.

attributeName - The name of the attribute.

required - Set to true if the child element is required, false otherwise.

nonEmpty - Set to true if the attribute cannot be empty false otherwise.

Returns:

Value of the attribute or null if the attribute is not present (and not required).

Throws:

XMLEmptyElementException - If the element should not be empty but is.

XMLMissingElementException - If the element is missing and it shouldn't be.

XMLMissingAttributeException - If the attribute is missing and it shouldn't be.

XMLParseException - If there is a system problem parsing the value.

getChildElements

public static java.util.List getChildElements(org.w3c.dom.Element parent)

Gets a list of all the child elements of the specified parent.

Parameters:

parent - The Element containing the children.

Returns:

a List of Element objects.

getChildElement

public static org.w3c.dom.Element getChildElement(org.w3c.dom.Element parent,
                                                  java.lang.String namespaceURI,
                                                  java.lang.String childName)

Gets the named child element of the specified parent. If there is more than one child element with this name, then the first one is returned.

Parameters:

parent - The parent Element.

namespaceURI - The URI for the namespace of the child element.

childName - The name of the child element.

Returns:

an Element or null if the child does not exist.

getChildElementAttribute

public static java.lang.String getChildElementAttribute(org.w3c.dom.Element parent,
                                                        java.lang.String namespaceURI,
                                                        java.lang.String childName,
                                                        java.lang.String attributeName)

Gets the named attribute of the named child element of the specified parent. If there is more than one child element with this name, then the attribute value of the first one is returned.

Parameters:

parent - The parent Element.

namespaceURI - The URI for the namespace of the child element.

childName - The name of the child element.

attributeName - The name of the attribute of the child.

Returns:

an attribute or null if the child does not exist.

getChildText

public static java.lang.String getChildText(org.w3c.dom.Element parent,
                                            java.lang.String namespaceURI,
                                            java.lang.String childName)
                                     throws XMLParseException

Gets the concatenated text children, trimmed of surrounding whitespace, of the named child element of the specified parent.

Parameters:

parent - The parent Element.

namespaceURI - The URI for the namespace of the child element.

childName - The name of the child element.

Returns:

a String containing the concatenated text children, trimmed of surrounding white space, or null if the parent does not contain the specified child.

Throws:

XMLParseException - If there is a system problem parsing the value.

getChildText

public static java.lang.String getChildText(org.w3c.dom.Node parent)
                                     throws XMLParseException

Extract the XML sub-tree beneath the given node and return as an XML string.

Parameters:

parent - Parent node

Returns:

XML sub-tree as a string.

Throws:

XMLParseException - If an internal problem occurs.

elementToString

public static java.lang.String elementToString(org.w3c.dom.Element element)
                                        throws XMLParseException

Converts an Element to its String representation. This is similar to xmlDOMToString but omits an XML header.

Parameters:

element - Element to convert.

Returns:

string

Throws:

XMLParseException - If an internal problem occurs.