Package net.sf.saxon.sxpath
Class XPathExpression
java.lang.Object
net.sf.saxon.sxpath.XPathExpression
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 free-standing, and is more strongly typed.
In Saxon 9.6, the methods that returned Object and did implicit conversion to a native Java object have been removed; all conversions must now be done explicitly.
-
Constructor Summary
ConstructorsModifierConstructorDescriptionprotected
XPathExpression
(StaticContext env, Expression exp, Executable exec) The constructor is protected, to ensure that instances can only be created using the createExpression() or createPattern() method of XPathEvaluator -
Method Summary
Modifier and TypeMethodDescriptionCreate a dynamic context suitable for evaluating this expression, without supplying a context itemcreateDynamicContext
(Controller controller, Item contextItem) Create a dynamic context suitable for evaluating this expression within an environment represented by an existing controller.createDynamicContext
(Item contextItem) Create a dynamic context suitable for evaluating this expressionboolean
effectiveBooleanValue
(XPathDynamicContext context) Evaluate the expression, returning its effective boolean valueevaluate
(XPathDynamicContext context) Execute the expression, returning the result as a List, whose members will be instances of the classItem
evaluateSingle
(XPathDynamicContext context) Execute the expression, returning the result as a singleItem
If the result of the expression is a sequence containing more than one item, items after the first are discarded.Get the Executable associated with this expressionLow-level method to get the internal Saxon expression object.iterate
(XPathDynamicContext context) Execute the expression, returning the result as aSequenceIterator
, whose members will be instances of the classItem
protected void
setStackFrameMap
(SlotManager map, int numberOfExternalVariables) Define the number of slots needed for local variables within the expression
-
Constructor Details
-
XPathExpression
The constructor is protected, to ensure that instances can only be created using the createExpression() or createPattern() method of XPathEvaluator- Parameters:
env
- the static context of the expressionexp
- the internal representation of the compiled expressionexec
- the Executable associated with this expression
-
-
Method Details
-
getExecutable
Get the Executable associated with this expression- Returns:
- the associated Executable
-
setStackFrameMap
Define the number of slots needed for local variables within the expression- Parameters:
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
-
createDynamicContext
Create a dynamic context suitable for evaluating this expression, without supplying a context item- Returns:
- 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.
-
createDynamicContext
Create a dynamic context suitable for evaluating this expression- Parameters:
contextItem
- the initial context item, which may be null if no context item is required, or if it is to be supplied later- Returns:
- 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.
- Throws:
XPathException
- if the context item does not match the required context item type set up in the static context
-
createDynamicContext
public XPathDynamicContext createDynamicContext(Controller controller, Item contextItem) throws XPathException Create a dynamic context suitable for evaluating this expression within an environment represented by an existing controller. The dynamic context will inherit properties of the Controller such as the current error listener, URI resolver, document pool, and implicit timezone.- Parameters:
controller
- an existing controller. May be null, in which case the method is equivalent to callingcreateDynamicContext(net.sf.saxon.om.Item)
contextItem
- the initial context item, which may be null if no context item is required, or if it is to be supplied later- Returns:
- 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.
- Throws:
XPathException
- if the context item does not match the required context item type set up in the static context- Since:
- 9.2
-
iterate
Execute the expression, returning the result as aSequenceIterator
, whose members will be instances of the classItem
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
- Parameters:
context
- the XPath dynamic context- Returns:
- an iterator over the result of the expression
- Throws:
XPathException
- if a dynamic error occurs during the expression evaluation (though in many cases, the error will only be detected when the iterator is actually used).
-
evaluate
Execute the expression, returning the result as a List, whose members will be instances of the classItem
- Parameters:
context
- the XPath dynamic context- Returns:
- a list of items representing the result of the expression
- Throws:
XPathException
- if a dynamic error occurs while evaluation the expression
-
evaluateSingle
Execute the expression, returning the result as a singleItem
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.- Parameters:
context
- the XPath dynamic context- Returns:
- the first item in the result of the expression, or null to indicate that the result is an empty sequence
- Throws:
XPathException
- if a dynamic error occurs during the expression evaluation
-
effectiveBooleanValue
Evaluate the expression, returning its effective boolean value- Parameters:
context
- the XPath dynamic context- Returns:
- the effective boolean value of the result, as defined by the fn:boolean() function
- Throws:
XPathException
- if a dynamic error occurs, or if the result is a value for which no effective boolean value is defined
-
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.- Returns:
- the underlying Saxon expression object.
-