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 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.

Author:

Michael H. Kay

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	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 Type	Method and Description
XPathDynamicContext	createDynamicContext() Create a dynamic context suitable for evaluating this expression, without supplying a context item
XPathDynamicContext	createDynamicContext(Controller controller, Item contextItem) Create a dynamic context suitable for evaluating this expression within an environment represented by an existing controller.
XPathDynamicContext	createDynamicContext(Item contextItem) Create a dynamic context suitable for evaluating this expression
boolean	effectiveBooleanValue(XPathDynamicContext context) Evaluate the expression, returning its effective boolean value
java.util.List<Item>	evaluate(XPathDynamicContext context) Execute the expression, returning the result as a List, whose members will be instances of the class Item
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.
Executable	getExecutable() Get the Executable associated with this expression
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
protected void	setStackFrameMap(SlotManager map, int numberOfExternalVariables) Define the number of slots needed for local variables within 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(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

Parameters:

env - the static context of the expression

exp - the internal representation of the compiled expression

exec - the Executable associated with this expression

Method Detail

getExecutable

public Executable getExecutable()

Get the Executable associated with this expression

Returns:

the associated Executable

setStackFrameMap

protected void setStackFrameMap(SlotManager map,
                                int numberOfExternalVariables)

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 externally

numberOfExternalVariables - the number of slots in the stack frame allocated to externally-declared variables. These must be assigned a value before execution starts

createDynamicContext

public XPathDynamicContext 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

public XPathDynamicContext createDynamicContext(Item contextItem)
                                         throws XPathException

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 calling createDynamicContext(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

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

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

public java.util.List<Item> evaluate(XPathDynamicContext context)
                              throws XPathException

Execute the expression, returning the result as a List, whose members will be instances of the class Item

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

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.

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

public boolean effectiveBooleanValue(XPathDynamicContext context)
                              throws XPathException

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

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.

Returns:

the underlying Saxon expression object.