org.apache.cocoon.xml.dom
Class DOMUtil

java.lang.Object
  extended by org.apache.cocoon.xml.dom.DOMUtil

public final class DOMUtil
extends Object

This class is a utility class for miscellaneous DOM functions, like getting and setting values of nodes.

Version:
$Id: DOMUtil.html 1304258 2012-03-23 10:09:27Z ilgrosso $
Author:
Carsten Ziegeler

Constructor Summary
DOMUtil()
           
 
Method Summary
static String[] buildPathArray(String xpath)
          Build the input for the get...FromPath methods.
static boolean compareAttributes(Element first, Element second)
          Compare all attributes of two elements.
static Document createDocument()
          Create a new empty DOM document.
static SourceParameters createParameters(Node fragment, SourceParameters source)
          Create a parameter object from xml.
static String createText(DocumentFragment fragment)
          Create a string from a DOM document fragment.
static DocumentFragment getDocumentFragment(SAXParser parser, Reader stream)
          Get a document fragment from a Reader.
static Node getFirstNodeFromPath(Node contextNode, String[] path, boolean create)
          Use a path to select the first occurence of a node.
static NodeList getNodeListFromPath(Node contextNode, String[] path)
          Use a path to select all occurences of a node.
static Document getOwnerDocument(Node node)
          Get the owner of the DOM document belonging to the node.
static Node getSingleNode(Node contextNode, String str)
          Use an XPath string to select a single node.
static Node getSingleNode(Node contextNode, String str, XPathProcessor processor)
          Use an XPath string to select a single node.
static boolean getValueAsBooleanOf(Node root, String path)
          Deprecated. To be removed in 2.2.
static boolean getValueAsBooleanOf(Node root, String path, boolean defaultValue)
          Deprecated. To be removed in 2.2.
static boolean getValueAsBooleanOf(Node root, String path, boolean defaultValue, XPathProcessor processor)
          Get the boolean value of the node specified by the XPath.
static boolean getValueAsBooleanOf(Node root, String path, XPathProcessor processor)
          Get the boolean value of the node specified by the XPath.
static String getValueOf(Node root, String path)
          Deprecated. To be removed in 2.2.
static String getValueOf(Node root, String path, String defaultValue)
          Deprecated. To be removed in 2.2.
static String getValueOf(Node root, String path, String defaultValue, XPathProcessor processor)
          Get the value of the node specified by the XPath.
static String getValueOf(Node root, String path, XPathProcessor processor)
          Get the value of the node specified by the XPath.
static String getValueOfNode(Node node)
          Get the value of the DOM node.
static String getValueOfNode(Node node, String defaultValue)
          Get the value of the node.
static String getValueOfNode(XPathProcessor processor, Node root, String path)
          Get the value of the node specified by the XPath.
static String getValueOfNode(XPathProcessor processor, Node root, String path, String defaultValue)
          Get the value of the node specified by the XPath.
static boolean getValueOfNodeAsBoolean(XPathProcessor processor, Node root, String path)
          Get the boolean value of the node specified by the XPath.
static boolean getValueOfNodeAsBoolean(XPathProcessor processor, Node root, String path, boolean defaultValue)
          Get the boolean value of the node specified by the XPath.
static String node2String(Node node)
          Deprecated. Use XMLUtils.serializeNodeToXML(Node) instead. To be removed in 2.2.
static String node2String(Node node, boolean pretty)
          Deprecated. Please use XMLUtils.serializeNode(Node, Properties) instead. To be removed in 2.2.
static StringBuffer node2StringBuffer(Node node)
          Deprecated. Please use XMLUtils.serializeNodeToXML(Node) instead. To be removed in 2.2.
static StringBuffer node2StringBuffer(Node node, boolean pretty, String indent)
          Deprecated. Please use XMLUtils.serializeNode(Node, Properties) instead. To be removed in 2.2.
static NodeList selectNodeList(Node contextNode, String str)
          Deprecated. To be removed in 2.2.
static NodeList selectNodeList(Node contextNode, String str, XPathProcessor processor)
          Use an XPath string to select a nodelist.
