org.apache.excalibur.xml.xpath
Class XPathUtil

java.lang.Object
  org.apache.excalibur.xml.xpath.XPathUtil

public final class XPathUtil

extends java.lang.Object

This is a simple XPath helper class. It uses a faster approach for simple XPath expressions and can create XPaths. If you know that your XPath expression is simple, you should use this helper instead.

Version:

CVS $Id: XPathUtil.java,v 1.4 2004/02/28 11:47:15 cziegeler Exp $

Author:

Avalon Development Team

Constructor Summary

XPathUtil()

Method Summary

static java.lang.String[]	buildPathArray(java.lang.String xpath) Build the input for the get...FromPath methods.
static org.w3c.dom.Node	getFirstNodeFromPath(org.w3c.dom.Node contextNode, java.lang.String[] path, boolean create) Use a path to select the first occurence of a node.
static org.w3c.dom.NodeList	getNodeListFromPath(org.w3c.dom.Node contextNode, java.lang.String[] path) Use a path to select all occurences of a node.
static org.w3c.dom.Node	getSingleNode(XPathProcessor processor, org.w3c.dom.Node rootNode, java.lang.String path) Return the Node from the DOM Node rootNode using the XPath expression path.
static boolean	getValueAsBooleanOf(XPathProcessor processor, org.w3c.dom.Node root, java.lang.String path) Get the boolean value of the node specified by the XPath.
static boolean	getValueAsBooleanOf(XPathProcessor processor, org.w3c.dom.Node root, java.lang.String path, boolean defaultValue) Get the boolean value of the node specified by the XPath.
static java.lang.String	getValueOf(XPathProcessor processor, org.w3c.dom.Node root, java.lang.String path) Get the value of the node specified by the XPath.
static java.lang.String	getValueOf(XPathProcessor processor, org.w3c.dom.Node root, java.lang.String path, java.lang.String defaultValue) Get the value of the node specified by the XPath.
static java.lang.String	getValueOfNode(XPathProcessor processor, org.w3c.dom.Node node) Get the value of the DOM node.
static java.lang.String	getValueOfNode(XPathProcessor processor, org.w3c.dom.Node node, java.lang.String defaultValue) Get the value of the node.
static org.w3c.dom.NodeList	searchNodeList(XPathProcessor processor, org.w3c.dom.Node contextNode, java.lang.String str) Use an XPath string to select a nodelist.
static org.w3c.dom.Node	searchSingleNode(XPathProcessor processor, org.w3c.dom.Node contextNode, java.lang.String str) Use an XPath string to select a single node.

Methods inherited from class java.lang.Object

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

Constructor Detail

XPathUtil

public XPathUtil()

Method Detail

getSingleNode

public static org.w3c.dom.Node getSingleNode(XPathProcessor processor,
                                             org.w3c.dom.Node rootNode,
                                             java.lang.String path)
                                      throws XPathException

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 tests to values (e.g. [@id = 'du' and @number = 'you'], the attributes with the given values are added. The attributes must be separated with 'and'. Another problem are namespaces: XPath requires sometimes selectors for namespaces, e.g. : /*[namespace-uri()="uri" and local-name()="name"] Creating such a node with a namespace is not possible right now as we use a very simple XPath parser which is not able to parse all kinds of selectors correctly.

Parameters:

processor - The XPathProcessor

rootNode - The node to start the search.

path - XPath expression for searching the node.

Returns:

The node specified by the path.

Throws:

XPathException - If no path is specified or the XPath engine fails.

searchSingleNode

public static org.w3c.dom.Node searchSingleNode(XPathProcessor processor,
                                                org.w3c.dom.Node contextNode,
                                                java.lang.String str)

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 (getSingleNode(XPathProcessor, Node ,String )).

Parameters:

contextNode - The node to start searching from.

str - A valid XPath string.

Returns:

The first node found that matches the XPath, or null.

searchNodeList

public static org.w3c.dom.NodeList searchNodeList(XPathProcessor processor,
                                                  org.w3c.dom.Node contextNode,
                                                  java.lang.String str)

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 NodeList, should never be null.

buildPathArray

public static java.lang.String[] buildPathArray(java.lang.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 org.w3c.dom.Node getFirstNodeFromPath(org.w3c.dom.Node contextNode,
                                                    java.lang.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 org.w3c.dom.NodeList getNodeListFromPath(org.w3c.dom.Node contextNode,
                                                       java.lang.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]...

getValueOf

public static java.lang.String getValueOf(XPathProcessor processor,
                                          org.w3c.dom.Node root,
                                          java.lang.String path)
                                   throws XPathException

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:

XPathException

getValueOf

public static java.lang.String getValueOf(XPathProcessor processor,
                                          org.w3c.dom.Node root,
                                          java.lang.String path,
                                          java.lang.String defaultValue)
                                   throws XPathException

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:

XPathException

getValueAsBooleanOf

public static boolean getValueAsBooleanOf(XPathProcessor processor,
                                          org.w3c.dom.Node root,
                                          java.lang.String path)
                                   throws XPathException

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:

XPathException - If the node is not found.

getValueAsBooleanOf

public static boolean getValueAsBooleanOf(XPathProcessor processor,
                                          org.w3c.dom.Node root,
                                          java.lang.String path,
                                          boolean defaultValue)
                                   throws XPathException

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:

XPathException

getValueOfNode

public static java.lang.String getValueOfNode(XPathProcessor processor,
                                              org.w3c.dom.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 java.lang.String getValueOfNode(XPathProcessor processor,
                                              org.w3c.dom.Node node,
                                              java.lang.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.