Interface supported by an XPath expression. This includes both compile-time
and run-time methods.
addToPathMap
public PathMap.PathMapNodeSet addToPathMap(PathMap pathMap,
PathMap.PathMapNodeSet pathMapNodeSet)
Add a representation of this expression to a PathMap. The PathMap captures a map of the nodes visited
by an expression in a source tree.
The default implementation of this method assumes that an expression does no navigation other than
the navigation done by evaluating its subexpressions, and that the subexpressions are evaluated in the
same context as the containing expression. The method must be overridden for any expression
where these assumptions do not hold. For example, implementations exist for AxisExpression, ParentExpression,
and RootExpression (because they perform navigation), and for the doc(), document(), and collection()
functions because they create a new navigation root. Implementations also exist for PathExpression and
FilterExpression because they have subexpressions that are evaluated in a different context from the
calling expression.
pathMap
- the PathMap to which the expression should be addedpathMapNodeSet
- the PathMapNodeSet to which the paths embodied in this expression should be added
- the pathMapNodeSet representing the points in the source document that are both reachable by this
expression, and that represent possible results of this expression. For an expression that does
navigation, it represents the end of the arc in the path map that describes the navigation route. For other
expressions, it is the same as the input pathMapNode.
adoptChildExpression
public void adoptChildExpression(Expression child)
Set up a parent-child relationship between this expression and a given child expression.
Note: many calls on this method are now redundant, but are kept in place for "belt-and-braces"
reasons. The rule is that an implementation of simplify(), typeCheck(), or optimize() that returns
a value other than "this" is required to set the location information and parent pointer in the new
child expression. However, in the past this was often left to the caller, which did it by calling
this method, either unconditionally on return from one of these methods, or after testing that the
returned object was not the same as the original.
child
- the child expression
checkPermittedContents
public void checkPermittedContents(SchemaType parentType,
StaticContext env,
boolean whole)
throws XPathException
Check that any elements and attributes constructed or returned by this expression are acceptable
in the content model of a given complex type. It's always OK to say yes, since the check will be
repeated at run-time. The process of checking element and attribute constructors against the content
model of a complex type also registers the type of content expected of those constructors, so the
static validation can continue recursively.
parentType
- the "given complex type": the method is checking that the nodes returned by this
expression are acceptable members of the content model of this typeenv
- the static contextwhole
- if true, we want to check that the value of this expression satisfies the content model
as a whole; if false we want to check that the value of the expression is acceptable as one part
of the content
XPathException
- if the value delivered by this expression cannot be part of the content model
of the given type
computeCardinality
protected abstract int computeCardinality()
Compute the static cardinality of this expression
computeDependencies
public int computeDependencies()
Compute the dependencies of an expression, as the union of the
dependencies of its subexpressions. (This is overridden for path expressions
and filter expressions, where the dependencies of a subexpression are not all
propogated). This method should be called only once, to compute the dependencies;
after that, getDependencies should be used.
- the depencies, as a bit-mask
computeSpecialProperties
protected int computeSpecialProperties()
Compute the special properties of this expression. These properties are denoted by a bit-significant
integer, possible values are in class
StaticProperty
. The "special" properties are properties
other than cardinality and dependencies, and most of them relate to properties of node sequences, for
example whether the nodes are in document order.
- the special properties, as a bit-significant integer
computeStaticProperties
public final void computeStaticProperties()
Compute the static properties. This should only be done once for each
expression.
copy
public abstract Expression copy()
Copy an expression. This makes a deep copy.
- the copy of the original expression
display
public void display(int level,
PrintStream out,
Configuration config)
since 9.0 - use the explain method
Diagnostic print of expression structure. The abstract expression tree
is written to the supplied output destination.
level
- this argument is ignoredout
- the expression presenter used to display the structureconfig
- the Saxon configuration
doPromotion
public final Expression doPromotion(Expression subexpression,
PromotionOffer offer)
throws XPathException
Promote a subexpression if possible, and if the expression was changed, carry out housekeeping
to reset the static properties and correct the parent pointers in the tree
subexpression
- the subexpression that is a candidate for promotionoffer
- details of the promotion being considered
- the result of the promotion. This will be the current expression if no promotion
actions have taken place
dynamicError
protected void dynamicError(String message,
String code,
XPathContext context)
throws XPathException
Method used in subclasses to signal a dynamic error
message
- the error messagecode
- the error codecontext
- the XPath dynamic context
effectiveBooleanValue
public boolean effectiveBooleanValue(XPathContext context)
throws XPathException
Get the effective boolean value of the expression. This returns false if the value
is the empty sequence, a zero-length string, a number equal to zero, or the boolean
false. Otherwise it returns true.
context
- The context in which the expression is to be evaluated
- the effective boolean value
XPathException
- if any dynamic error occurs evaluating the
expression
evaluateAsString
public CharSequence evaluateAsString(XPathContext context)
throws XPathException
Evaluate an expression as a String. This function must only be called in contexts
where it is known that the expression will return a single string (or where an empty sequence
is to be treated as a zero-length string). Implementations should not attempt to convert
the result to a string, other than converting () to "". This method is used mainly to
evaluate expressions produced by compiling an attribute value template.
context
- The context in which the expression is to be evaluated
- the value of the expression, evaluated in the current context.
The expression must return a string or (); if the value of the
expression is (), this method returns "".
XPathException
- if any dynamic error occurs evaluating the
expression
evaluateItem
public Item evaluateItem(XPathContext context)
throws XPathException
Evaluate an expression as a single item. This always returns either a single Item or
null (denoting the empty sequence). No conversion is done. This method should not be
used unless the static type of the expression is a subtype of "item" or "item?": that is,
it should not be called if the expression may return a sequence. There is no guarantee that
this condition will be detected.
- evaluateItem in interface EvaluableItem
context
- The context in which the expression is to be evaluated
- the node or atomic value that results from evaluating the
expression; or null to indicate that the result is an empty
sequence
XPathException
- if any dynamic error occurs evaluating the
expression
explain
public final void explain(OutputStream out)
Diagnostic print of expression structure. The abstract expression tree
is written to the supplied outputstream.
out
- the expression presenter used to display the structure
explain
public abstract void explain(ExpressionPresenter out)
Diagnostic print of expression structure. The abstract expression tree
is written to the supplied output destination.
out
- the expression presenter used to display the structure
findParentOf
public Expression findParentOf(Expression leaf)
Within the subtree rooted at this node, find the expression that is the parent of a given leaf node.
leaf
- the expression whose parent is required
- the parent of the expression. If leaf is not found in the tree, return null
getCardinality
public int getCardinality()
Determine the static cardinality of the expression. This establishes how many items
there will be in the result of the expression, at compile time (i.e., without
actually evaluating the result.
- one of the values Cardinality.ONE_OR_MORE,
Cardinality.ZERO_OR_MORE, Cardinality.EXACTLY_ONE,
Cardinality.ZERO_OR_ONE, Cardinality.EMPTY. This default
implementation returns ZERO_OR_MORE (which effectively gives no
information).
getColumnNumber
public int getColumnNumber()
Get the column number of the expression
getConstructType
protected int getConstructType()
Get the type of this expression for use in tracing and diagnostics
- the type of expression, as enumerated in class
Location
getContainer
public Container getContainer()
Get the container in which this expression is located. This will usually be a top-level construct
such as a function or global variable, and XSLT template, or an XQueryExpression. In the case of
free-standing XPath expressions it will be the StaticContext object
- the expression's container
getDependencies
public int getDependencies()
Determine which aspects of the context the expression depends on. The result is
a bitwise-or'ed value composed from constants such as XPathContext.VARIABLES and
XPathContext.CURRENT_NODE. The default implementation combines the intrinsic
dependencies of this expression with the dependencies of the subexpressions,
computed recursively. This is overridden for expressions such as FilterExpression
where a subexpression's dependencies are not necessarily inherited by the parent
expression.
- a set of bit-significant flags identifying the dependencies of
the expression
getExecutable
public Executable getExecutable()
Get the executable containing this expression
- the containing Executable
getHostLanguage
public int getHostLanguage()
Get the host language (XSLT, XQuery, XPath) used to implement the code in this container
getImplementationMethod
public int getImplementationMethod()
An implementation of Expression must provide at least one of the methods evaluateItem(), iterate(), or process().
This method indicates which of these methods is provided directly. The other methods will always be available
indirectly, using an implementation that relies on one of the other methods.
getIntrinsicDependencies
public int getIntrinsicDependencies()
Determine the intrinsic dependencies of an expression, that is, those which are not derived
from the dependencies of its subexpressions. For example, position() has an intrinsic dependency
on the context position, while (position()+1) does not. The default implementation
of the method returns 0, indicating "no dependencies".
- a set of bit-significant flags identifying the "intrinsic"
dependencies. The flags are documented in class net.sf.saxon.value.StaticProperty
getItemType
public abstract ItemType getItemType(TypeHierarchy th)
Determine the data type of the expression, if possible. All expression return
sequences, in general; this method determines the type of the items within the
sequence, assuming that (a) this is known in advance, and (b) it is the same for
all items in the sequence.
This method should always return a result, though it may be the best approximation
that is available at the time.
th
- the type hierarchy cache
- a value such as Type.STRING, Type.BOOLEAN, Type.NUMBER,
Type.NODE, or Type.ITEM (meaning not known at compile time)
getLineNumber
public int getLineNumber()
Get the line number of the expression
getLocationId
public final int getLocationId()
Get the location ID of the expression
- a location identifier, which can be turned into real
location information by reference to a location provider
getLocationProvider
public LocationProvider getLocationProvider()
Get the LocationProvider allowing location identifiers to be resolved.
- the LocationProvider used to turn the location id into real location information
getPublicId
public final String getPublicId()
Get the publicId of the module containing the expression (to satisfy the SourceLocator interface)
getSlotsUsed
public int[] getSlotsUsed()
Get the local variables (identified by their slot numbers) on which this expression depends.
Should only be called if the caller has established that there is a dependency on local variables.
- an array of integers giving the slot numbers of the local variables referenced in this
expression.
getSpecialProperties
public final int getSpecialProperties()
Get the static properties of this expression (other than its type). The result is
bit-signficant. These properties are used for optimizations. In general, if
property bit is set, it is true, but if it is unset, the value is unknown.
- a set of flags indicating static properties of this expression
getSystemId
public String getSystemId()
Get the systemId of the module containing the expression
hasLoopingSubexpression
public boolean hasLoopingSubexpression(Expression child)
Given an expression that is an immediate child of this expression, test whether
the evaluation of the parent expression causes the child expression to be
evaluated repeatedly
child
- the immediate subexpression
- true if the child expression is evaluated repeatedly
implementsStaticTypeCheck
public boolean implementsStaticTypeCheck()
Determine whether this expression implements its own method for static type checking
- true if this expression has a non-trivial implementation of the staticTypeCheck()
method
iterate
public SequenceIterator iterate(XPathContext context)
throws XPathException
Return an Iterator to iterate over the values of a sequence. The value of every
expression can be regarded as a sequence, so this method is supported for all
expressions. This default implementation handles iteration for expressions that
return singleton values: for non-singleton expressions, the subclass must
provide its own implementation.
- iterate in interface SequenceIterable
context
- supplies the context for evaluation
- a SequenceIterator that can be used to iterate over the result
of the expression
XPathException
- if any dynamic error occurs evaluating the
expression
iterateEvents
public EventIterator iterateEvents(XPathContext context)
throws XPathException
Deliver the result of the expression as a sequence of events.
The events (of class
PullEvent
) are either complete
items, or one of startElement, endElement, startDocument, or endDocument, known
as semi-nodes. The stream of events may also include a nested EventIterator.
If a start-end pair exists in the sequence, then the events between
this pair represent the content of the document or element. The content sequence will
have been processed to the extent that any attribute and namespace nodes in the
content sequence will have been merged into the startElement event. Namespace fixup
will have been performed: that is, unique prefixes will have been allocated to element
and attribute nodes, and all namespaces will be declared by means of a namespace node
in the startElement event or in an outer startElement forming part of the sequence.
However, duplicate namespaces may appear in the sequence.
The content of an element or document may include adjacent or zero-length text nodes,
atomic values, and nodes represented as nodes rather than broken down into events.
context
- The dynamic evaluation context
- the result of the expression as an iterator over a sequence of PullEvent objects
XPathException
- if a dynamic error occurs during expression evaluation
iterateSubExpressions
public Iterator iterateSubExpressions()
Get the immediate sub-expressions of this expression. Default implementation
returns a zero-length array, appropriate for an expression that has no
sub-expressions.
- an iterator containing the sub-expressions of this expression
markTailFunctionCalls
public int markTailFunctionCalls(StructuredQName qName,
int arity)
Mark tail-recursive calls on stylesheet functions. For most expressions, this does nothing.
qName
- the name of the functionarity
- the arity (number of parameters) of the function
- 0 if no tail call was found; 1 if a tail call on a different function was found;
2 if a tail recursive call was found and if this call accounts for the whole of the value.
optimize
public Expression optimize(ExpressionVisitor visitor,
ItemType contextItemType)
throws XPathException
Perform optimisation of an expression and its subexpressions. This is the third and final
phase of static optimization.
This method is called after all references to functions and variables have been resolved
to the declaration of the function or variable, and after all type checking has been done.
visitor
- an expression visitorcontextItemType
- the static type of "." at the point where this expression is invoked.
The parameter is set to null if it is known statically that the context item will be undefined.
If the type of the context item is not known statically, the argument is set to
Type.ITEM_TYPE
- the original expression, rewritten if appropriate to optimize execution
XPathException
- if an error is discovered during this phase
(typically a type error)
process
public void process(XPathContext context)
throws XPathException
Process the instruction, without returning any tail calls
context
- The dynamic context, giving access to the current node,
the current variables, etc.
promote
public Expression promote(PromotionOffer offer)
throws XPathException
Offer promotion for this subexpression. The offer will be accepted if the subexpression
is not dependent on the factors (e.g. the context item) identified in the PromotionOffer.
By default the offer is not accepted - this is appropriate in the case of simple expressions
such as constant values and variable references where promotion would give no performance
advantage. This method is always called at compile time.
offer
- details of the offer, for example the offer to move
expressions that don't depend on the context to an outer level in
the containing expression
- if the offer is not accepted, return this expression unchanged.
Otherwise return the result of rewriting the expression to promote
this subexpression
replaceSubExpression
public boolean replaceSubExpression(Expression original,
Expression replacement)
Replace one subexpression by a replacement subexpression
original
- the original subexpressionreplacement
- the replacement subexpression
- true if the original subexpression is found
resetLocalStaticProperties
protected final void resetLocalStaticProperties()
Reset the static properties of the expression to -1, so that they have to be recomputed
next time they are used.
setContainer
public void setContainer(Container container)
Mark an expression as being in a given Container. This link is used primarily for diagnostics:
the container links to the location map held in the executable.
This affects the expression and all its subexpressions. Any subexpressions that are not in the
same container are marked with the new container, and this proceeds recursively. However, any
subexpression that is already in the correct container is not modified.
container
- The container of this expression.
setFiltered
public void setFiltered(boolean filtered)
Mark an expression as filtered: that is, it appears as the base expression in a filter expression.
This notification currently has no effect except when the expression is a variable reference.
filtered
- if true, marks this expression as the base of a filter expression
setFlattened
public void setFlattened(boolean flattened)
Mark an expression as being "flattened". This is a collective term that includes extracting the
string value or typed value, or operations such as simple value construction that concatenate text
nodes before atomizing. The implication of all of these is that although the expression might
return nodes, the identity of the nodes has no significance. This is called during type checking
of the parent expression.
flattened
- set to true if the result of the expression is atomized or otherwise turned into
an atomic value
setLocationId
public void setLocationId(int id)
Set the location ID on an expression.
simplify
public Expression simplify(ExpressionVisitor visitor)
throws XPathException
Simplify an expression. This performs any static optimization (by rewriting the expression
as a different expression). The default implementation does nothing.
visitor
- an expression visitor
- the simplified expression
XPathException
- if an error is discovered during expression
rewriting
staticTypeCheck
public Expression staticTypeCheck(SequenceType req,
boolean backwardsCompatible,
RoleLocator role,
ExpressionVisitor visitor)
throws XPathException
Static type checking of some expressions is delegated to the expression itself, by calling
this method. The default implementation of the method throws UnsupportedOperationException.
If there is a non-default implementation, then implementsStaticTypeCheck() will return true
req
- the required typebackwardsCompatible
- true if backwards compatibility mode appliesrole
- the role of the expression in relation to the required typevisitor
- an expression visitor
- the expression after type checking (perhaps augmented with dynamic type checking code)
XPathException
- if failures occur, for example if the static type of one branch of the conditional
is incompatible with the required type
suppressValidation
public void suppressValidation(int validationMode)
Suppress validation on contained element constructors, on the grounds that the parent element
is already performing validation. The default implementation does nothing.
validationMode
- the kind of validation being performed on the parent expression
toString
public String toString()
The toString() method for an expression attempts to give a representation of the expression
in an XPath-like form, but there is no guarantee that the syntax will actually be true XPath.
In the case of XSLT instructions, the toString() method gives an abstracted view of the syntax
typeCheck
public Expression typeCheck(ExpressionVisitor visitor,
ItemType contextItemType)
throws XPathException
Perform type checking of an expression and its subexpressions. This is the second phase of
static optimization.
This checks statically that the operands of the expression have
the correct type; if necessary it generates code to do run-time type checking or type
conversion. A static type error is reported only if execution cannot possibly succeed, that
is, if a run-time type error is inevitable. The call may return a modified form of the expression.
This method is called after all references to functions and variables have been resolved
to the declaration of the function or variable. However, the types of such functions and
variables may not be accurately known if they have not been explicitly declared.
If the implementation returns a value other than "this", then it is required to ensure that
the parent pointer and location information in the returned expression have been set up correctly.
It should not rely on the caller to do this, although for historical reasons many callers do so.
visitor
- an expression visitorcontextItemType
- the static type of "." at the point where this expression is invoked.
The parameter is set to null if it is known statically that the context item will be undefined.
If the type of the context item is not known statically, the argument is set to
Type.ITEM_TYPE
- the original expression, rewritten to perform necessary run-time type checks,
and to perform other type-related optimizations
XPathException
- if an error is discovered during this phase
(typically a type error)
typeError
protected void typeError(String message,
String errorCode,
XPathContext context)
throws XPathException
Method used in subclasses to signal a runtime type error
message
- the error messageerrorCode
- the error codecontext
- the XPath dynamic context