static Node selectSingleNode(Node rootNode, String path)
          Deprecated. To be removed in 2.2.
static Node selectSingleNode(Node rootNode, String path, XPathProcessor processor)
          Return the Node from the DOM Node rootNode using the XPath expression path.
static void setValueOfNode(Node node, String value)
          Set the value of the DOM node.
static void valueOf(Node parent, Collection v)
          Implementation for java.util.Collection : outputs the value by calling valueOf(Node, Object) on each element of the collection.
static void valueOf(Node parent, Map v)
          Implementation for java.util.Map : For each entry an element is created with the childs key and value Outputs the value and the key by calling valueOf(Node, Object) on each value and key of the Map.
static void valueOf(Node parent, Node v)
          Implementation for org.w3c.dom.Node : converts the Node to a SAX event stream.
static void valueOf(Node parent, Object v)
          Implementation for Object depending on its class : if it's an array, call valueOf(Node, Object) on all its elements, if it's class has a specific valueOf(Node, Object) implementation, use it, else, output it's string representation.
static void valueOf(Node parent, String text)
          Implementation for String : outputs characters representing the value.
static void valueOf(Node parent, XMLizable v)
          Implementation for XMLizable : outputs the value by calling v.toSax(contentHandler).
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

DOMUtil

public DOMUtil()
Method Detail

getOwnerDocument

public static Document getOwnerDocument(Node node)
Get the owner of the DOM document belonging to the node. This works even if the node is the document itself.

Parameters:
node - The node.
Returns:
The corresponding document.

getValueOfNode

public static String getValueOfNode(XPathProcessor processor,
                                    Node root,
                                    String path)
                             throws ProcessingException
Get the value of the node specified by the XPath. This works similar to <xsl:value-of>. If the node does not exist null is returned.

Parameters:
root - The node to start the search.
path - XPath search expression.
Returns:
The value of the node or null
Throws:
ProcessingException

getValueOfNode

public static String getValueOfNode(XPathProcessor processor,
                                    Node root,
                                    String path,
                                    String defaultValue)
                             throws ProcessingException
Get the value of the node specified by the XPath. This works similar to <xsl:value-of>. If the node is not found the defaultValue is returned.

Parameters:
root - The node to start the search.
path - XPath search expression.
defaultValue - The default value if the node does not exist.
Returns:
The value of the node or defaultValue
Throws:
ProcessingException

getValueOfNodeAsBoolean

public static boolean getValueOfNodeAsBoolean(XPathProcessor processor,
                                              Node root,
                                              String path)
                                       throws ProcessingException
Get the boolean value of the node specified by the XPath. This works similar to <xsl:value-of>. If the node exists and has a value this value is converted to a boolean, e.g. "true" or "false" as value will result into the corresponding boolean values.

Parameters:
root - The node to start the search.
path - XPath search expression.
Returns:
The boolean value of the node.
Throws:
ProcessingException - If the node is not found.

getValueOfNodeAsBoolean

public static boolean getValueOfNodeAsBoolean(XPathProcessor processor,
                                              Node root,
                                              String path,
                                              boolean defaultValue)
                                       throws ProcessingException
Get the boolean value of the node specified by the XPath. This works similar to <xsl:value-of>. If the node exists and has a value this value is converted to a boolean, e.g. "true" or "false" as value will result into the corresponding boolean values. If the node does not exist, the defaultValue is returned.

Parameters:
root - The node to start the search.
path - XPath search expression.
defaultValue - Default boolean value.
Returns:
The value of the node or defaultValue
Throws:
ProcessingException

getValueOfNode

public static String getValueOfNode(Node node)
Get the value of the DOM node. The value of a node is the content of the first text node. If the node has no text nodes, null is returned.


getValueOfNode

public static String getValueOfNode(Node node,
                                    String defaultValue)
Get the value of the node. The value of the node is the content of the first text node. If the node has no text nodes the defaultValue is returned.


setValueOfNode

public static void setValueOfNode(Node node,
                                  String value)
Set the value of the DOM node. All current children of the node are removed and a new text node with the value is appended.


getDocumentFragment

public static DocumentFragment getDocumentFragment(SAXParser parser,
                                                   Reader stream)
                                            throws ProcessingException
