org.apache.oodt.commons.util

Class XML

java.lang.Object

org.apache.oodt.commons.util.XML

public class XML
extends Object

XML services. This class provides several XML convenience services and encapsulates the underlying XML implementation, allowing it to vary without impacting developers.

Author:

Kelly

Field Summary

Fields

Modifier and Type	Field and Description
static Document	EMPTY_DOCUMENT An empty XML DOM document.
static EntityResolver	ENTERPRISE_ENTITY_RESOLVER The resolver for entities for the JPL enterprise.

Constructor Summary

Constructors

Constructor and Description
XML()

Method Summary

Modifier and Type	Method and Description
static void	add(Node node, String name, Collection values) Add a repeating child element with text from the given collection to the given node.
static void	add(Node node, String name, Object object) Add a child element with the string representation of the given object to the given node.
static void	add(Node node, String name, String text) Add a child element with the given text to the given element.
static void	addNonNull(Node node, String name, String text) Add a child element with the given text to the given element.
static Document	createDocument() Create a DOM document.
static DOMParser	createDOMParser() Create a DOM parser.
static SAXParser	createSAXParser() Create a SAX parser.
static void	dump(PrintWriter writer, Node node) Dump the structure of the DOM tree rooted at the given node to the given writer.
static String	escape(String source) Escapes a string so it may be printed as text content or attribute value.
static DOMImplementation	getDOMImplementation() Get the DOM implementation.
static Document	parse(InputSource inputSource) Parse the given XML document into a DOM tree.
static Document	parse(InputStream inputStream) Parse the given XML document into a DOM tree.
static Document	parse(Reader reader) Parse the given XML document into a DOM tree.
static Document	parse(String string) Parse the given XML document into a DOM tree.
static void	removeComments(Node node) Remove all comments from the given document node's subtree.
static String	serialize(Document doc) Serialize an XML DOM document into a String.
static String	serialize(Document doc, boolean omitXMLDeclaration) Serialize an XML DOM document into a String.
static void	serialize(Document doc, Writer writer) Serialize an XML DOM document into a writer.
static void	serialize(Document doc, Writer writer, boolean omitXMLDeclaration) Serialize an XML DOM document into a writer.
static String	text(Node node) Get the text from the given DOM node.
static String	unwrappedText(Node node) Get unwrapped text from the given DOM node This method unwraps any wrapped text.

Methods inherited from class java.lang.Object

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

Field Detail

ENTERPRISE_ENTITY_RESOLVER

public static final EntityResolver ENTERPRISE_ENTITY_RESOLVER

The resolver for entities for the JPL enterprise.

EMPTY_DOCUMENT

public static final Document EMPTY_DOCUMENT

An empty XML DOM document. This is handy for some basic operations, and for fetching the DOM implementation.

Constructor Detail

XML

public XML()

Method Detail

getDOMImplementation

public static DOMImplementation getDOMImplementation()

Get the DOM implementation.

Returns:

The DOM implementation.

createDocument

public static Document createDocument()

Create a DOM document.

Returns:

A new DOM document.

createDOMParser

public static DOMParser createDOMParser()

Create a DOM parser. This method creates a new DOM parser that has validation turned on and ignorable whitespace not included, and has a default error handler that prints error messages and warnings to the standard error stream.

Returns:

A new DOM parser.

createSAXParser

public static SAXParser createSAXParser()

Create a SAX parser. This method creates a new, default SAX parser. It's set up with a default error handler that just prints messages to the standard error stream.

Returns:

A new SAX parser.

serialize

public static String serialize(Document doc,
                               boolean omitXMLDeclaration)

Serialize an XML DOM document into a String. This method takes a DOM document and pretty-prints (or pretty-serializes, in XML parlance) it into a string.

Parameters:

doc - The document.

omitXMLDeclaration - True if we should omit the XML declaration, false to keep the XML declaration.

Returns:

The pretty-serialized, stringified, document.

serialize

public static String serialize(Document doc)

Serialize an XML DOM document into a String. This method takes a DOM document and pretty-prints (or pretty-serializes, in XML parlance) it into a string.

Parameters:

doc - The document.

Returns:

The pretty-serialized, stringified, document.

serialize

public static void serialize(Document doc,
                             Writer writer,
                             boolean omitXMLDeclaration)

Serialize an XML DOM document into a writer. This method takes a DOM document and pretty-prints (or pretty-serializes, in XML parlance) it into a writer.

Parameters:

doc - The document.

writer - Where to write it.

omitXMLDeclaration - True if we should omit the XML declaration, false to keep the XML declaration.

Throws:

IOException - If an I/O error occurs.

serialize

public static void serialize(Document doc,
                             Writer writer)

Serialize an XML DOM document into a writer. This method takes a DOM document and pretty-prints (or pretty-serializes, in XML parlance) it into a writer.

Parameters:

doc - The document.

writer - Where to write it.

