net.sf.saxon.expr

Class SystemFunctionCall

java.lang.Object

net.sf.saxon.expr.Expression

net.sf.saxon.expr.FunctionCall

net.sf.saxon.expr.StaticFunctionCall

net.sf.saxon.expr.SystemFunctionCall

All Implemented Interfaces:

Callable, ExportAgent, Locatable, Negatable, IdentityComparable

Direct Known Subclasses:

SystemFunctionCall.Optimized

public class SystemFunctionCall
extends StaticFunctionCall
implements Negatable

A call to a system-defined function (specifically, a function implemented as an instance of SystemFunction)

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	SystemFunctionCall.Optimized Subclass representing a system function call that has been optimized; this overrides the optimize() method to do nothing, thus ensuring that optimization converges.

Field Summary

Fields

Modifier and Type	Field and Description
Evaluator[]	argumentEvaluators

Fields inherited from class net.sf.saxon.expr.Expression

EFFECTIVE_BOOLEAN_VALUE, EVALUATE_METHOD, ITEM_FEED_METHOD, ITERATE_METHOD, MAX_COST, MAX_SEQUENCE_LENGTH, MAX_STRING_LENGTH, PROCESS_METHOD, staticProperties, UNBOUNDED_LOWER, UNBOUNDED_UPPER, UPDATE_METHOD, WATCH_METHOD

Constructor Summary

Constructors

Constructor and Description
SystemFunctionCall(SystemFunction target, Expression[] arguments)

Method Summary

Modifier and Type	Method and Description
PathMap.PathMapNodeSet	addToPathMap(PathMap pathMap, PathMap.PathMapNodeSet pathMapNodeSet) Add a representation of this expression to a PathMap.
protected int	computeCardinality() Compute the static cardinality of this expression
protected int	computeSpecialProperties() Compute the special properties of this expression.
Expression	copy(RebindingMap rebindings) Copy an expression.
Sequence[]	evaluateArguments(XPathContext context)
void	export(ExpressionPresenter out) Diagnostic print of expression structure.
java.lang.String	getExpressionName() Get a name identifying the kind of expression, in terms meaningful to a user.
IntegerValue[]	getIntegerBounds() For an expression that returns an integer or a sequence of integers, get a lower and upper bound on the values of the integers that may be returned, from static analysis.
int	getIntrinsicDependencies() Compute the dependencies of an expression, as the union of the dependencies of its subexpressions.
ItemType	getItemType() Determine the data type of the expression, if possible.
int	getNetCost() Return the estimated cost of evaluating an expression.
Expression	getScopingExpression() Get the innermost scoping expression of this expression, for expressions that directly depend on something in the dynamic context.
SystemFunction	getTargetFunction() Get the target function to be called
boolean	isLiftable(boolean forStreaming) Ask whether the expression can be lifted out of a loop, assuming it has no dependencies on the controlling variable/focus of the loop
boolean	isNegatable(TypeHierarchy th) Check whether this specific instance of the expression is negatable
boolean	isVacuousExpression() Determine whether this is a vacuous expression as defined in the XQuery update specification
Expression	negate() Create an expression that returns the negation of this expression
Expression	optimize(ExpressionVisitor visitor, ContextItemStaticInfo contextInfo) Perform optimisation of an expression and its subexpressions.
Expression	preEvaluate(ExpressionVisitor visitor) Pre-evaluate a function at compile time.
void	resetLocalStaticProperties() Reset the static properties of the expression to -1, so that they have to be recomputed next time they are used.
void	setRetainedStaticContext(RetainedStaticContext rsc) Set the retained static context
Pattern	toPattern(Configuration config) Convert this expression to an equivalent XSLT pattern
Expression	typeCheck(ExpressionVisitor visitor, ContextItemStaticInfo contextInfo) Type-check the expression.
Expression	unordered(boolean retainAllNodes, boolean forStreaming) Replace this expression by a simpler expression that delivers the results without regard to order.

Methods inherited from class net.sf.saxon.expr.StaticFunctionCall

call, getFunctionName, getStaticUType, getTargetFunction, isCallOn

Methods inherited from class net.sf.saxon.expr.FunctionCall

addExternalFunctionCallToPathMap, adjustRequiredType, checkArgumentCount, checkArguments, checkFunctionCall, computeHashCode, equals, getArg, getArguments, getArity, getDisplayName, getImplementationMethod, getOperanda, iterate, operands, pluralArguments, preEvaluateIfConstant, setArg, setArguments, setOperanda, setOperanda, simplifyArguments, toShortString, toString

Methods inherited from class net.sf.saxon.expr.Expression