Get a document fragment from a Reader. The reader must provide valid XML, but it is allowed that the XML has more than one root node. This xml is parsed by the specified parser instance and a DOM DocumentFragment is created.

Throws:
ProcessingException

createParameters

public static SourceParameters createParameters(Node fragment,
                                                SourceParameters source)
Create a parameter object from xml. The xml is flat and consists of elements which all have exactly one text node: value_one value_two A parameter can occur more than once with different values. If source is not specified a new parameter object is created otherwise the parameters are added to source.


createText

public static String createText(DocumentFragment fragment)
Create a string from a DOM document fragment. Only the top level text nodes are chained together to build the text.


compareAttributes

public static boolean compareAttributes(Element first,
                                        Element second)
Compare all attributes of two elements. This method returns true only if both nodes have the same number of attributes and the same attributes with equal values. Namespace definition nodes are ignored


valueOf

public static void valueOf(Node parent,
                           String text)
                    throws ProcessingException
Implementation for String : outputs characters representing the value.

Parameters:
parent - The node getting the value
text - the value
Throws:
ProcessingException

valueOf

public static void valueOf(Node parent,
                           XMLizable v)
                    throws ProcessingException
Implementation for XMLizable : outputs the value by calling v.toSax(contentHandler).

Parameters:
parent - The node getting the value
v - the XML fragment
Throws:
ProcessingException

valueOf

public static void valueOf(Node parent,
                           Node v)
                    throws ProcessingException
Implementation for org.w3c.dom.Node : converts the Node to a SAX event stream.

Parameters:
parent - The node getting the value
v - the value
Throws:
ProcessingException

valueOf

public static void valueOf(Node parent,
                           Collection v)
                    throws ProcessingException
Implementation for java.util.Collection : outputs the value by calling valueOf(Node, Object) on each element of the collection.

Parameters:
parent - The node getting the value
v - the XML fragment
Throws:
ProcessingException

valueOf

public static void valueOf(Node parent,
                           Map v)
                    throws ProcessingException
Implementation for java.util.Map : For each entry an element is created with the childs key and value Outputs the value and the key by calling valueOf(Node, Object) on each value and key of the Map.

Parameters:
parent - The node getting the value
v - the Map
Throws:
ProcessingException

valueOf

public static void valueOf(Node parent,
                           Object v)
                    throws ProcessingException
Implementation for Object depending on its class :

Parameters:
parent - The node getting the value
v - the value
Throws:
ProcessingException

getSingleNode

public static Node getSingleNode(Node contextNode,
                                 String str,
                                 XPathProcessor processor)
                          throws TransformerException
Use an XPath string to select a single node. XPath namespace prefixes are resolved from the context node, which may not be what you want (see the next method).

Parameters:
contextNode - The node to start searching from.
str - A valid XPath string.
processor - The XPath processor to use
Returns:
The first node found that matches the XPath, or null.
Throws:
TransformerException

getSingleNode

public static Node getSingleNode(Node contextNode,
                                 String str)
                          throws TransformerException
Use an XPath string to select a single node. XPath namespace prefixes are resolved from the context node, which may not be what you want (see the next method).

Parameters:
contextNode - The node to start searching from.
str - A valid XPath string.
Returns:
The first node found that matches the XPath, or null.
Throws:
TransformerException

selectSingleNode

public static Node selectSingleNode(Node rootNode,
                                    String path)
                             throws ProcessingException
Deprecated. To be removed in 2.2.