Throws:

IOException - If an I/O error occurs.

parse

public static Document parse(InputSource inputSource)
                      throws SAXException,
                             IOException

Parse the given XML document into a DOM tree.

Parameters:

inputSource - The XML document to parse.

Returns:

A DOM tree for the given XML document.

Throws:

SAXException - If a parse error occurs.

IOException - If an I/O error occurs.

parse

public static Document parse(String string)
                      throws SAXException

Parse the given XML document into a DOM tree.

Parameters:

string - The XML document to parse.

Returns:

A DOM tree for the given XML document.

Throws:

SAXException - If a parse error occurs.

parse

public static Document parse(Reader reader)
                      throws SAXException,
                             IOException

Parse the given XML document into a DOM tree.

Parameters:

reader - The XML document to parse.

Returns:

A DOM tree for the given XML document.

Throws:

SAXException - If a parse error occurs.

IOException - If an I/O error occurs.

parse

public static Document parse(InputStream inputStream)
                      throws SAXException,
                             IOException

Parse the given XML document into a DOM tree.

Parameters:

inputStream - The XML document to parse.

Returns:

A DOM tree for the given XML document.

Throws:

SAXException - If a parse error occurs.

IOException - If an I/O error occurs.

add

public static void add(Node node,
                       String name,
                       Collection values)
                throws DOMException

Add a repeating child element with text from the given collection to the given node. For example, if values is a List with strings items "a", "b", and "c", and name is "value", then the XML document will have

<value>a</value>
 <value>b</value>
 <value>c</value>

appended to node.

Parameters:

node - Node to which to add child elements.

name - Name to give each child element.

values - Collection of values to assign to each child element, in iterator order.

Throws:

DOMException - If a DOM error occurs.

addNonNull

public static void addNonNull(Node node,
                              String name,
                              String text)
                       throws DOMException

Add a child element with the given text to the given element. This method modifies your DOM tree so that

<node>
   ...
 </node>

becomes

<node>
   ...
   <name>text>/name>
 </node>

Adding a null name does nothing. Adding null text won't add the element.

Parameters:

node - Node to which to add a child element.

name - Name of the child element to add to node.

text - What text the text-node child the child element named name should have. If null, nothing happens.

Throws:

DOMException - If a DOM error occurs.

add

public static void add(Node node,
                       String name,
                       String text)
                throws DOMException

Add a child element with the given text to the given element. This method modifies your DOM tree so that

<node>
   ...
 </node>

becomes

<node>
   ...
   <name>text>/name>
 </node>

Adding a null name does nothing. Adding null text results in an empty name tag.

Parameters:

node - Node to which to add a child element.

name - Name of the child element to add to node.

text - What text the text-node child the child element named name should have.

Throws:

DOMException - If a DOM error occurs.

add

public static void add(Node node,
                       String name,
                       Object object)
                throws DOMException

Add a child element with the string representation of the given object to the given node. This method modifies your DOM tree so that

<node>
   ...
 </node>

becomes

<node>
   ...
   <name>string-rep>/name>
 </node>

Adding a null name does nothing. Adding null object results in an empty name tag.

Parameters:

node - Node to which to add a child element.

name - Name of the child element to add to node.

object - The string representation of the object to have as the text-node child the child element named name.

Throws:

DOMException - If a DOM error occurs.

unwrappedText

public static String unwrappedText(Node node)

Get unwrapped text from the given DOM node This method unwraps any wrapped text. For example, if the document contains

<node>Hello, world.  This is
    my first document.
 </node>

then the node's unwrapped text is

Hello, world.  This is my first document.

while the text(org.w3c.dom.Node) method would return the wrapped value

Hello, world.  This is
    my first document.

In other words, it collects the text nodes under the given node and replaces strings of newlines and spaces with a single space. Unwrapping a null node returns a null string.

Parameters:

node - The node.

Returns:

The text in its children, unwrapped.

text

public static String text(Node node)

Get the text from the given DOM node. Getting text from a null node gives you a null string.

Parameters:

node - The node.

Returns:

The text in its children.

dump

public static void dump(PrintWriter writer,
                        Node node)

Dump the structure of the DOM tree rooted at the given node to the given writer. This outputs the tree structure including the type of each node, its name, and its value. Note that for many nodes, the name isn't useful (the name of text nodes, for example, is #text), and for many nodes, the value is null.

Parameters:

writer - The writer to which write the tree structure.

node - The tree to output.

removeComments

public static void removeComments(Node node)

Remove all comments from the given document node's subtree.

Parameters:

node - Node from which to search for comments to nuke.

escape

public static String escape(String source)

Escapes a string so it may be printed as text content or attribute value. Non printable characters are escaped using character references. Where the format specifies a deault entity reference, that reference is used (e.g. <).

Taken from Xerces 1.0.3. Apache license applies; see source code for license.

Parameters:

source - The string to escape

Returns:

The escaped string