Package net.sf.saxon.expr.instruct

Class UserFunction

    • Field Detail

    • Constructor Detail

      • UserFunction

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

    • Method Detail

      • 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 Function
        Returns:
        the function name, as a StructuredQName. Returns null for an anonymous function

      • getDescription

        public java.lang.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 Function
        Returns:
        a description of the function for use in error messages

      • getTracingTag

        public java.lang.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:
        an identifying string

      • gatherProperties

        public void gatherProperties​(java.util.function.BiConsumer<java.lang.String,​java.lang.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

      • getOperandRoles

        public OperandRole[] getOperandRoles()
        Get the roles of the arguments, for the purposes of streaming
        Specified by:
        getOperandRoles in interface Function
        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 Function
        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 java.lang.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
        Parameters:
        params - an array of parameter definitions

      • getParameterDefinitions

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

      • 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

      • 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

      • getEvaluator

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

      • setEvaluationMode

        public void setEvaluationMode​(EvaluationMode 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 Function
        Returns:
        the number of arguments

      • isMemoFunction

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

      • makeNewContext

        public XPathContextMajor makeNewContext​(XPathContext oldContext,
                                        ContextOriginator originator)
        Create a context for evaluating this function
        Specified by:
        makeNewContext in interface Function
        Parameters:
        oldContext - the existing context of the caller
        originator -
        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
        Specified by:
        call in interface Function
        Parameters:
        context - This provides the run-time context for evaluating the function. This should be created using Function.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.
        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 Function
        Specified by:
        export in class Actor
        Parameters:
        presenter - the expression presenter used to display the structure
        Throws:
        XPathException

      • isExportable

        public boolean isExportable()
        Overrides:
        isExportable in class Actor

      • isTrustedResultType

        public boolean isTrustedResultType()
        Description copied from interface: Function
        Check that result type is of the trusted system functions to return a result of the correct type
        Specified by:
        isTrustedResultType in interface Function

      • isMap

        public boolean isMap()
        Ask whether this function item is a map
        Specified by:
        isMap in interface Function
        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 Function
        Returns:
        true if this function item is an array, otherwise false

      • deepEquals

        public boolean deepEquals​(Function 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 Function
        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

      • itemAt

        public Function 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

      • getStringValue

        public java.lang.String getStringValue()
        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.

        If the calling code can handle any CharSequence, the method getStringValueCS() should be used. If the caller requires a string, this method is preferred.

        Specified by:
        getStringValue in interface GroundedValue
        Specified by:
        getStringValue in interface Item
        Returns:
        the string value of the item
        Throws:
        java.lang.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
        See Also:
        getStringValueCS()

      • getStringValueCS

        public java.lang.CharSequence getStringValueCS()
        Get the string value of the item as a CharSequence. This is in some cases more efficient than the version of the method that returns a String. The method satisfies the rule that X.getStringValueCS().toString() returns a string that is equal to X.getStringValue().

        Note that two CharSequence values of different types should not be compared using equals(), and for the same reason they should not be used as a key in a hash table.

        If the calling code can handle any CharSequence, this method should be used. If the caller requires a string, the getStringValue() method is preferred.

        Specified by:
        getStringValueCS in interface GroundedValue
        Specified by:
        getStringValueCS in interface Item
        Returns:
        the string value of the item
        Throws:
        java.lang.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
        See Also:
        getStringValue()

      • incrementReferenceCount

        public void incrementReferenceCount()

      • getReferenceCount

        public int getReferenceCount()