Return the Node from the DOM Node rootNode using the XPath expression path. If the node does not exist, it is created and then returned. This is a very simple method for creating new nodes. If the XPath contains selectors ([,,,]) or "*" it is of course not possible to create the new node. So if you use such XPaths the node must exist beforehand. An simple exception is if the expression contains attribute test to values (e.g. [@id = 'du' and

Parameters:
rootNode - The node to start the search.
path - XPath expression for searching the node.
Returns:
The node specified by the path.
Throws:
ProcessingException - If no path is specified or the XPath engine fails.

selectSingleNode

public static Node selectSingleNode(Node rootNode,
                                    String path,
                                    XPathProcessor processor)
                             throws ProcessingException
Return the Node from the DOM Node rootNode using the XPath expression path. If the node does not exist, it is created and then returned. This is a very simple method for creating new nodes. If the XPath contains selectors ([,,,]) or "*" it is of course not possible to create the new node. So if you use such XPaths the node must exist beforehand. An simple exception is if the expression contains attribute test to values (e.g. [@id = 'du' and

Parameters:
rootNode - The node to start the search.
path - XPath expression for searching the node.
processor - The XPath processor to use
Returns:
The node specified by the path.
Throws:
ProcessingException - If no path is specified or the XPath engine fails.

getValueOf

public static String getValueOf(Node root,
                                String path)
                         throws ProcessingException
Deprecated. To be removed in 2.2.

Get the value of the node specified by the XPath. This works similar to <xsl:value-of>. If the node does not exist null is returned.

Parameters:
root - The node to start the search.
path - XPath search expression.
Returns:
The value of the node or null
Throws:
ProcessingException

getValueOf

public static String getValueOf(Node root,
                                String path,
                                XPathProcessor processor)
                         throws ProcessingException
Get the value of the node specified by the XPath. This works similar to <xsl:value-of>. If the node does not exist null is returned.

Parameters:
root - The node to start the search.
path - XPath search expression.
processor - The XPath processor to use
Returns:
The value of the node or null
Throws:
ProcessingException

getValueOf

public static String getValueOf(Node root,
                                String path,
                                String defaultValue)
                         throws ProcessingException
Deprecated. To be removed in 2.2.

Get the value of the node specified by the XPath. This works similar to <xsl:value-of>. If the node is not found the defaultValue is returned.

Parameters:
root - The node to start the search.
path - XPath search expression.
defaultValue - The default value if the node does not exist.
Returns:
The value of the node or defaultValue
Throws:
ProcessingException

getValueOf

public static String getValueOf(Node root,
                                String path,
                                String defaultValue,
                                XPathProcessor processor)
                         throws ProcessingException
Get the value of the node specified by the XPath. This works similar to <xsl:value-of>. If the node is not found the defaultValue is returned.

Parameters:
root - The node to start the search.
path - XPath search expression.
defaultValue - The default value if the node does not exist.
processor - The XPath Processor
Returns:
The value of the node or defaultValue
Throws:
ProcessingException

getValueAsBooleanOf

public static boolean getValueAsBooleanOf(Node root,
                                          String path)
                                   throws ProcessingException
Deprecated. To be removed in 2.2.

Get the boolean value of the node specified by the XPath. This works similar to <xsl:value-of>. If the node exists and has a value this value is converted to a boolean, e.g. "true" or "false" as value will result into the corresponding boolean values.

Parameters:
root - The node to start the search.
path - XPath search expression.
Returns:
The boolean value of the node.
Throws:
ProcessingException - If the node is not found.

getValueAsBooleanOf

public static boolean getValueAsBooleanOf(Node root,
                                          String path,
                                          XPathProcessor processor)
                                   throws ProcessingException
Get the boolean value of the node specified by the XPath. This works similar to <xsl:value-of>. If the node exists and has a value this value is converted to a boolean, e.g. "true" or "false" as value will result into the corresponding boolean values.

Parameters:
root - The node to start the search.
path - XPath search expression.
processor - The XPath Processor
Returns:
The boolean value of the node.
Throws:
ProcessingException - If the node is not found.

getValueAsBooleanOf

public static boolean getValueAsBooleanOf(Node root,
                                          String path,
                                          boolean defaultValue)
                                   throws ProcessingException
Deprecated. To be removed in 2.2.

Get the boolean value of the node specified by the XPath. This works similar to <xsl:value-of>. If the node exists and has a value this value is converted to a boolean, e.g. "true" or "false" as value will result into the corresponding boolean values. If the node does not exist, the defaultValue is returned.

Parameters:
root - The node to start the search.
path - XPath search expression.
defaultValue - Default boolean value.
Returns:
The value of the node or defaultValue
Throws:
ProcessingException

getValueAsBooleanOf

public static boolean getValueAsBooleanOf(Node root,
                                          String path,
                                          boolean defaultValue,
                                          XPathProcessor processor)
                                   throws ProcessingException
Get the boolean value of the node specified by the XPath. This works similar to <xsl:value-of>. If the node exists and has a value this value is converted to a boolean, e.g. "true" or "false" as value will result into the corresponding boolean values. If the node does not exist, the defaultValue is returned.

Parameters:
root - The node to start the search.
path - XPath search expression.
defaultValue - Default boolean value.
processor - The XPath Processor
Returns:
The value of the node or defaultValue
Throws:
ProcessingException

createDocument

public static Document createDocument()
                               throws ProcessingException
Create a new empty DOM document.

Throws:
ProcessingException

selectNodeList

public static NodeList selectNodeList(Node contextNode,
                                      String str)
                               throws TransformerException
Deprecated. To be removed in 2.2.

Use an XPath string to select a nodelist. XPath namespace prefixes are resolved from the contextNode.

Parameters:
contextNode - The node to start searching from.
str - A valid XPath string.
Returns:
A NodeIterator, should never be null.
Throws:
TransformerException

selectNodeList

public static NodeList selectNodeList(Node contextNode,
                                      String str,
                                      XPathProcessor processor)
                               throws TransformerException
Use an XPath string to select a nodelist. XPath namespace prefixes are resolved from the contextNode.

Parameters:
contextNode - The node to start searching from.
str - A valid XPath string.
processor - The XPath Processor
Returns:
A NodeIterator, should never be null.
Throws:
TransformerException

buildPathArray

public static String[] buildPathArray(String xpath)
Build the input for the get...FromPath methods. If the XPath expression cannot be handled by the methods, null is returned.


getFirstNodeFromPath

public static Node getFirstNodeFromPath(Node contextNode,
                                        String[] path,
                                        boolean create)
Use a path to select the first occurence of a node. The namespace of a node is ignored!

Parameters:
contextNode - The node starting the search.
path - The path to search the node. The contextNode is searched for a child named path[0], this node is searched for a child named path[1]...
create - If a child with the corresponding name is not found and create is set, this node will be created.

getNodeListFromPath

public static NodeList getNodeListFromPath(Node contextNode,
                                           String[] path)
Use a path to select all occurences of a node. The namespace of a node is ignored!

Parameters:
contextNode - The node starting the search.
path - The path to search the node. The contextNode is searched for a child named path[0], this node is searched for a child named path[1]...

node2String

public static String node2String(Node node)
Deprecated. Use XMLUtils.serializeNodeToXML(Node) instead. To be removed in 2.2.

Converts a org.w3c.dom.Node to a String. Uses Transformer to convert from a Node to a String.

Parameters:
node - a org.w3c.dom.Node value
Returns:
String representation of the document

node2String

public static String node2String(Node node,
                                 boolean pretty)
Deprecated. Please use XMLUtils.serializeNode(Node, Properties) instead. To be removed in 2.2.

Create a string representation of a org.w3c.dom.Node and any (most) subtypes.

Parameters:
node - a org.w3c.dom.Node value
pretty - a boolean value whether to format the XML
Returns:
a String value

node2StringBuffer

public static StringBuffer node2StringBuffer(Node node)
Deprecated. Please use XMLUtils.serializeNodeToXML(Node) instead. To be removed in 2.2.

Create a string representation of a org.w3c.dom.Node and any (most) subtypes.

Parameters:
node - a org.w3c.dom.Node value
Returns:
a StringBuffer value

node2StringBuffer

public static StringBuffer node2StringBuffer(Node node,
                                             boolean pretty,
                                             String indent)
Deprecated. Please use XMLUtils.serializeNode(Node, Properties) instead. To be removed in 2.2.

Create a string representation of a org.w3c.dom.Node and any (most) subtypes.

Parameters:
node - a org.w3c.dom.Node value
pretty - a boolean value whether to format the XML
indent - a String value containing spaces as initial indent, if null defaults to empty string.
Returns:
a StringBuffer value


Copyright © 1999-2010 The Apache Software Foundation. All Rights Reserved.