Package net.sf.saxon.expr.instruct

Class UserFunction

java.lang.Object
net.sf.saxon.expr.instruct.Actor
net.sf.saxon.expr.instruct.UserFunction
All Implemented Interfaces:
SourceLocator, Callable, ContextOriginator, ExpressionOwner, Locatable, FunctionDefinition, FunctionItem, GroundedValue, Item, Sequence, Location, Traceable, TraceableComponent, Locator
Direct Known Subclasses:
MemoFunction, StreamableUserFunction
public class UserFunction extends Actor implements FunctionItem, FunctionDefinition, ContextOriginator, TraceableComponent
This object represents the compiled form of a user-written function (the source can be either an XSLT stylesheet function or an XQuery function).

It is assumed that type-checking, of both the arguments and the results, has been handled at compile time. That is, the expression supplied as the body of the function must be wrapped in code to check or convert the result to the required type, and calls on the function must be wrapped at compile time to check or convert the supplied arguments.

  • Field Details

  • Constructor Details

    • UserFunction

      public UserFunction()
      Create a user-defined function (the body must be added later)

  • Method Details

    • setFunctionName

      public void setFunctionName(StructuredQName name)
      Set the function name
      Parameters:
      name - the function name

    • getFunctionName

      public StructuredQName getFunctionName()
      Get the function name
      Specified by:
      getFunctionName in interface FunctionDefinition
      Specified by:
      getFunctionName in interface FunctionItem
      Returns:
      the function name, as a StructuredQName. Returns null for an anonymous function

    • getDescription

      public String getDescription()
      Get a description of this function for use in error messages. For named functions, the description is the function name (as a lexical QName). For others, it might be, for example, "inline function", or "partially-applied ends-with function".
      Specified by:
      getDescription in interface FunctionItem
      Returns:
      a description of the function for use in error messages

    • getTracingTag

      public String getTracingTag()
      Description copied from class: Actor
      Get a string used to identify this kind of component when used in tracing output
      Specified by:
      getTracingTag in interface TraceableComponent
      Overrides:
      getTracingTag in class Actor
      Returns:
      a diagnostic string used to identify the component when tracing

    • gatherProperties

      public void gatherProperties(BiConsumer<String,Object> consumer)
      Get the properties of this object to be included in trace messages, by supplying the property values to a supplied consumer function
      Specified by:
      gatherProperties in interface Traceable
      Parameters:
      consumer - the function to which the properties should be supplied, as (property name, value) pairs.

    • getObjectName

      public StructuredQName getObjectName()
      Get a name identifying the object of the expression, for example a function name, template name, variable name, key name, element name, etc. This is used only where the name is known statically.
      Specified by:
      getObjectName in interface Traceable
      Returns:
      the QName of the object declared or manipulated by this instruction or expression

    • getSymbolicName

      public SymbolicName.F getSymbolicName()
      Description copied from class: Actor
      Get the symbolic name of the component
      Specified by:
      getSymbolicName in class Actor
      Returns:
      the symbolic name

    • getFunctionItemType

      public FunctionItemType getFunctionItemType()
      Get the type of the function
      Specified by:
      getFunctionItemType in interface FunctionItem
      Returns:
      the function type

    • getFunctionItemType

      public FunctionItemType getFunctionItemType(int arity)
      Get the type of the function when invoked with a specific number of arguments
      Returns:
      the function type

    • getOperandRoles

      public OperandRole[] getOperandRoles()
      Get the roles of the arguments, for the purposes of streaming
      Specified by:
      getOperandRoles in interface FunctionItem
      Returns:
      an array of OperandRole objects, one for each argument

    • acceptsNodesWithoutAtomization

      public boolean acceptsNodesWithoutAtomization()
      Ask whether any of the declared arguments accept nodes without atomizing them
      Returns:
      true if this is the case

    • isOverrideExtensionFunction

      public boolean isOverrideExtensionFunction()

    • setOverrideExtensionFunction

      public void setOverrideExtensionFunction(boolean overrideExtensionFunction)

    • setAnnotations

      public void setAnnotations(AnnotationList list)
      Supply a set of annotations
      Parameters:
      list - the new set of annotations, which will replace any previous annotations on the function

    • getAnnotations

      public AnnotationList getAnnotations()
      Get the annotations defined on this function
      Specified by:
      getAnnotations in interface FunctionItem
      Returns:
      the list of annotations defined on this function

    • setDeterminism

      public void setDeterminism(UserFunction.Determinism determinism)
      Set the determinism of the function. Corresponds to the XSLT 3.0 values new-each-time=yes|no|maybe
      Parameters:
      determinism - the determinism value for the function

    • getDeterminism

      public UserFunction.Determinism getDeterminism()
      Get the determinism of the function. Corresponds to the XSLT 3.0 values new-each-time=yes|no|maybe
      Returns:
      the determinism value for the function

    • computeEvaluationMode

      public void computeEvaluationMode()
      Determine the preferred evaluation mode for this function

    • isInlineable

      public Optional<Boolean> isInlineable()
      Ask whether the function can be inlined
      Returns:
      true (yes), false (no), or null (don't know)

    • setInlineable

      public void setInlineable(boolean inlineable)
      Say whether this function can be inlined
      Parameters:
      inlineable - true or false

    • markAsInlined

      public void markAsInlined()
      Indicate that the function is being inlined, incrementing a count of how many times it has been inlined

    • setParameterDefinitions

      public void setParameterDefinitions(UserFunctionParameter[] params)
      Set the definitions of the declared parameters for this function. Note that at the time this is called, full analysis of the xsl:param element is yet to be done.
      Parameters:
      params - an array of parameter definitions

    • setMinimumArity

      public void setMinimumArity(int minimumArity)

    • setArityRange

      public void setArityRange(int min, int max)

    • getParameterDefinitions

      public UserFunctionParameter[] getParameterDefinitions()
      Get the definitions of the declared parameters for this function
      Returns:
      an array of parameter definitions

    • getMinimumArity

      public int getMinimumArity()
      Get the minumum arity of this function, that is, the number of mandatory parameters
      Specified by:
      getMinimumArity in interface FunctionDefinition
      Returns:
      the minimum arity

    • setResultType

      public void setResultType(SequenceType resultType)
      Set the declared result type of the function
      Parameters:
      resultType - the declared return type

    • setTailRecursive

      public void setTailRecursive(boolean tailCalls, boolean recursiveTailCalls)
      Indicate whether the function contains a tail call
      Parameters:
      tailCalls - true if the function contains a tail call (on any function)
      recursiveTailCalls - true if the function contains a tail call (on itself)

    • containsTailCalls

      public boolean containsTailCalls()
      Determine whether the function contains tail calls (on this or other functions)
      Returns:
      true if the function contains tail calls

    • isTailRecursive

      public boolean isTailRecursive()
      Determine whether the function contains a tail call, calling itself
      Returns:
      true if the function contains a directly-recursive tail call

    • setUpdating

      public void setUpdating(boolean isUpdating)
      Set whether this is an updating function (as defined in XQuery Update)
      Parameters:
      isUpdating - true if this is an updating function

    • isUpdating

      public boolean isUpdating()
      Ask whether this is an updating function (as defined in XQuery Update)
      Returns:
      true if this is an updating function

    • setIxslUpdating

      public void setIxslUpdating(boolean isUpdating)
      Set whether this is an ixsl:updating function, as defined for use with IXSL promises in SaxonJS, allowing the function to have updating side effects
      Parameters:
      isUpdating - true if this is an updating function

    • setDeclaredStreamability

      public void setDeclaredStreamability(FunctionStreamability streamability)
      Set the declared streamability (XSLT 3.0 attribute)
      Parameters:
      streamability - the declared streamability (defaults to "unclassified")

    • getDeclaredStreamability

      public FunctionStreamability getDeclaredStreamability()
      Get the declared streamability (XSLT 3.0 attribute)
      Returns:
      the declared streamability (defaults to "unclassified")

    • getResultType

      public SequenceType getResultType()
      Get the type of value returned by this function
      Returns:
      the declared result type, or the inferred result type if this is more precise

    • getDeclaredResultType

      public SequenceType getDeclaredResultType()
      Get the declared result type
      Returns:
      the declared result type

    • getArgumentType

      public SequenceType getArgumentType(int n)
      Get the required types of an argument to this function
      Parameters:
      n - identifies the argument in question, starting at 0
      Returns:
      a SequenceType object, indicating the required type of the argument

    • getBodyEvaluator

      public SequenceEvaluator getBodyEvaluator()
      Get the evaluation mode. The evaluation mode will be computed if this has not already been done
      Returns:
      the computed evaluation mode

    • setBodyEvaluator

      public void setBodyEvaluator(SequenceEvaluator mode)
      Set the evaluation mode. (Used when reloading a saved package)
      Parameters:
      mode - the evaluation mode

    • getArity

      public int getArity()
      Get the arity of this function
      Specified by:
      getArity in interface FunctionItem
      Returns:
      the number of arguments

    • isMemoFunction

      public boolean isMemoFunction()
      Ask whether this function is a memo function
      Returns:
      false (overridden in a subclass)

    • typeCheck

      public void typeCheck(ExpressionVisitor visitor) throws XPathException
      Throws:
      XPathException

    • makeNewContext

      public XPathContextMajor makeNewContext(XPathContext oldContext, ContextOriginator originator)
      Create a context for evaluating this function
      Specified by:
      makeNewContext in interface FunctionItem
      Parameters:
      oldContext - the existing context of the caller
      originator - identifies the location of the caller for diagnostics
      Returns:
      a new context which should be supplied to the call() method.

    • call

      public Sequence call(XPathContext context, Sequence[] actualArgs) throws XPathException
      Call this function to return a value.
      Specified by:
      call in interface Callable
      Parameters:
      context - This provides the run-time context for evaluating the function. This should be created using FunctionItem.makeNewContext(XPathContext, ContextOriginator). It must be an instance of XPathContextMajor.
      actualArgs - the arguments supplied to the function. These must have the correct types required by the function signature (it is the caller's responsibility to check this). It is acceptable to supply a Closure to represent a value whose evaluation will be delayed until it is needed. The array must be the correct size to match the number of arguments: again, it is the caller's responsibility to check this.
      Returns:
      a Value representing the result of the function.
      Throws:
      XPathException - if a dynamic error occurs while evaluating the function

    • process

      public void process(XPathContextMajor context, Sequence[] actualArgs, Outputter output) throws XPathException
      Call this function in "push" mode, writing the results to the current output destination.
      Parameters:
      context - This provides the run-time context for evaluating the function. It is the caller's responsibility to allocate a "clean" context for the function to use; the context that is provided will be overwritten by the function.
      actualArgs - the arguments supplied to the function. These must have the correct types required by the function signature (it is the caller's responsibility to check this). It is acceptable to supply a Closure to represent a value whose evaluation will be delayed until it is needed. The array must be the correct size to match the number of arguments: again, it is the caller's responsibility to check this.
      output - the destination for the result
      Throws:
      XPathException - if a dynamic error occurs while evaluating the function

    • call

      public Sequence call(Sequence[] actualArgs, Controller controller) throws XPathException
      Call this function. This method allows an XQuery function to be called directly from a Java application. It creates the environment needed to achieve this
      Parameters:
      actualArgs - the arguments supplied to the function. These must have the correct types required by the function signature (it is the caller's responsibility to check this). It is acceptable to supply a Closure to represent a value whose evaluation will be delayed until it is needed. The array must be the correct size to match the number of arguments: again, it is the caller's responsibility to check this.
      controller - This provides the run-time context for evaluating the function. A Controller may be obtained by calling XQueryExpression.newController(net.sf.saxon.query.DynamicQueryContext). This may be used for a series of calls on functions defined in the same module as the XQueryExpression.
      Returns:
      a Value representing the result of the function.
      Throws:
      XPathException - if a dynamic error occurs while evaluating the function.

    • callUpdating

      public void callUpdating(Sequence[] actualArgs, XPathContextMajor context, PendingUpdateList pul) throws XPathException
      Call an updating function.
      Parameters:
      actualArgs - the arguments supplied to the function. These must have the correct types required by the function signature (it is the caller's responsibility to check this). It is acceptable to supply a Closure to represent a value whose evaluation will be delayed until it is needed. The array must be the correct size to match the number of arguments: again, it is the caller's responsibility to check this.
      context - the dynamic evaluation context
      pul - the pending updates list, to which the function's update actions are to be added.
      Throws:
      XPathException - if a dynamic error occurs while evaluating the function.

    • export

      public void export(ExpressionPresenter presenter) throws XPathException
      Diagnostic print of expression structure. The abstract expression tree is written to the supplied outputstream.
      Specified by:
      export in interface FunctionItem
      Specified by:
      export in class Actor
      Parameters:
      presenter - the expression presenter used to display the structure
      Throws:
      XPathException - if things go wrong, for example an I/O failure

    • isExportable

      public boolean isExportable()
      Overrides:
      isExportable in class Actor

    • isTrustedResultType

      public boolean isTrustedResultType()
      Description copied from interface: FunctionItem
      Ask if the function can be trusted to return a result of the correct type
      Specified by:
      isTrustedResultType in interface FunctionItem
      Returns:
      true if the implementation can be trusted

    • isMap

      public boolean isMap()
      Ask whether this function item is a map
      Specified by:
      isMap in interface FunctionItem
      Returns:
      true if this function item is a map, otherwise false

    • isArray

      public boolean isArray()
      Ask whether this function item is an array
      Specified by:
      isArray in interface FunctionItem
      Returns:
      true if this function item is an array, otherwise false

    • deepEquals

      public boolean deepEquals(FunctionItem other, XPathContext context, AtomicComparer comparer, int flags) throws XPathException
      Test whether this FunctionItem is deep-equal to another function item, under the rules of the deep-equal function
      Specified by:
      deepEquals in interface FunctionItem
      Parameters:
      other - the other function item
      context - the dynamic evaluation context
      comparer - the object to perform the comparison
      flags - options for how the comparison is performed
      Returns:
      true if the two function items are deep-equal
      Throws:
      XPathException - if the comparison cannot be performed

    • deepEqual40

      public boolean deepEqual40(FunctionItem other, XPathContext context, DeepEqual.DeepEqualOptions options) throws XPathException
      Specified by:
      deepEqual40 in interface FunctionItem
      Throws:
      XPathException

    • itemAt

      public FunctionItem itemAt(int n)
      Get the n'th item in the value, counting from 0
      Specified by:
      itemAt in interface GroundedValue
      Specified by:
      itemAt in interface Item
      Parameters:
      n - the index of the required item, with 0 representing the first item in the sequence
      Returns:
      the n'th item if it exists, or null otherwise

    • subsequence

      public GroundedValue subsequence(int start, int length)
      Get a subsequence of the value
      Specified by:
      subsequence in interface GroundedValue
      Specified by:
      subsequence in interface Item
      Parameters:
      start - the index of the first item to be included in the result, counting from zero. A negative value is taken as zero. If the value is beyond the end of the sequence, an empty sequence is returned
      length - the number of items to be included in the result. Specify Integer.MAX_VALUE to get the subsequence up to the end of the base sequence. If the value is negative, an empty sequence is returned. If the value goes off the end of the sequence, the result returns items up to the end of the sequence
      Returns:
      the required subsequence.

    • getLength

      public int getLength()
      Get the size of the value (the number of items)
      Specified by:
      getLength in interface GroundedValue
      Specified by:
      getLength in interface Item
      Returns:
      the number of items in the sequence

    • effectiveBooleanValue

      public boolean effectiveBooleanValue() throws XPathException
      Get the effective boolean value of this sequence
      Specified by:
      effectiveBooleanValue in interface GroundedValue
      Returns:
      the effective boolean value
      Throws:
      XPathException - if the sequence has no effective boolean value (for example a sequence of two integers)

    • reduce

      public UserFunction reduce()
      Reduce the sequence to its simplest form. If the value is an empty sequence, the result will be EmptySequence.getInstance(). If the value is a single atomic value, the result will be an instance of AtomicValue. If the value is a single item of any other kind, the result will be an instance of One. Otherwise, the result will typically be unchanged.
      Specified by:
      reduce in interface GroundedValue
      Specified by:
      reduce in interface Item
      Returns:
      the simplified sequence

    • head

      public UserFunction head()
      Get the first item in the sequence. Differs from the superclass Sequence in that no exception is thrown.
      Specified by:
      head in interface GroundedValue
      Specified by:
      head in interface Item
      Specified by:
      head in interface Sequence
      Returns:
      the first item in the sequence if there is one, or null if the sequence is empty

    • getUnicodeStringValue

      public UnicodeString getUnicodeStringValue()
      Get the value of the item as a string. For nodes, this is the string value of the node as defined in the XPath 2.0 data model, except that all nodes are treated as being untyped: it is not an error to get the string value of a node with a complex type. For atomic values, the method returns the result of casting the atomic value to a string.
      Specified by:
      getUnicodeStringValue in interface GroundedValue
      Specified by:
      getUnicodeStringValue in interface Item
      Returns:
      the string value of the item
      Throws:
      UnsupportedOperationException - if the item is a function item (an unchecked exception is used here to avoid introducing exception handling to a large number of paths where it is not needed)
      Since:
      8.4

    • atomize

      public AtomicSequence atomize() throws XPathException
      Atomize the item.
      Specified by:
      atomize in interface Item
      Returns:
      the result of atomization
      Throws:
      XPathException - if atomization is not allowed for this kind of item

    • incrementReferenceCount

      public void incrementReferenceCount()

    • getReferenceCount

      public int getReferenceCount()

    • prepareForStreaming

      public void prepareForStreaming() throws XPathException
      Throws:
      XPathException

    • getNumberOfParameters

      public int getNumberOfParameters()
      Get the number of declared parameters (the upper bound of the arity range)
      Specified by:
      getNumberOfParameters in interface FunctionDefinition
      Returns:
      the number of declared parameters

    • getParameterName

      public StructuredQName getParameterName(int i)
      Get the name (keyword) of the Nth parameter
      Specified by:
      getParameterName in interface FunctionDefinition
      Parameters:
      i - the position of the required parameter
      Returns:
      the expression for computing the value of the Nth parameter

    • getDefaultValueExpression

      public Expression getDefaultValueExpression(int i)
      Get the default value expression of the Nth parameter, if any
      Specified by:
      getDefaultValueExpression in interface FunctionDefinition
      Parameters:
      i - the position of the required parameter
      Returns:
      the expression for computing the value of the Nth parameter, or null if there is none

    • getPositionOfParameter

      public int getPositionOfParameter(StructuredQName name)
      Get the position in the parameter list of a given parameter name
      Specified by:
      getPositionOfParameter in interface FunctionDefinition
      Parameters:
      name - the name of the required parameter
      Returns:
      the position of the parameter in the parameter list, or -1 if absent

    • makeExpandedArgumentArray

      public static Expression[] makeExpandedArgumentArray(Expression[] arguments, Map<StructuredQName,Integer> keywords, FunctionDefinition fd) throws XPathException
      Combine supplied positional and keyword arguments into a single array of positional arguments, completing the array using the default value expression for any unsupplied arguments
      Parameters:
      arguments - the expressions supplied in the function call, including both positional and keyword arguments, in the order supplied
      keywords - a list of keywords used in the function call, with the 0-based position at which each keyword was used; or null if no keywords were used
      fd - the XQuery function definition, used to identify the position in the list of declared parameters at which a particular parameter name appears
      Returns:
      the expanded list of positional parameters
      Throws:
      XPathException - in the event of duplicate or undeclared keywords, or keywords that duplicate positional arguments