adoptChildExpression, allowExtractingCommonSubexpressions, checkedOperands, checkForUpdatingSubexpressions, checkPermittedContents, computeDependencies, computeStaticProperties, dynamicError, effectiveBooleanValue, evaluateAsString, evaluateItem, evaluatePendingUpdates, explain, getCardinality, getConfiguration, getConstructType, getCost, getDependencies, getEvaluationMethod, getExtraProperty, getInterpretedExpression, getLocalRetainedStaticContext, getLocation, getObjectName, getPackageData, getParentExpression, getProperties, getProperty, getRetainedStaticContext, getSlotsUsed, getSpecialProperties, getStaticBaseURI, getStaticBaseURIString, getStaticType, getStreamerName, hasCompatibleStaticContext, hashCode, hasSpecialProperty, hasVariableBinding, identityHashCode, implementsStaticTypeCheck, isEqual, isIdentical, isInstruction, isMultiThreaded, isStaticPropertiesKnown, isSubtreeExpression, isUpdatingExpression, markTailFunctionCalls, operandList, operandSparseList, optimizeChildren, prepareForStreaming, process, restoreParentPointers, setEvaluationMethod, setExtraProperty, setFiltered, setFlattened, setLocation, setParentExpression, setRetainedStaticContextLocally, setRetainedStaticContextThoroughly, setStaticProperty, simplify, simplifyChildren, staticTypeCheck, suppressValidation, typeCheckChildren, typeError, verifyParentPointers

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

argumentEvaluators

public Evaluator[] argumentEvaluators

Constructor Detail

SystemFunctionCall

public SystemFunctionCall(SystemFunction target,
                          Expression[] arguments)

Method Detail

setRetainedStaticContext

public void setRetainedStaticContext(RetainedStaticContext rsc)

Set the retained static context

Overrides:

setRetainedStaticContext in class Expression

Parameters:

rsc - the static context to be retained

preEvaluate

public Expression preEvaluate(ExpressionVisitor visitor)
                       throws XPathException

Pre-evaluate a function at compile time. Functions that do not allow pre-evaluation, or that need access to context information, can prevent early evaluation by setting the LATE bit in the function properties.

Overrides:

preEvaluate in class FunctionCall

Parameters:

visitor - an expression visitor

Returns:

the result of the early evaluation, or the original expression, or potentially a simplified expression

Throws:

XPathException - if evaluation fails

typeCheck

public Expression typeCheck(ExpressionVisitor visitor,
                            ContextItemStaticInfo contextInfo)
                     throws XPathException

Type-check the expression. This also calls preEvaluate() to evaluate the function if all the arguments are constant; functions that do not require this behavior can override the preEvaluate method.

Overrides:

typeCheck in class StaticFunctionCall

Parameters:

visitor - the expression visitor

contextInfo - information about the type of the context item

Returns:

the original expression, rewritten to perform necessary run-time type checks, and to perform other type-related optimizations

Throws:

XPathException - if an error is discovered during this phase (typically a type error)

getTargetFunction

public SystemFunction getTargetFunction()

Description copied from class: StaticFunctionCall

Get the target function to be called

Overrides:

getTargetFunction in class StaticFunctionCall

Returns:

the target function

getIntrinsicDependencies

public int getIntrinsicDependencies()

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.

Overrides:

getIntrinsicDependencies in class Expression

Returns:

the depencies, as a bit-mask

computeCardinality

protected int computeCardinality()

Compute the static cardinality of this expression

Overrides:

computeCardinality in class StaticFunctionCall

Returns:

the computed cardinality, as one of the values StaticProperty.ALLOWS_ZERO_OR_ONE, StaticProperty.EXACTLY_ONE, StaticProperty.ALLOWS_ONE_OR_MORE, StaticProperty.ALLOWS_ZERO_OR_MORE

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.

Overrides:

computeSpecialProperties in class Expression

Returns:

the special properties, as a bit-significant integer

getNetCost

public int getNetCost()

Return the estimated cost of evaluating an expression. This is a very crude measure based on the syntactic form of the expression (we have no knowledge of data values). We take the cost of evaluating a simple scalar comparison or arithmetic expression as 1 (one), and we assume that a sequence has length 5. The resulting estimates may be used, for example, to reorder the predicates in a filter expression so cheaper predicates are evaluated first.

Overrides:

getNetCost in class FunctionCall

Returns:

the intrinsic cost of this operation, excluding the costs of evaluating the operands

getScopingExpression

public Expression getScopingExpression()

Description copied from class: Expression

Get the innermost scoping expression of this expression, for expressions that directly depend on something in the dynamic context. For example, in the case of a local variable reference this is the expression that causes the relevant variable to be bound; for a context item expression it is the innermost focus-setting container. For expressions that have no intrinsic dependency on the dynamic context, the value returned is null; the scoping container for such an expression is the innermost scoping container of its operands.

Overrides:

getScopingExpression in class Expression

Returns:

the innermost scoping container of this expression

isLiftable

public boolean isLiftable(boolean forStreaming)

