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:

javax.xml.transform.SourceLocator, Callable, ContextOriginator, ExpressionOwner, Locatable, Function, GroundedValue, Item, Sequence, Location, Traceable, TraceableComponent, org.xml.sax.Locator

Direct Known Subclasses:

MemoFunction, StreamableUserFunction

public class UserFunction
extends Actor
implements Function, 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.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	UserFunction.Determinism

Field Summary

Fields

Modifier and Type	Field and Description
protected Evaluator	evaluator

Fields inherited from class net.sf.saxon.expr.instruct.Actor

body

Constructor Summary

Constructors

Constructor and Description
UserFunction() Create a user-defined function (the body must be added later)

Method Summary

Modifier and Type	Method and Description
boolean	acceptsNodesWithoutAtomization() Ask whether any of the declared arguments accept nodes without atomizing them
AtomicSequence	atomize() Atomize the item.
Sequence	call(Sequence[] actualArgs, Controller controller) Call this function.
Sequence	call(XPathContext context, Sequence[] actualArgs) Call this function to return a value.
void	callUpdating(Sequence[] actualArgs, XPathContextMajor context, PendingUpdateList pul) Call an updating function.
void	computeEvaluationMode() Determine the preferred evaluation mode for this function
boolean	containsTailCalls() Determine whether the function contains tail calls (on this or other functions)
boolean	deepEquals(Function other, XPathContext context, AtomicComparer comparer, int flags) Test whether this FunctionItem is deep-equal to another function item, under the rules of the deep-equal function
boolean	effectiveBooleanValue() Get the effective boolean value of this sequence
void	export(ExpressionPresenter presenter) Diagnostic print of expression structure.
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
AnnotationList	getAnnotations() Get the annotations defined on this function
SequenceType	getArgumentType(int n) Get the required types of an argument to this function
int	getArity() Get the arity of this function
SequenceType	getDeclaredResultType() Get the declared result type
FunctionStreamability	getDeclaredStreamability() Get the declared streamability (XSLT 3.0 attribute)
java.lang.String	getDescription() Get a description of this function for use in error messages.
UserFunction.Determinism	getDeterminism() Get the determinism of the function.
Evaluator	getEvaluator() Get the evaluation mode.
FunctionItemType	getFunctionItemType() Get the type of the function
StructuredQName	getFunctionName() Get the function name
int	getLength() Get the size of the value (the number of items)
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.
OperandRole[]	getOperandRoles() Get the roles of the arguments, for the purposes of streaming
UserFunctionParameter[]	getParameterDefinitions() Get the definitions of the declared parameters for this function
int	getReferenceCount()
SequenceType	getResultType() Get the type of value returned by this function
SymbolicName.F	getSymbolicName() Get the symbolic name of the component
java.lang.String	getTracingTag() Get a string used to identify this kind of component when used in tracing output
UnicodeString	getUnicodeStringValue() Get the value of the item as a string.
UserFunction	head() Get the first item in the sequence.
void	incrementReferenceCount()
boolean	isArray() Ask whether this function item is an array
boolean	isExportable()
java.util.Optional<java.lang.Boolean>	isInlineable() Ask whether the function can be inlined
boolean	isMap() Ask whether this function item is a map
boolean	isMemoFunction() Ask whether this function is a memo function
boolean	isOverrideExtensionFunction()
boolean	isTailRecursive() Determine whether the function contains a tail call, calling itself
boolean	isTrustedResultType() Ask if the function can be trusted to return a result of the correct type
boolean	isUpdating() Ask whether this is an updating function (as defined in XQuery Update)
Function	itemAt(int n) Get the n'th item in the value, counting from 0
XPathContextMajor	makeNewContext(XPathContext oldContext, ContextOriginator originator) Create a context for evaluating this function
void	markAsInlined() Indicate that the function is being inlined, incrementing a count of how many times it has been inlined
void	prepareForStreaming()
void	process(XPathContextMajor context, Sequence[] actualArgs, Outputter output) Call this function in "push" mode, writing the results to the current output destination.
UserFunction	reduce() Reduce the sequence to its simplest form.
void	setAnnotations(AnnotationList list) Supply a set of annotations
void	setDeclaredStreamability(FunctionStreamability streamability) Set the declared streamability (XSLT 3.0 attribute)
void	setDeterminism(UserFunction.Determinism determinism) Set the determinism of the function.
void	setEvaluator(Evaluator mode) Set the evaluation mode.
void	setFunctionName(StructuredQName name) Set the function name
void	setInlineable(boolean inlineable) Say whether this function can be inlined
void	setOverrideExtensionFunction(boolean overrideExtensionFunction)
void	setParameterDefinitions(UserFunctionParameter[] params) Set the definitions of the declared parameters for this function
void	setResultType(SequenceType resultType) Set the declared result type of the function
void	setTailRecursive(boolean tailCalls, boolean recursiveTailCalls) Indicate whether the function contains a tail call
void	setUpdating(boolean isUpdating) Set whether this is an updating function (as defined in XQuery Update)
GroundedValue	subsequence(int start, int length) Get a subsequence of the value
void	typeCheck(ExpressionVisitor visitor)

Methods inherited from class net.sf.saxon.expr.instruct.Actor

allocateAllBindingSlots, allocateBindingSlotsRecursive, getBody, getChildExpression, getColumnNumber, getComponentName, getDeclaredVisibility, getDeclaringComponent, getLineNumber, getLocation, getPackageData, getProperty, getPublicId, getRetainedStaticContext, getStackFrameMap, getSystemId, makeDeclaringComponent, obtainDeclaringComponent, saveLocation, setBody, setChildExpression, setColumnNumber, setDeclaredVisibility, setDeclaringComponent, setLineNumber, setPackageData, setRetainedStaticContext, setStackFrameMap, setSystemId

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface net.sf.saxon.om.Function

getGenre, isSequenceVariadic, toShortString

Methods inherited from interface net.sf.saxon.om.Item

getStringValue, isStreamed, iterate

Methods inherited from interface net.sf.saxon.om.GroundedValue

asIterable, concatenate, containsNode, materialize

Methods inherited from interface net.sf.saxon.om.Sequence

makeRepeatable

Methods inherited from interface net.sf.saxon.trace.TraceableComponent

getBody, setBody

Methods inherited from interface net.sf.saxon.expr.Locatable

getLocation

Field Detail

evaluator

protected Evaluator evaluator

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:

a diagnostic string used to identify the component when tracing

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

getFunctionItemType

public FunctionItemType getFunctionItemType()

Get the type of the function

Specified by:

getFunctionItemType in interface Function

Returns:

the function type

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.util.Optional<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

setEvaluator

public void setEvaluator(Evaluator 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)

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

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

Ask if the function can be trusted to return a result of the correct type

Specified by:

isTrustedResultType in interface Function

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

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:

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

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