com.caucho.xpath

Class XPath

java.lang.Object

com.caucho.xpath.XPath

public class XPath
extends java.lang.Object

Public facade for selecting nodes and creating match patterns.

Applications can select nodes directly from the XPath facade. For example,

 Node verse = XPath.find("chapter/verse", node);
 

For greater efficiency, applications can also precompile the match patterns.

 Pattern pattern = XPath.parseSelect("chapter/verse");
 Node verse = pattern.find(node);
 

XPath can also return values based on XPath expressions, following the XPath expression syntax. Applications can use the expressions for the equivalent of xsl:value-of

 Expr expr = XPath.parseExpr("chapter/verse/@id + 1");
 double value = expr.evalNumber(node);
 

To support the XPath pattern variables, XPath uses an environment object. Most applications will not need to use it.

Method Summary

Modifier and Type	Method and Description
static Env	createCall(Env parent) Creates a new variable environment based on an old environment.
static Env	createEnv() Creates a new variable environment.
static Env	createEnv(Env global) Creates a new variable environment based on an old environment.
static boolean	evalBoolean(java.lang.String query, org.w3c.dom.Node node) Evaluates an XPath expression, returning a boolean.
static double	evalNumber(java.lang.String query, org.w3c.dom.Node node) Evaluates an XPath expression, returning a double.
static java.lang.Object	evalObject(java.lang.String query, org.w3c.dom.Node node) Evaluates an XPath expression, returning an object
static java.lang.String	evalString(java.lang.String query, org.w3c.dom.Node node) Evaluates an XPath expression, returning a string.
static org.w3c.dom.Node	find(java.lang.String query, org.w3c.dom.Node node) Finds a node based on an XPath pattern.
static void	freeEnv(Env env) Free an environment.
static Expr	parseExpr(java.lang.String query) Parses an XPath expression for later evaluation.
static Expr	parseExpr(java.lang.String query, NamespaceContext namespace) Parses an XPath expression for later evaluation.
static Expr	parseExpr(java.lang.String query, NamespaceContext namespace, AbstractPattern nodeList) Parses an XPath expression for later evaluation.
static Pattern	parseMatch(java.lang.String query) Create a node match pattern.
static Pattern	parseMatch(java.lang.String query, NamespaceContext namespace) Create a node match pattern.
static Pattern	parseSelect(java.lang.String query) Create a node selection pattern.
static Pattern	parseSelect(java.lang.String query, NamespaceContext namespace) Create a node selection pattern.
static java.util.Iterator	select(java.lang.String query, org.w3c.dom.Node node) Selects all node matching an XPath pattern

Methods inherited from class java.lang.Object

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

Method Detail

find

public static org.w3c.dom.Node find(java.lang.String query,
                                    org.w3c.dom.Node node)
                             throws XPathException

Finds a node based on an XPath pattern. The pattern is relative to the node so XPath.find("child", node) will find children, not grandchildren.

Parameters:

query - XPath select pattern.

node - XML node to start searching from.

Returns:

The first matching node in document order.

Throws:

XPathException

select

public static java.util.Iterator select(java.lang.String query,
                                        org.w3c.dom.Node node)
                                 throws XPathException

Selects all node matching an XPath pattern

Parameters:

query - XPath select pattern.

node - XML node to start searching from.

Returns:

An iterator of nodes matching the pattern.

Throws:

XPathException

parseSelect

public static Pattern parseSelect(java.lang.String query)
                           throws XPathParseException

Create a node selection pattern. The pattern matches relative to the current node.

Parameters:

query - XPath select pattern.

Returns:

a pattern that can later select nodes.

Throws:

XPathParseException

parseSelect

public static Pattern parseSelect(java.lang.String query,
                                  NamespaceContext namespace)
                           throws XPathParseException

Create a node selection pattern. The pattern matches relative to the current node.

XSLT uses this version of parseSelect for proper namespace matching.

Parameters:

query - XPath select pattern.

namespace - the appropriate namespace mappings

Returns:

a pattern that can later select nodes.

Throws:

XPathParseException

parseMatch

public static Pattern parseMatch(java.lang.String query)
                          throws XPathParseException

Create a node match pattern. Match patterns are intended to test if a node matches the pattern. They do not work well for finding or selecting patterns. Essentially, a match pattern of 'foo[@bar]' is equivalent to a select pattern of '//foo[@bar]', but with less overhead.

Parameters:

query - XPath match pattern.

Returns:

a pattern that can later be used for isMatch.

Throws:

XPathParseException

parseMatch

public static Pattern parseMatch(java.lang.String query,
                                 NamespaceContext namespace)
                          throws XPathParseException

Create a node match pattern. Match patterns are intended to test if a node matches the pattern. They do not work well for finding or selecting patterns. Essentially, a match pattern of 'foo[@bar]' is equivalent to a select pattern of '//foo[@bar]', but with less overhead.

Parameters:

query - XPath match pattern.

namespace - the appropriate namespace mappings.

Returns:

a pattern that can later be used for isMatch.

Throws:

XPathParseException

evalString

public static java.lang.String evalString(java.lang.String query,
                                          org.w3c.dom.Node node)
                                   throws XPathException

Evaluates an XPath expression, returning a string. evalString works like the XSL value-of element.

For example, to get the value of an attribute use:

 String value = XPath.evalString("@id", node);
 

Parameters:

query - XPath expression

node - the node context

Returns:

the string result of the expression.

Throws:

XPathException

evalNumber

public static double evalNumber(java.lang.String query,
                                org.w3c.dom.Node node)
                         throws XPathException

Evaluates an XPath expression, returning a double.

Parameters:

query - XPath expression

node - the node context

Returns:

the number result of the expression.

Throws:

XPathException

evalBoolean

public static boolean evalBoolean(java.lang.String query,
                                  org.w3c.dom.Node node)
                           throws XPathException

Evaluates an XPath expression, returning a boolean.

Parameters:

query - XPath expression

node - the node context

Returns:

the boolean result of the expression.

Throws:

XPathException

evalObject

public static java.lang.Object evalObject(java.lang.String query,
                                          org.w3c.dom.Node node)
                                   throws XPathException

Evaluates an XPath expression, returning an object

Parameters:

query - XPath expression

node - the node context

Returns:

the result of the expression.

Throws:

XPathException

parseExpr

public static Expr parseExpr(java.lang.String query)
                      throws XPathParseException

Parses an XPath expression for later evaluation.

Parameters:

query - XPath expression

Returns:

the result of the expression.

Throws:

XPathParseException

parseExpr

public static Expr parseExpr(java.lang.String query,
                             NamespaceContext namespace)
                      throws XPathParseException

Parses an XPath expression for later evaluation.

Parameters:

query - XPath expression

namespace - namespace context

Returns:

the compiled expression

Throws:

XPathParseException

parseExpr

public static Expr parseExpr(java.lang.String query,
                             NamespaceContext namespace,
                             AbstractPattern nodeList)
                      throws XPathParseException

Parses an XPath expression for later evaluation.

Parameters:

query - XPath expression

namespace - namespace context

nodeList - containing nodeList pattern

Returns:

the compiled expression

Throws:

XPathParseException

createEnv

public static Env createEnv()

Creates a new variable environment.

createEnv

public static Env createEnv(Env global)

Creates a new variable environment based on an old environment.

This lets environments share globals even through function calls.

createCall

public static Env createCall(Env parent)

Creates a new variable environment based on an old environment.

This lets environments share globals even through function calls.

freeEnv

public static void freeEnv(Env env)

Free an environment.