Ask whether the expression can be lifted out of a loop, assuming it has no dependencies on the controlling variable/focus of the loop

Overrides:

isLiftable in class Expression

Parameters:

forStreaming - true if we are optimizing for streamed evaluation

Returns:

true if the expression can be loop lifted

optimize

public Expression optimize(ExpressionVisitor visitor,
                           ContextItemStaticInfo contextInfo)
                    throws XPathException

Description copied from class: FunctionCall

Perform optimisation of an expression and its subexpressions.

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.

Overrides:

optimize in class FunctionCall

Parameters:

visitor - an expression visitor

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

Returns:

the original expression, rewritten if appropriate to optimize execution

Throws:

XPathException - if an error is discovered during this phase (typically a type error)

isVacuousExpression

public boolean isVacuousExpression()

Description copied from class: Expression

Determine whether this is a vacuous expression as defined in the XQuery update specification

Overrides:

isVacuousExpression in class Expression

Returns:

true if this expression is vacuous

getItemType

public ItemType getItemType()

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.

Overrides:

getItemType in class StaticFunctionCall

Returns:

a value such as Type.STRING, Type.BOOLEAN, Type.NUMBER, Type.NODE, or Type.ITEM (meaning not known at compile time)

copy

public Expression copy(RebindingMap rebindings)

Copy an expression. This makes a deep copy.

Overrides:

copy in class StaticFunctionCall

Parameters:

rebindings - variables that need to be re-bound

Returns:

the copy of the original expression

getIntegerBounds

public IntegerValue[] getIntegerBounds()

For an expression that returns an integer or a sequence of integers, get a lower and upper bound on the values of the integers that may be returned, from static analysis. The default implementation returns null, meaning "unknown" or "not applicable". Other implementations return an array of two IntegerValue objects, representing the lower and upper bounds respectively. The values UNBOUNDED_LOWER and UNBOUNDED_UPPER are used by convention to indicate that the value may be arbitrarily large. The values MAX_STRING_LENGTH and MAX_SEQUENCE_LENGTH are used to indicate values limited by the size of a string or the size of a sequence.

Overrides:

getIntegerBounds in class Expression

Returns:

the lower and upper bounds of integer values in the result, or null to indicate unknown or not applicable.

isNegatable

public boolean isNegatable(TypeHierarchy th)

Check whether this specific instance of the expression is negatable

Specified by:

isNegatable in interface Negatable

Parameters:

th - the TypeHierarchy (in case it's needed)

Returns:

true if it is

negate

public Expression negate()

Create an expression that returns the negation of this expression

Specified by:

negate in interface Negatable

Returns:

the negated expression

Throws:

java.lang.UnsupportedOperationException - if isNegatable() returns false

unordered

public Expression unordered(boolean retainAllNodes,
                            boolean forStreaming)
                     throws XPathException

Replace this expression by a simpler expression that delivers the results without regard to order.

Overrides:

unordered in class Expression

Parameters:

retainAllNodes - set to true if the result must contain exactly the same nodes as the original; set to false if the result can eliminate (or introduce) duplicates.

forStreaming - set to true if the result is to be optimized for streaming

Returns:

an expression that delivers the same nodes in a more convenient order

Throws:

XPathException - if the rewrite fails

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.

Overrides:

addToPathMap in class Expression

Parameters:

pathMap - the PathMap to which the expression should be added

pathMapNodeSet - the PathMapNodeSet to which the paths embodied in this expression should be added

Returns:

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.

toPattern

public Pattern toPattern(Configuration config)
                  throws XPathException

Convert this expression to an equivalent XSLT pattern

Overrides:

toPattern in class Expression

Parameters:

config - the Saxon configuration

Returns:

the equivalent pattern

Throws:

XPathException - if conversion is not possible

evaluateArguments

public Sequence[] evaluateArguments(XPathContext context)
                             throws XPathException

Overrides:

evaluateArguments in class FunctionCall

Throws:

XPathException

resetLocalStaticProperties

public void resetLocalStaticProperties()

Description copied from class: Expression

Reset the static properties of the expression to -1, so that they have to be recomputed next time they are used.

Overrides:

resetLocalStaticProperties in class Expression

getExpressionName

public java.lang.String getExpressionName()

Get a name identifying the kind of expression, in terms meaningful to a user.

Overrides:

getExpressionName in class StaticFunctionCall

Returns:

a name identifying the kind of expression, in terms meaningful to a user. The name will always be in the form of a lexical XML QName, and should match the name used in explain() output displaying the expression.

export

public void export(ExpressionPresenter out)
            throws XPathException

Diagnostic print of expression structure. The abstract expression tree is written to the supplied output destination.

Specified by:

export in interface ExportAgent

Overrides:

export in class StaticFunctionCall

Parameters:

out - the destination of the output

Throws:

XPathException - if the export fails, for example if an expression is found that won't work in the target environment.