Class FunctionCall
- All Implemented Interfaces:
ExportAgent
,Locatable
,IdentityComparable
,Traceable
- Direct Known Subclasses:
IntegratedFunctionCall
,JavaExtensionFunctionCall
,JavaExtensionLibrary.UnresolvedExtensionFunctionCall
,StaticFunctionCall
,UserFunctionCall
,XPathFunctionCall
-
Nested Class Summary
Nested Classes -
Field Summary
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 -
Method Summary
Modifier and TypeMethodDescriptionaddExternalFunctionCallToPathMap
(PathMap pathMap, PathMap.PathMapNodeSet pathMapNodes) Add a representation of this expression to a PathMap.boolean
adjustRequiredType
(JavaExternalObjectType requiredType) When a call to a Java extension function appears in a context where there the required type is a Java external object (typically an xsl:variable with a declared type, or as an argument to another Java extension function), notify this required type so that the process of converting the result to an XDM value can be short-circuited.protected void
checkArgumentCount
(int min, int max) Check number of arguments.protected void
checkArguments
(ExpressionVisitor visitor) Method supplied by each class of function to check arguments during parsing, when all the argument expressions have been readvoid
checkFunctionCall
(FunctionItem target, ExpressionVisitor visitor) Check the function call against the declared function signature, applying the function conversion rules to each argument as necessaryprotected int
Get hashCode in support of equals() methodboolean
Determine whether two expressions are equivalentevaluateItem
(XPathContext context) Evaluate an expression as a single item.void
Diagnostic print of expression structure.getArg
(int n) Get the expression supplied as the Nth argumentGet the expressions supplied as actual arguments to the functionfinal int
getArity()
Determine the number of actual arguments supplied in the function callfinal String
Get the name of the function for display in messagesGet a name identifying the kind of expression, in terms meaningful to a user.abstract StructuredQName
Get the qualified of the function being calledint
An implementation of Expression must provide at least one of the methods evaluateItem(), iterate(), or process().int
Return the estimated cost of evaluating an expression.Get the data structure holding the operands of this expression.abstract FunctionItem
getTargetFunction
(XPathContext context) Get the target function to be callediterate
(XPathContext context) Return an Iterator to iterate over the values of a sequence.operands()
Get the immediate sub-expressions of this expression, with information about the relationship of each expression to its parent expression.optimize
(ExpressionVisitor visitor, ContextItemStaticInfo contextItemType) Perform optimisation of an expression and its subexpressions.static String
Utility routine used in constructing error messages: get the word "argument" or "arguments"preEvaluate
(ExpressionVisitor visitor) Pre-evaluate a function at compile time.protected Expression
preEvaluateIfConstant
(ExpressionVisitor visitor) void
setArg
(int n, Expression child) Set the expression to be used as the Nth argumentvoid
setArguments
(Expression[] args) Method called by the expression parser when all arguments have been suppliedprotected void
setOperanda
(Expression[] args, OperandRole[] roles) protected void
setOperanda
(OperandArray operanda) Set the data structure for the operands of this expression.protected final Expression
Simplify the arguments of the function.Produce a short string identifying the expression for use in error messagestoString()
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.typeCheck
(ExpressionVisitor visitor, ContextItemStaticInfo contextInfo) Type-check the expression.Methods inherited from class net.sf.saxon.expr.Expression
addToPathMap, adoptChildExpression, allowExtractingCommonSubexpressions, checkedOperands, checkForUpdatingSubexpressions, checkPermittedContents, computeCardinality, computeDependencies, computeSpecialProperties, computeStaticProperties, copy, dispatchTailCall, dynamicError, effectiveBooleanValue, evaluateAsString, explain, getCardinality, getConfiguration, getCost, getDependencies, getElaborator, getEvaluationMethod, getExtraProperty, getIntegerBounds, getIntrinsicDependencies, getItemType, getLocalRetainedStaticContext, getLocation, getObjectName, getPackageData, getParentExpression, getProperties, getProperty, getRetainedStaticContext, getScopingExpression, getSlotsUsed, getSpecialProperties, getStaticBaseURI, getStaticBaseURIString, getStaticType, getStaticUType, getStreamerName, getTracingTag, hasCompatibleStaticContext, hashCode, hasSpecialProperty, hasVariableBinding, identityHashCode, implementsStaticTypeCheck, isCallOn, isEqual, isIdentical, isInstruction, isLiftable, isMultiThreaded, isStaticPropertiesKnown, isSubtreeExpression, isUpdatingExpression, isVacuousExpression, makeElaborator, markTailFunctionCalls, operandList, operandSparseList, optimizeChildren, prepareForStreaming, process, resetLocalStaticProperties, restoreParentPointers, setEvaluationMethod, setExtraProperty, setFiltered, setFlattened, setLocation, setParentExpression, setRetainedStaticContext, setRetainedStaticContextLocally, setRetainedStaticContextThoroughly, setStaticProperty, simplify, simplifyChildren, staticTypeCheck, supportsLazyEvaluation, suppressValidation, toPattern, typeCheckChildren, typeError, unordered, verifyParentPointers, withLocation
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
Methods inherited from interface net.sf.saxon.trace.Traceable
gatherProperties
-
Constructor Details
-
FunctionCall
public FunctionCall()
-
-
Method Details
-
setOperanda
Set the data structure for the operands of this expression. This must be created during initialisation of the expression and must not be subsequently changed- Parameters:
operanda
- the data structure for expression operands
-
getOperanda
Get the data structure holding the operands of this expression.- Returns:
- the data structure holding expression operands
-
operands
Description copied from class:Expression
Get the immediate sub-expressions of this expression, with information about the relationship of each expression to its parent expression.If the expression is a Callable, then it is required that the order of the operands returned by this function is the same as the order of arguments supplied to the corresponding call() method.
- Overrides:
operands
in classExpression
- Returns:
- an iterator containing the sub-expressions of this expression
-
getTargetFunction
Get the target function to be called- Parameters:
context
- the dynamic evaluation context- Returns:
- the target function
- Throws:
XPathException
- if the target function cannot be determined
-
getFunctionName
Get the qualified of the function being called- Returns:
- the qualified name. May be null if the function is anonymous.
-
getArity
public final int getArity()Determine the number of actual arguments supplied in the function call- Returns:
- the arity (the number of arguments)
-
setArguments
Method called by the expression parser when all arguments have been supplied- Parameters:
args
- the expressions contained in the argument list of the function call
-
setOperanda
-
getArguments
Get the expressions supplied as actual arguments to the function- Returns:
- the array of expressions supplied in the argument list of the function call. The array is newly constructed to ensure that modifications to the array have no effect.
-
getArg
Get the expression supplied as the Nth argument- Parameters:
n
- the required argument, zero-based- Returns:
- the expression supplied in the relevant position
- Throws:
IllegalArgumentException
- if the value of n is out of range
-
setArg
Set the expression to be used as the Nth argument- Parameters:
n
- the required argument, zero-basedchild
- the expression to be used in the relevant position- Throws:
IllegalArgumentException
- if the value of n is out of range
-
simplifyArguments
Simplify the arguments of the function. Called from the simplify() method of each function.- Parameters:
env
- the static context- Returns:
- the result of simplifying the arguments of the expression
- Throws:
XPathException
- if an error occurs
-
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 classExpression
- Parameters:
visitor
- an expression visitorcontextInfo
- Information available statically about the context item: whether it is (possibly) absent; its static type; its streaming posture.- 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)
-
preEvaluateIfConstant
- Throws:
XPathException
-
checkFunctionCall
Check the function call against the declared function signature, applying the function conversion rules to each argument as necessary- Parameters:
target
- the function being calledvisitor
- an expression visitor- Throws:
XPathException
- if there is a type error
-
optimize
public Expression optimize(ExpressionVisitor visitor, ContextItemStaticInfo contextItemType) throws XPathException 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 classExpression
- Parameters:
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 toType.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)
-
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 classExpression
- Returns:
- the intrinsic cost of this operation, excluding the costs of evaluating the operands
-
preEvaluate
Pre-evaluate a function at compile time. Functions that do not allow pre-evaluation, or that need access to context information, can override this method.- 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
-
checkArguments
Method supplied by each class of function to check arguments during parsing, when all the argument expressions have been read- Parameters:
visitor
- the expression visitor- Throws:
XPathException
- if the arguments are incorrect
-
checkArgumentCount
Check number of arguments.
A convenience routine for use in subclasses.- Parameters:
min
- the minimum number of arguments allowedmax
- the maximum number of arguments allowed- Throws:
XPathException
- if the number of arguments is out of range
-
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.- Specified by:
getImplementationMethod
in classExpression
- Returns:
- the implementation method, for example
Expression.ITERATE_METHOD
orExpression.EVALUATE_METHOD
orExpression.PROCESS_METHOD
-
plural
Utility routine used in constructing error messages: get the word "argument" or "arguments"- Parameters:
num
- the number of argumentsthing
- the string "argument" or "parameter"- Returns:
- the singular or plural phrase for N arguments or parameters.
-
addExternalFunctionCallToPathMap
public PathMap.PathMapNodeSet addExternalFunctionCallToPathMap(PathMap pathMap, PathMap.PathMapNodeSet pathMapNodes) 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.
- Parameters:
pathMap
- the PathMap to which the expression should be addedpathMapNodes
- the node in the PathMap representing the focus at the point where this expression is called. Set to null if this expression appears at the top level, in which case the expression, if it is registered in the path map at all, must create a new path map root.- Returns:
- the pathMapNode representing the focus established by this expression, in the case where this expression is the first operand of a path expression or filter 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.
-
getExpressionName
Get a name identifying the kind of expression, in terms meaningful to a user.- Overrides:
getExpressionName
in classExpression
- 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.
-
getDisplayName
Get the name of the function for display in messages- Returns:
- the name of the function as a lexical QName
-
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- Overrides:
toString
in classExpression
- Returns:
- a representation of the expression as a string
-
toShortString
Produce a short string identifying the expression for use in error messages- Overrides:
toShortString
in classExpression
- Returns:
- a short string, sufficient to identify the expression
-
export
Diagnostic print of expression structure. The abstract expression tree is written to the supplied output destination.- Specified by:
export
in interfaceExportAgent
- Specified by:
export
in classExpression
- Parameters:
out
- the expression presenter used to display the structure- Throws:
XPathException
- if the export fails, for example if an expression is found that won't work in the target environment.
-
equals
Determine whether two expressions are equivalent- Overrides:
equals
in classExpression
- Parameters:
o
- the other operand; the result is false if this is not an Expression- Returns:
- true if the other operand is an expression and if it can be determined that the two expressions are equivalent, in the sense that they will always return the same result.
-
computeHashCode
protected int computeHashCode()Get hashCode in support of equals() method- Overrides:
computeHashCode
in classExpression
- Returns:
- a computed hash code
-
iterate
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.- Overrides:
iterate
in classExpression
- Parameters:
context
- supplies the context for evaluation- Returns:
- a SequenceIterator that can be used to iterate over the result of the expression
- Throws:
XPathException
- if any dynamic error occurs evaluating the expression
-
evaluateItem
Description copied from class:Expression
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.- Overrides:
evaluateItem
in classExpression
- Parameters:
context
- The context in which the expression is to be evaluated- Returns:
- the node or atomic value that results from evaluating the expression; or null to indicate that the result is an empty sequence
- Throws:
XPathException
- if any dynamic error occurs evaluating the expression
-
adjustRequiredType
When a call to a Java extension function appears in a context where there the required type is a Java external object (typically an xsl:variable with a declared type, or as an argument to another Java extension function), notify this required type so that the process of converting the result to an XDM value can be short-circuited.- Parameters:
requiredType
- the required type of the result of the function, determined by the context in which the function call appears- Returns:
- Ok if the type has been successfully adjusted
- Throws:
XPathException
- if the required return type is incompatible with the type actually returned by the Java method
-