net.sf.saxon.sxpath
Class XPathExpression
java.lang.Object
net.sf.saxon.sxpath.XPathExpression
public class XPathExpression
extends java.lang.Object
This class is a representation of an XPath Expression for use with the
XPathEvaluator
class.
It is modelled on the XPath API defined in JAXP 1.3, but is cut down to remove any dependencies on JAXP 1.3,
making it suitable for use on vanilla JDK 1.4 installations.
XPathDynamicContext | createDynamicContext(Item contextItem) - Create a dynamic context suitable for evaluating this expression
|
List | evaluate(Source source) - Execute a prepared XPath expression, returning the results as a List in which items have been converted
to the appropriate Java object.
|
List | evaluate(XPathDynamicContext context) - Execute the expression, returning the result as a List, whose members will be instances
of the class
Item
|
Object | evaluateSingle(Source source) - Execute a prepared XPath expression, returning the first item in the result.
|
Item | evaluateSingle(XPathDynamicContext context) - Execute the expression, returning the result as a single
Item
If the result of the expression is a sequence containing more than one item, items after
the first are discarded.
|
Expression | getInternalExpression() - Low-level method to get the internal Saxon expression object.
|
SequenceIterator | iterate(XPathDynamicContext context) - Execute the expression, returning the result as a
SequenceIterator , whose members will be instances
of the class Item
Note that if evaluation of the expression fails with a dynamic error, this will generally
be reported in the form of an exception thrown by the next() method of the SequenceIterator
|
SequenceIterator | rawIterator(Source source) - since 8.9 - use
iterate(XPathDynamicContext)
|
protected void | setStackFrameMap(SlotManager map, int numberOfExternalVariables) - Define the number of slots needed for local variables within the expression
|
XPathExpression
protected XPathExpression(XPathEvaluator evaluator,
Expression exp)
The constructor is protected, to ensure that instances can only be
created using the createExpression() method of XPathEvaluator
evaluator
- the creating XPathEvaluatorexp
- the internal representation of the compiled expression
createDynamicContext
public XPathDynamicContext createDynamicContext(Item contextItem)
Create a dynamic context suitable for evaluating this expression
contextItem
- the initial context item, which may be null if no
context item is required, or if it is to be supplied later
- an XPathDynamicContext object representing a suitable dynamic context. This will
be initialized with a stack frame suitable for holding the variables used by the
expression.
evaluate
public List evaluate(Source source)
throws XPathException
Execute a prepared XPath expression, returning the results as a List in which items have been converted
to the appropriate Java object.
source
- the document or other node against which the XPath expression
will be evaluated. This may be a Saxon NodeInfo object, representing a node in an
existing tree, or it may be any kind of JAXP Source object such as a StreamSource
SAXSource or DOMSource. For the way in which the source document is built, see
Configuration.buildDocument(Source)
- 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.
evaluate
public List evaluate(XPathDynamicContext context)
throws XPathException
Execute the expression, returning the result as a List, whose members will be instances
of the class
Item
context
- the XPath dynamic context
- a list of items representing the result of the expression
evaluateSingle
public Object evaluateSingle(Source source)
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).
source
- the document or other node against which the XPath expression
will be evaluated. This may be a Saxon NodeInfo object, representing a node in an
existing tree, or it may be any kind of JAXP Source object such as a StreamSource
SAXSource or DOMSource. For the way in which the source document is built, see
Configuration.buildDocument(Source)
- 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
evaluateSingle
public Item evaluateSingle(XPathDynamicContext context)
throws XPathException
Execute the expression, returning the result as a single
Item
If the result of the expression is a sequence containing more than one item, items after
the first are discarded. If the result is an empty sequence, the method returns null.
context
- the XPath dynamic context
- the first item in the result of the expression, or null
getInternalExpression
public Expression getInternalExpression()
Low-level method to get the internal Saxon expression object. This exposes a wide range of
internal methods that may be needed by specialized applications, and allows greater control
over the dynamic context for evaluating the expression.
- the underlying Saxon expression object.
iterate
public SequenceIterator iterate(XPathDynamicContext context)
throws XPathException
Execute the expression, returning the result as a
SequenceIterator
, whose members will be instances
of the class
Item
Note that if evaluation of the expression fails with a dynamic error, this will generally
be reported in the form of an exception thrown by the next() method of the
SequenceIterator
context
- the XPath dynamic context
- an iterator over the result of the expression
rawIterator
public SequenceIterator rawIterator(Source source)
throws XPathException
since 8.9 - use iterate(XPathDynamicContext)
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.
source
- the document or other node against which the XPath expression
will be evaluated. This may be a Saxon NodeInfo object, representing a node in an
existing tree, or it may be any kind of JAXP Source object such as a StreamSource
SAXSource or DOMSource. For the way in which the source document is built, see
Configuration.buildDocument(Source)
- an iterator over the results of the expression
setStackFrameMap
protected void setStackFrameMap(SlotManager map,
int numberOfExternalVariables)
Define the number of slots needed for local variables within the expression
map
- the stack frame map identifying all the variables used by the expression, both
those declared internally, and references to variables declared externallynumberOfExternalVariables
- the number of slots in the stack frame allocated to
externally-declared variables. These must be assigned a value before execution starts