com.caucho.xpath
Class XPath

java.lang.Object
  extended by 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
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.