org.apache.xpath
Class XPath

java.lang.Object
  extended byorg.apache.xpath.XPath
All Implemented Interfaces:
ExpressionOwner, Serializable

public class XPath
extends Object
implements Serializable, ExpressionOwner

The XPath class wraps an expression object and provides general services for execution of that expression.

See Also:
Serialized Form

Field Summary
private static boolean DEBUG_MATCHES
          Set to true to get diagnostic messages about the result of match pattern testing.
private  Expression m_mainExp
          The top of the expression tree.
(package private)  String m_patternString
          The pattern string, mainly kept around for diagnostic purposes.
static int MATCH
          Represents a match type expression.
static double MATCH_SCORE_NODETEST
           The match score if the pattern consists of just a NodeTest.
static double MATCH_SCORE_NONE
           The match score if no match is made.
static double MATCH_SCORE_NSWILD
           The match score if the pattern pattern has the form NCName:*.
static double MATCH_SCORE_OTHER
           The match score if the pattern consists of something other than just a NodeTest or just a qname.
static double MATCH_SCORE_QNAME
           The match score if the pattern has the form of a QName optionally preceded by an @ character.
static int SELECT
          Represents a select type expression.
 
Constructor Summary
XPath(Expression expr)
          Construct an XPath object.
XPath(String exprString, javax.xml.transform.SourceLocator locator, PrefixResolver prefixResolver, int type)
          Construct an XPath object.
XPath(String exprString, javax.xml.transform.SourceLocator locator, PrefixResolver prefixResolver, int type, javax.xml.transform.ErrorListener errorListener)
          Construct an XPath object.
 
Method Summary
 void assertion(boolean b, String msg)
          Tell the user of an assertion error, and probably throw an exception.
 boolean bool(XPathContext xctxt, int contextNode, PrefixResolver namespaceContext)
           Given an expression and a context, evaluate the XPath and return the result.
 void callVisitors(ExpressionOwner owner, XPathVisitor visitor)
          This will traverse the heararchy, calling the visitor for each member.
 void error(XPathContext xctxt, int sourceNode, String msg, Object[] args)
          Tell the user of an error, and probably throw an exception.
 XObject execute(XPathContext xctxt, int contextNode, PrefixResolver namespaceContext)
           Given an expression and a context, evaluate the XPath and return the result.
 XObject execute(XPathContext xctxt, org.w3c.dom.Node contextNode, PrefixResolver namespaceContext)
           Given an expression and a context, evaluate the XPath and return the result.
 void fixupVariables(Vector vars, int globalsSize)
          This function is used to fixup variables from QNames to stack frame indexes at stylesheet build time.
 Expression getExpression()
          Get the raw Expression object that this class wraps.
 javax.xml.transform.SourceLocator getLocator()
          Get the SourceLocator on the expression object.
 double getMatchScore(XPathContext xctxt, int context)
          Get the match score of the given node.
 String getPatternString()
          Return the XPath string associated with this object.
 void installFunction(String name, int funcIndex, Function func)
          Install a built-in function.
 void setExpression(Expression exp)
          Set the raw expression object for this object.
 void warn(XPathContext xctxt, int sourceNode, String msg, Object[] args)
          Warn the user of an problem.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

m_mainExp

private Expression m_mainExp
The top of the expression tree.


m_patternString

String m_patternString
The pattern string, mainly kept around for diagnostic purposes.


SELECT

public static final int SELECT
Represents a select type expression.

See Also:
Constant Field Values

MATCH

public static final int MATCH
Represents a match type expression.

See Also:
Constant Field Values

DEBUG_MATCHES

private static final boolean DEBUG_MATCHES
Set to true to get diagnostic messages about the result of match pattern testing.

See Also:
Constant Field Values

MATCH_SCORE_NONE

public static final double MATCH_SCORE_NONE
The match score if no match is made.

See Also:
Constant Field Values

MATCH_SCORE_QNAME

public static final double MATCH_SCORE_QNAME
The match score if the pattern has the form of a QName optionally preceded by an @ character.

See Also:
Constant Field Values

MATCH_SCORE_NSWILD

public static final double MATCH_SCORE_NSWILD
The match score if the pattern pattern has the form NCName:*.

See Also:
Constant Field Values

MATCH_SCORE_NODETEST

public static final double MATCH_SCORE_NODETEST
The match score if the pattern consists of just a NodeTest.

See Also:
Constant Field Values

MATCH_SCORE_OTHER

public static final double MATCH_SCORE_OTHER
The match score if the pattern consists of something other than just a NodeTest or just a qname.

See Also:
Constant Field Values
Constructor Detail

XPath

public XPath(String exprString,
             javax.xml.transform.SourceLocator locator,
             PrefixResolver prefixResolver,
             int type,
             javax.xml.transform.ErrorListener errorListener)
      throws javax.xml.transform.TransformerException
Construct an XPath object. (Needs review -sc) This method initializes an XPathParser/ Compiler and compiles the expression.

Parameters:
exprString - The XPath expression.
locator - The location of the expression, may be null.
prefixResolver - A prefix resolver to use to resolve prefixes to namespace URIs.
type - one of SELECT or MATCH.
errorListener - The error listener, or null if default should be used.
Throws:
javax.xml.transform.TransformerException - if syntax or other error.

XPath

public XPath(String exprString,
             javax.xml.transform.SourceLocator locator,
             PrefixResolver prefixResolver,
             int type)
      throws javax.xml.transform.TransformerException
Construct an XPath object. (Needs review -sc) This method initializes an XPathParser/ Compiler and compiles the expression.

