com.abstractics.utils.xml
Class DOMUtils

java.lang.Object
  com.abstractics.utils.xml.DOMUtils

public final class DOMUtils

extends java.lang.Object

Various utility methods to deal with parsing XML into Document Object Models, getting values from a DOM, and transforming a DOM back into XML.
All parsing activities rely on the JDK javax.xml.parsers.DocumentBuilderFactory for parsing.
All transformation activities rely on the JDK javax.xml.transform.TransformerFactory for transformation.

Version:

$Id: DOMUtils.java,v 1.2 2006/03/15 05:37:32 andyman99 Exp $

Author:

Andrew Lawrence, Copyright 2006 Abstractics, L.L.C., Licensed under the Apache License, Version 2.0

Method Summary

static org.w3c.dom.Element[]	getDirectChildren(org.w3c.dom.Node node) Returns all direct children of the given node (children where type = Node.ELEMENT_NODE).
static org.w3c.dom.Element[]	getDirectChildrenOfName(java.lang.String nodeName, org.w3c.dom.Node node) Returns any direct children of the given node (children where type = Node.ELEMENT_NODE) that have the name specified.
static org.w3c.dom.Element	getElement(org.w3c.dom.Node startNode, java.lang.String path) Given a starting node and a "path" this method will return the element at the end of that path. The path is an XPath-ish type string consisting of sub-element names separated by a forward slash.
static java.lang.String	getText(org.w3c.dom.Node node) Returns the node value of the first Node.TEXT_NODE child of the given node.
static java.lang.String	getValue(org.w3c.dom.Node startNode, java.lang.String path) Given a starting node and a "path" this method will return the text at the end of that path. The path is an XPath-ish type string consisting of sub-element names separated by a forward slash.
static java.lang.String[]	getValueNames(org.w3c.dom.Node node) Given a Node, this method returns all of the attribute names that are available for it (non-null values).
static org.w3c.dom.Document	parseDOM(java.io.File file) Given a file containing XML, this method parses it into a DOM Document
static org.w3c.dom.Document	parseDOM(java.io.InputStream is) Given an InputStream of XML, this method parses it into a DOM Document
static org.w3c.dom.Document	parseDOM(java.io.Reader reader) Given a Reader of XML, this method parses it into a DOM Document
static org.w3c.dom.Document	parseDOM(java.lang.String xml) Given a String containing XML, this method parses it into a DOM Document
static java.lang.String	transformToXmlString(org.w3c.dom.Node node) Returns a String that contains XML for the given Node

Methods inherited from class java.lang.Object

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

Method Detail

getValue

public static java.lang.String getValue(org.w3c.dom.Node startNode,
                                        java.lang.String path)

Given a starting node and a "path" this method will return the text at the end of that path.
The path is an XPath-ish type string consisting of sub-element names separated by a forward slash. The difference being that the last element in the path can be an attribute or a text value, it doesn't matter.
An example path might be "foo/bar/test". This path assumes that the given element will have a child element called "foo", and that element will have a child element called "bar", and that element will have either an attribute called "test", or a child element called "test". The value returned will either be the value of the attribute, or the text of the element.
In any case, if the path cannot be found, null is returned.

As an example, asking for the value of "foo" from each of the following XML examples will yield the same result:

     <element foo="value" />
     
     <element><foo>value</foo></element>
 

Parameters:

startNode - The node to start from

path - A simple XPath-ish descriptor for what to return.

Returns:

String value of the attribute/element found at the end of the path given.

getElement

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

Given a starting node and a "path" this method will return the element at the end of that path.
The path is an XPath-ish type string consisting of sub-element names separated by a forward slash. The element found at the last part of the path is then returned.
An example path might be "foo/bar/test". This path assumes that the given element will have a child element called "foo", and that element will have a child element called "bar", and that element will have a child element called "test". The "test" element object is then returned.
In any case, if the path cannot be found, null is returned.

Parameters:

startNode - The node to start from

path - A simple XPath-ish descriptor for what to return.

Returns:

parseDOM

public static org.w3c.dom.Document parseDOM(java.io.File file)
                                     throws XmlException,
                                            java.io.FileNotFoundException

Given a file containing XML, this method parses it into a DOM Document

Parameters:

file - File object pointing to an XML file

Returns:

Resulting Document object

Throws:

XmlException - Thrown if there is an error in parsing

java.io.FileNotFoundException - Thrown if the given file cannot be found

java.lang.NullPointerException - Thrown if the File is null

parseDOM

public static org.w3c.dom.Document parseDOM(java.lang.String xml)
                                     throws XmlException

Given a String containing XML, this method parses it into a DOM Document

Parameters:

xml - String containing XML

Returns:

Resulting Document object

Throws:

XmlException - Thrown if there is an error in parsing

java.lang.NullPointerException - Thrown if the String is null

transformToXmlString

public static java.lang.String transformToXmlString(org.w3c.dom.Node node)
                                             throws XmlException

Returns a String that contains XML for the given Node

Parameters:

node - Node to transform

Returns:

String containing the XML for the node

Throws:

XmlException - Thrown if there is a parsing/transforming exception

getDirectChildrenOfName

public static org.w3c.dom.Element[] getDirectChildrenOfName(java.lang.String nodeName,
                                                            org.w3c.dom.Node node)

Returns any direct children of the given node (children where type = Node.ELEMENT_NODE) that have the name specified.

Parameters:

nodeName -

node -

Returns:

Returns an array of Element objects. Will not return null, but might return an empty array.

getDirectChildren

public static org.w3c.dom.Element[] getDirectChildren(org.w3c.dom.Node node)

Returns all direct children of the given node (children where type = Node.ELEMENT_NODE).

Parameters:

node -

Returns:

Returns an array of Element objects. Will not return null, but might return an empty array.

getText

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

Returns the node value of the first Node.TEXT_NODE child of the given node. Returns null if not found. Empty strings are also returned as null.

Parameters:

node -

Returns:

getValueNames

public static java.lang.String[] getValueNames(org.w3c.dom.Node node)

Given a Node, this method returns all of the attribute names that are available for it (non-null values). Attributes means any attribute of the node, or any child elements that have a text value.

So asking for the attribute names from each of the following XML examples will give back a single name of "foo":

     <element foo="value" />
     
     <element><foo>value</foo></element>
 

Parameters:

node -

Returns:

Returns an array of attribute names. Will not return null, but may return an empty array.

parseDOM

public static org.w3c.dom.Document parseDOM(java.io.InputStream is)
                                     throws XmlException

Given an InputStream of XML, this method parses it into a DOM Document

Parameters:

is -

Returns:

Resulting Document object

Throws:

XmlException - Thrown if there are parsing errors

java.lang.NullPointerException - Thrown if the InputStream is null

parseDOM

public static org.w3c.dom.Document parseDOM(java.io.Reader reader)
                                     throws XmlException

Given a Reader of XML, this method parses it into a DOM Document

Parameters:

reader - Reader object that points to a XML source

Returns:

Resulting Document object

Throws:

XmlException - Thrown if there is an error in parsing

java.lang.NullPointerException - Thrown if the InputStream is null