Class ExtensionFunctionCall
- All Implemented Interfaces:
Callable
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 ExtensionFunctionCall
is trusted; calls are allowed even if the configuration option
FeatureKeys.ALLOW_EXTERNAL_FUNCTIONS
is false. In cases where an ExtensionFunctionCall
is used to load and execute untrusted code, it should check this configuration option before doing so.
- Since:
- 9.2; modified in 9.5 to use Sequence rather than SequenceIterator for the arguments and result
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionabstract Sequence
call
(XPathContext context, Sequence[] arguments) Evaluate this function call at run-timevoid
copyLocalData
(ExtensionFunctionCall destination) Deprecated.since 12.0boolean
effectiveBooleanValue
(XPathContext context, Sequence[] arguments) Compute the effective boolean value of the result.Get the definition of this extension functionGet a streamable implementation of this extension function.rewrite
(StaticContext context, Expression[] arguments) Rewrite the function call.final void
setDefinition
(ExtensionFunctionDefinition definition) This method is called by the system to provide information about the extension function call.void
supplyStaticContext
(StaticContext context, int locationId, Expression[] arguments) Supply static context information.
-
Constructor Details
-
ExtensionFunctionCall
public ExtensionFunctionCall()
-
-
Method Details
-
setDefinition
This method is called by the system to provide information about the extension function call. It should not be called by the implementor of the extension function.- Parameters:
definition
- the extension function definition
-
getDefinition
Get the definition of this extension function- Returns:
- the function definition from which this
ExtensionFunctionCall
was created
-
supplyStaticContext
public void supplyStaticContext(StaticContext context, int locationId, Expression[] arguments) throws XPathException Supply static context information.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 diagnosticsarguments
- 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. This parameter will be null in the case where the supplied arguments are null, that is when binding a higher-order function reference or a call on fn:function-lookup().- 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).
-
rewrite
Rewrite the function call. This method is called at compile time. It gives the implementation an opportunity to replace itself with an optimized implementation that returns the same result. This includes the ability to pre-evaluate the function and return its result as a literal value.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).
-
copyLocalData
Deprecated.since 12.0Copy local data from one copy of the function to another.This method is no longer used: functions do not need to provide an implementation, and if they do so, the implementation will never be called. It is retained for the time being for backwards compatibility
- Parameters:
destination
- the function to which the local data must be copied.
-
call
Evaluate this function call at run-time- Specified by:
call
in interfaceCallable
- Parameters:
context
- The XPath dynamic evaluation contextarguments
- The values of the arguments to the function call. Each argument value (which is in general a sequence) is supplied in the form ofSequence
. Any required conversions to the declared types of the arguments will already have been performed.If the argument is always a singleton, then the single item may be obtained by calling
arguments[i].head()
.The implementation is not obliged to read all the items in each
SequenceIterator
if they are not required to compute the result; but if anySequenceIterator
is not read to completion, it is good practice to call itsclose()
method.- Returns:
- the results of the function as a
Sequence
.The implementation is responsible for ensuring that the result is a valid instance of the declared result type. Saxon will check that this is the case if the
ExtensionFunctionDefinition.trustResultType()
method returns false, but it will never convert the supplied result value to the declared result type.The
Sequence
objects used for the arguments will often be instances ofLazySequence
, which means that the items in the sequence are computed lazily on demand. This means that any errors that occur while computing the sequence might not be thrown until the relevant item is actually read from the sequence.If the result is a single item, it can be returned directly, since single items all implement
Sequence
. For example a string can be returned as an instance ofStringValue
, and a boolean as an instance ofBooleanValue
. If the result is an empty sequence, the method should returnEmptySequence.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.
-
effectiveBooleanValue
public boolean effectiveBooleanValue(XPathContext context, Sequence[] arguments) throws XPathException Compute the effective boolean value of the result.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 contextarguments
- The values of the arguments to the function call. Each argument value (which is in general a sequence) is supplied in the form ofSequence
. Any required conversions to the declared types of the arguments will already have been performed.If the argument is always a singleton, then the single item may be obtained by calling
arguments[i].head()
.The implementation is not obliged to read all the items in each
Sequence
if they are not required to compute the result; but if anySequence
is not read to completion, it is good practice to callclose()
on the iterator.- 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.
-
getStreamingImplementation
Get a streamable implementation of this extension function. This interface is provisional and currently only really intended for internal use; it is subject to change. If the value returned is non-null, then it must be an instance of com.saxonica.ee.stream.adjunct- Returns:
- the streaming implementation of the extension function
-