net.sf.saxon.xpath
Class XPathExpression

java.lang.Object
  extended bynet.sf.saxon.xpath.XPathExpression

public final class XPathExpression
extends java.lang.Object

XPathExpression represents a compiled XPath expression that can be repeatedly evaluated.

Note that the object contains the context node, so it is not thread-safe.

Author:
Michael H. Kay (michael.h.kay@ntlworld.com)

Constructor Summary
protected XPathExpression(Expression exp, DocumentInfo doc)
          The constructor is protected, to ensure that instances can only be created using the createExpression() method of XPathEvaluator
 
Method Summary
 java.util.List evaluate()
          Execute a prepared XPath expression, returning the results as a List.
 java.lang.Object evaluateSingle()
          Execute a prepared XPath expression, returning the first item in the result.
 SequenceIterator rawIterator()
          Get a raw iterator over the results of the expression.
 void setContextNode(NodeInfo node)
          Set the context node for evaluating the expression.
 void setSortKey(XPathExpression sortKey)
          Define the sort order for the results of the expression.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

XPathExpression

protected XPathExpression(Expression exp,
                          DocumentInfo doc)
The constructor is protected, to ensure that instances can only be created using the createExpression() method of XPathEvaluator

Method Detail

setSortKey

public void setSortKey(XPathExpression sortKey)
Define the sort order for the results of the expression. If this method is called, then the list returned by a subsequent call on the evaluate() method will first be sorted.

Parameters:
sortKey - an XPathExpression, which will be applied to each item in the sequence; the result of this expression determines the ordering of the list returned by the evaluate() method. The sortKey can be null, to clear a previous sort key.

setContextNode

public void setContextNode(NodeInfo node)
Set the context node for evaluating the expression. If this method is not called, the context node will be the root of the document to which the prepared expression is bound.


evaluate

public java.util.List evaluate()
                        throws XPathException
Execute a prepared XPath expression, returning the results as a List.

Returns:
The results of the expression, as a List. The List represents the sequence of items returned by the expression. Each item in the list will either be an instance of net.sf.saxon.om.NodeInfo, representing a node, or a Java object representing an atomic value. For the types of Java object that may be returned, see the description of the evaluate method of class XPathProcessor
Throws:
XPathException

evaluateSingle

public java.lang.Object evaluateSingle()
                                throws XPathException
Execute a prepared XPath expression, returning the first item in the result. This is useful where it is known that the expression will only return a singleton value (for example, a single node, or a boolean).

Returns:
The first item in the sequence returned by the expression. If the expression returns an empty sequence, this method returns null. Otherwise, it returns the first item in the result sequence, represented as a Java object using the same mapping as for the evaluate() method
Throws:
XPathException

rawIterator

public SequenceIterator rawIterator()
                             throws XPathException
Get a raw iterator over the results of the expression. This returns results without any conversion of the returned items to "native" Java classes. This method is intended for use by applications that need to process the results of the expression using internal Saxon interfaces.

Throws:
XPathException