org.apache.xpath
Class XPath

java.lang.Object
  |
  +--org.apache.xpath.XPath

public class XPath
extends java.lang.Object
implements java.io.Serializable

**For advanced use only** The XPath class wraps an expression object and provides general services for execution of that expression.

See Also:
Serialized Form

Field Summary
static int MATCH
          Represents a match type expression.
static double MATCH_SCORE_NODETEST
          **For advanced use only** The match score if the pattern consists of just a NodeTest.
static double MATCH_SCORE_NONE
          **For advanced use only** The match score if no match is made.
static double MATCH_SCORE_NSWILD
          **For advanced use only** The match score if the pattern pattern has the form NCName:*.
static double MATCH_SCORE_OTHER
          **For advanced use only** The match score if the pattern consists of something other than just a NodeTest or just a qname.
static double MATCH_SCORE_QNAME
          **For advanced use only** 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(java.lang.String exprString, SourceLocator locator, PrefixResolver prefixResolver, int type)
          Construct an XPath object.
XPath(java.lang.String exprString, SourceLocator locator, PrefixResolver prefixResolver, int type, ErrorListener errorListener)
          Construct an XPath object.
 
Method Summary
 void assert(boolean b, java.lang.String msg)
          Tell the user of an assertion error, and probably throw an exception.
 void error(XPathContext xctxt, Node sourceNode, int msg, java.lang.Object[] args)
          Tell the user of an error, and probably throw an exception.
 XObject execute(XPathContext xctxt, Node contextNode, PrefixResolver namespaceContext)
          **Experimental** Given an expression and a context, evaluate the XPath and call the callback as nodes are found.
 Expression getExpression()
          Get the raw Expression object that this class wraps.
 SourceLocator getLocator()
          Get the SourceLocator on the expression object.
 double getMatchScore(XPathContext xctxt, Node context)
          Get the match score of the given node.
 java.lang.String getPatternString()
          Return the XPath string associated with this object.
 void installFunction(java.lang.String name, int funcIndex, Function func)
          Install a built-in function.
 void setExpression(Expression exp)
          Set the raw expression object for this object.
 void setLocator(SourceLocator l)
          Set the SourceLocator on the expression object.
 void warn(XPathContext xctxt, Node sourceNode, int msg, java.lang.Object[] args)
          Warn the user of an problem.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

SELECT

public static final int SELECT
Represents a select type expression.

MATCH

public static final int MATCH
Represents a match type expression.

MATCH_SCORE_NONE

public static final double MATCH_SCORE_NONE
**For advanced use only** The match score if no match is made.

MATCH_SCORE_QNAME

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

MATCH_SCORE_NSWILD

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

MATCH_SCORE_NODETEST

public static final double MATCH_SCORE_NODETEST
**For advanced use only** The match score if the pattern consists of just a NodeTest.

MATCH_SCORE_OTHER

public static final double MATCH_SCORE_OTHER
**For advanced use only** The match score if the pattern consists of something other than just a NodeTest or just a qname.
Constructor Detail

XPath

public XPath(java.lang.String exprString,
             SourceLocator locator,
             PrefixResolver prefixResolver,
             int type,
             ErrorListener errorListener)
      throws TransformerException
Construct an XPath object. The object must be initialized by the XPathParser.initXPath method.
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:
TransformerException - if syntax or other error.

XPath

public XPath(java.lang.String exprString,
             SourceLocator locator,
             PrefixResolver prefixResolver,
             int type)
      throws TransformerException
Construct an XPath object. The object must be initialized by the XPathParser.initXPath method.
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:
TransformerException - if syntax or other error.
Method Detail

getExpression

public Expression getExpression()
Get the raw Expression object that this class wraps.
Returns:
the raw Expression object, which should not normally be null.

setExpression

public void setExpression(Expression exp)
Set the raw expression object for this object.
Parameters:
exp - the raw Expression object, which should not normally be null.

getLocator

public SourceLocator getLocator()
Get the SourceLocator on the expression object.
Returns:
the SourceLocator on the expression object, which may be null.

setLocator

public void setLocator(SourceLocator l)
Set the SourceLocator on the expression object.
Parameters:
l - the SourceLocator on the expression object, which may be null.

getPatternString

public java.lang.String getPatternString()
Return the XPath string associated with this object.
Returns:
the XPath string associated with this object.

execute

public XObject execute(XPathContext xctxt,
                       Node contextNode,
                       PrefixResolver namespaceContext)
                throws TransformerException
**Experimental** Given an expression and a context, evaluate the XPath and call the callback as nodes are found. Only some simple types of expresions right now can call back, so if this method returns null, then the callbacks have been called, otherwise a valid XObject will be returned.
Parameters:
xctxt - The execution context.
contextNode - The node that "." expresses.
namespaceContext - The context in which namespaces in the XPath are supposed to be expanded.
callback - Interface that implements the processLocatedNode method.
callbackInfo - Object that will be passed to the processLocatedNode method.
stopAtFirst - True if the search should stop once the first node in document order is found.
Returns:
The result of the XPath or null if callbacks are used.
Throws:
TransformerException - thrown if the active ProblemListener decides the error condition is severe enough to halt processing.
TransformerException - thrown if the error condition is severe enough to halt processing.
TransformerException -  

getMatchScore

public double getMatchScore(XPathContext xctxt,
                            Node context)
                     throws 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:
TransformerException -  

installFunction

public void installFunction(java.lang.String name,
                            int funcIndex,
                            Function func)
Install a built-in function.
Parameters:
name - The unqualified name of the function.
funcIndex - The index of the function in the table.
func - A Implementation of an XPath Function object.
Returns:
the position of the function in the internal index.

warn

public void warn(XPathContext xctxt,
                 Node sourceNode,
                 int msg,
                 java.lang.Object[] args)
          throws TransformerException
Warn the user of an problem.
Parameters:
xctxt - The XPath runtime context.
sourceNode - Not used.
msg - An error number that corresponds to one of the numbers 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:
TransformerException - if the current ErrorListoner determines to throw an exception.

assert

public void assert(boolean b,
                   java.lang.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:
java.lang.RuntimeException - if the b argument is false.

error

public void error(XPathContext xctxt,
                  Node sourceNode,
                  int msg,
                  java.lang.Object[] args)
           throws TransformerException
Tell the user of an error, and probably throw an exception.
Parameters:
xctxt - The XPath runtime context.
sourceNode - Not used.
msg - An error number that corresponds to one of the numbers 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:
TransformerException - if the current ErrorListoner determines to throw an exception.


Copyright � 2000 Apache XML Project. All Rights Reserved.