Parameters:
exprString - The XPath expression.
locator - The location of the expression, may be null.
prefixResolver - A prefix resolver to use to resolve prefixes to namespace URIs.
type - one of SELECT or MATCH.
Throws:
javax.xml.transform.TransformerException - if syntax or other error.

XPath

public XPath(Expression expr)
Construct an XPath object.

Parameters:
expr - The Expression object.
Throws:
javax.xml.transform.TransformerException - if syntax or other error.
Method Detail

getExpression

public Expression getExpression()
Get the raw Expression object that this class wraps.

Specified by:
getExpression in interface ExpressionOwner
Returns:
the raw Expression object, which should not normally be null.

fixupVariables

public void fixupVariables(Vector vars,
                           int globalsSize)
This function is used to fixup variables from QNames to stack frame indexes at stylesheet build time.

Parameters:
vars - List of QNames that correspond to variables. This list should be searched backwards for the first qualified name that corresponds to the variable reference qname. The position of the QName in the vector from the start of the vector will be its position in the stack frame (but variables above the globalsTop value will need to be offset to the current stack frame).

setExpression

public void setExpression(Expression exp)
Set the raw expression object for this object.

Specified by:
setExpression in interface ExpressionOwner
Parameters:
exp - the raw Expression object, which should not normally be null.

getLocator

public javax.xml.transform.SourceLocator getLocator()
Get the SourceLocator on the expression object.

Returns:
the SourceLocator on the expression object, which may be null.

getPatternString

public String getPatternString()
Return the XPath string associated with this object.

Returns:
the XPath string associated with this object.

execute

public XObject execute(XPathContext xctxt,
                       org.w3c.dom.Node contextNode,
                       PrefixResolver namespaceContext)
                throws javax.xml.transform.TransformerException
Given an expression and a context, evaluate the XPath and return the result.

Parameters:
xctxt - The execution context.
contextNode - The node that "." expresses.
namespaceContext - The context in which namespaces in the XPath are supposed to be expanded.
Returns:
The result of the XPath or null if callbacks are used.
Throws:
javax.xml.transform.TransformerException - thrown if the error condition is severe enough to halt processing.
javax.xml.transform.TransformerException

execute

public XObject execute(XPathContext xctxt,
                       int contextNode,
                       PrefixResolver namespaceContext)
                throws javax.xml.transform.TransformerException
Given an expression and a context, evaluate the XPath and return the result.

Parameters:
xctxt - The execution context.
contextNode - The node that "." expresses.
namespaceContext - The context in which namespaces in the XPath are supposed to be expanded.
Throws:
javax.xml.transform.TransformerException - thrown if the active ProblemListener decides the error condition is severe enough to halt processing.
javax.xml.transform.TransformerException

bool

public boolean bool(XPathContext xctxt,
                    int contextNode,
                    PrefixResolver namespaceContext)
             throws javax.xml.transform.TransformerException
Given an expression and a context, evaluate the XPath and return the result.

Parameters:
xctxt - The execution context.
contextNode - The node that "." expresses.
namespaceContext - The context in which namespaces in the XPath are supposed to be expanded.
Throws:
javax.xml.transform.TransformerException - thrown if the active ProblemListener decides the error condition is severe enough to halt processing.
javax.xml.transform.TransformerException

getMatchScore

public double getMatchScore(XPathContext xctxt,
                            int context)
                     throws javax.xml.transform.TransformerException
Get the match score of the given node.

Parameters:
xctxt - XPath runtime context.
context - The current source tree context node.
Returns:
score, one of MATCH_SCORE_NODETEST, MATCH_SCORE_NONE, MATCH_SCORE_OTHER, or MATCH_SCORE_QNAME.
Throws:
javax.xml.transform.TransformerException

installFunction

public void installFunction(String name,
                            int funcIndex,
                            Function func)
Install a built-in function.

Parameters:
name - The unqualified name of the function; not currently used.
funcIndex - The index of the function in the table.
func - An Implementation of an XPath Function object.
Returns:
the position of the function in the internal index.

warn

public void warn(XPathContext xctxt,
                 int sourceNode,
                 String msg,
                 Object[] args)
          throws javax.xml.transform.TransformerException
Warn the user of an problem.

Parameters:
xctxt - The XPath runtime context.
sourceNode - Not used.
msg - An error msgkey that corresponds to one of the constants found in XPATHErrorResources, which is a key for a format string.
args - An array of arguments represented in the format string, which may be null.
Throws:
javax.xml.transform.TransformerException - if the current ErrorListoner determines to throw an exception.

assertion

public void assertion(boolean b,
                      String msg)
Tell the user of an assertion error, and probably throw an exception.

Parameters:
b - If false, a runtime exception will be thrown.
msg - The assertion message, which should be informative.
Throws:
RuntimeException - if the b argument is false.

error

public void error(XPathContext xctxt,
                  int sourceNode,
                  String msg,
                  Object[] args)
           throws javax.xml.transform.TransformerException
Tell the user of an error, and probably throw an exception.

Parameters:
xctxt - The XPath runtime context.
sourceNode - Not used.
msg - An error msgkey that corresponds to one of the constants found in XPATHErrorResources, which is a key for a format string.
args - An array of arguments represented in the format string, which may be null.
Throws:
javax.xml.transform.TransformerException - if the current ErrorListoner determines to throw an exception.

callVisitors

public void callVisitors(ExpressionOwner owner,
                         XPathVisitor visitor)
This will traverse the heararchy, calling the visitor for each member. If the called visitor method returns false, the subtree should not be called.

Parameters:
owner - The owner of the visitor, where that path may be rewritten if needed.
visitor - The visitor whose appropriate method will be called.