net.sf.saxon.functions
public abstract class ExtensionFunctionCall extends Object implements Serializable
Instances of this class are created by calling the method makeCallExpression() on the ExtensionFunctionDefinition object that represents the definition of the function.
The compiler will create one instance of this class for each function call appearing in the expression being compiled. The class must therefore have a public zero-argument constructor.
The compiler will ensure that the supplied arguments in the extension function call are converted if necessary to the declared argument types, by applying the standard conversion rules. The result returned by the function is checked against the declared return type, but no conversion takes place: the returned value must strictly conform to the declared type.
Note that an IntegratedFunction is trusted; calls are allowed even if the configuration option ALLOW_EXTERNAL_FUNCTIONS is false. In cases where an IntegratedFunction is used to load and execute untrusted code, it should check this configuration option before doing so.
Since: 9.2
Field Summary | |
---|---|
ExtensionFunctionDefinition | definition |
Method Summary | |
---|---|
abstract SequenceIterator | call(SequenceIterator[] arguments, XPathContext context)
Evaluate this function call at run-time
|
void | copyLocalData(ExtensionFunctionCall destination)
Copy local data from one copy of the function to another. |
boolean | effectiveBooleanValue(SequenceIterator[] arguments, XPathContext context)
Compute the effective boolean value of the result.
|
ExtensionFunctionDefinition | getDefinition()
Get the definition of this extension function |
Expression | rewrite(StaticContext context, Expression[] arguments)
Rewrite the function call. |
void | setDefinition(ExtensionFunctionDefinition definition) |
void | supplyStaticContext(StaticContext context, int locationId, Expression[] arguments)
Supply static context information.
|
Parameters: arguments The values of the arguments to the function call. Each argument value (which is in general
a sequence) is supplied in the form of an iterator over the items in the sequence. If required, the
supplied sequence can be materialized by calling, for example, new SequenceExtent(arguments[i])
.
If the argument is always a singleton, then the single item may be obtained by calling
arguments[i].next()
. The implementation is not obliged to read all the items in each
SequenceIterator
if they are not required to compute the result; but if any SequenceIterator is not read
to completion, it is good practice to call its close() method. context The XPath dynamic evaluation context
Returns: an iterator over the results of the function. If the result is a single item, it can be
returned in the form of a SingletonIterator. If the result is an empty sequence,
the method should return EmptyIterator.getInstance()
Throws: XPathException if a dynamic error occurs during evaluation of the function. The Saxon run-time code will add information about the error location.
This method is called if a call to the extension function needs to be copied during the process of optimization. For example, this occurs if the function containing the call to the extension function is inlined.
If any objects held as local data for the function call are mutable then deep copies must be made.
Parameters: destination the function to which the local data must be copied. This will always be an instance of the same function class as the source function.
Implementations can override this method but are not required to do so. If it is overridden, the result must be consistent with the rules for calculating effective boolean value. The method should be implemented in cases where computing the effective boolean value is significantly cheaper than computing the full result.
Parameters: context The XPath dynamic evaluation context arguments The values of the arguments to the function call. Each argument value (which is in general
a sequence) is supplied in the form of an iterator over the items in the sequence. If required, the
supplied sequence can be materialized by calling, for example, new SequenceExtent(arguments[i])
.
If the argument is always a singleton, then the single item may be obtained by calling
arguments[i].next()
. The implementation is not obliged to read all the items in each
SequenceIterator
if they are not required to compute the result; but if any SequenceIterator is not read
to completion, it is good practice to call its close() method.
Returns: the effective boolean value of the result
Throws: XPathException if a dynamic error occurs during evaluation of the function. The Saxon run-time code will add information about the error location.
Returns: the function definition from which this ExtensionFunctionCall was created
There is also a further opportunity to perform static checking at this stage and to throw an error if the arguments are invalid.
Parameters: context The static context in which the function call appears. The method must not modify the static context. arguments The XPath expressions supplied in the call to this function. This method is called after type-checking, so these expressions may have been modified by adding atomization operators or type-checking operations, for example.
Returns: an expression to be evaluated at run-time in place of this function call. Return null if no rewriting is required and the function call should be used unchanged. Return a Literal representing the result of the function call if the function call can be precomputed at compile time
Throws: XPathException if the implementation is able to detect a static error in the way the function is being called (for example it might require that the types of the arguments are consistent with each other).
This method is called during compilation to provide information about the static context in which the function call appears. If the implementation of the function needs information from the static context, then it should save it now, as it will not be available later at run-time.
The implementation also has the opportunity to examine the expressions that appear in the arguments to the function call at this stage. These might already have been modified from the original expressions as written by the user. The implementation must not modify any of these expressions.
The default implementation of this method does nothing.
Parameters: context The static context in which the function call appears. The method must not modify the static context. locationId An integer code representing the location of the call to the extension function in the stylesheet; can be used in conjunction with the locationMap held in the static context for diagnostics arguments The XPath expressions supplied in the call to this function. The method must not modify this array, or any of the expressions contained in the array.
Throws: XPathException if the implementation is able to detect a static error in the way the function is being called (for example it might require that the types of the arguments are consistent with each other).