public class UserFunction extends Actor implements Function, ContextOriginator, TraceableComponent
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.
Modifier and Type | Class and Description |
---|---|
static class |
UserFunction.Determinism |
Constructor and Description |
---|
UserFunction()
Create a user-defined function (the body must be added later)
|
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) |
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
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
getGenre, isSequenceVariadic, toShortString
getStringValue, isStreamed, iterate
asIterable, concatenate, containsNode, materialize
makeRepeatable
getBody, setBody
getLocation
protected Evaluator evaluator
public UserFunction()
public void setFunctionName(StructuredQName name)
name
- the function namepublic StructuredQName getFunctionName()
getFunctionName
in interface Function
public java.lang.String getDescription()
getDescription
in interface Function
public java.lang.String getTracingTag()
Actor
getTracingTag
in interface TraceableComponent
getTracingTag
in class Actor
public void gatherProperties(java.util.function.BiConsumer<java.lang.String,java.lang.Object> consumer)
gatherProperties
in interface Traceable
consumer
- the function to which the properties should be supplied, as (property name,
value) pairs.public StructuredQName getObjectName()
getObjectName
in interface Traceable
public SymbolicName.F getSymbolicName()
Actor
getSymbolicName
in class Actor
public FunctionItemType getFunctionItemType()
getFunctionItemType
in interface Function
public OperandRole[] getOperandRoles()
getOperandRoles
in interface Function
public boolean acceptsNodesWithoutAtomization()
public boolean isOverrideExtensionFunction()
public void setOverrideExtensionFunction(boolean overrideExtensionFunction)
public void setAnnotations(AnnotationList list)
list
- the new set of annotations, which will replace any previous annotations on the functionpublic AnnotationList getAnnotations()
getAnnotations
in interface Function
public void setDeterminism(UserFunction.Determinism determinism)
determinism
- the determinism value for the functionpublic UserFunction.Determinism getDeterminism()
public void computeEvaluationMode()
public java.util.Optional<java.lang.Boolean> isInlineable()
public void setInlineable(boolean inlineable)
inlineable
- true or falsepublic void markAsInlined()
public void setParameterDefinitions(UserFunctionParameter[] params)
params
- an array of parameter definitionspublic UserFunctionParameter[] getParameterDefinitions()
public void setResultType(SequenceType resultType)
resultType
- the declared return typepublic void setTailRecursive(boolean tailCalls, boolean recursiveTailCalls)
tailCalls
- true if the function contains a tail call (on any function)recursiveTailCalls
- true if the function contains a tail call (on itself)public boolean containsTailCalls()
public boolean isTailRecursive()
public void setUpdating(boolean isUpdating)
isUpdating
- true if this is an updating functionpublic boolean isUpdating()
public void setDeclaredStreamability(FunctionStreamability streamability)
streamability
- the declared streamability (defaults to "unclassified")public FunctionStreamability getDeclaredStreamability()
public SequenceType getResultType()
public SequenceType getDeclaredResultType()
public SequenceType getArgumentType(int n)
n
- identifies the argument in question, starting at 0public Evaluator getEvaluator()
public void setEvaluator(Evaluator mode)
mode
- the evaluation modepublic int getArity()
public boolean isMemoFunction()
public void typeCheck(ExpressionVisitor visitor) throws XPathException
XPathException
public XPathContextMajor makeNewContext(XPathContext oldContext, ContextOriginator originator)
makeNewContext
in interface Function
oldContext
- the existing context of the calleroriginator
- identifies the location of the caller for diagnosticspublic Sequence call(XPathContext context, Sequence[] actualArgs) throws XPathException
call
in interface Callable
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.XPathException
- if a dynamic error occurs while evaluating the functionpublic void process(XPathContextMajor context, Sequence[] actualArgs, Outputter output) throws XPathException
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 resultXPathException
- if a dynamic error occurs while evaluating the functionpublic Sequence call(Sequence[] actualArgs, Controller controller) throws XPathException
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.XPathException
- if a dynamic error occurs while evaluating the function.public void callUpdating(Sequence[] actualArgs, XPathContextMajor context, PendingUpdateList pul) throws XPathException
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 contextpul
- the pending updates list, to which the function's update actions are to be added.XPathException
- if a dynamic error occurs while evaluating the function.public void export(ExpressionPresenter presenter) throws XPathException
export
in interface Function
export
in class Actor
presenter
- the expression presenter used to display the structureXPathException
- if things go wrong, for example an I/O failurepublic boolean isExportable()
isExportable
in class Actor
public boolean isTrustedResultType()
Function
isTrustedResultType
in interface Function
public boolean isMap()
public boolean isArray()
public boolean deepEquals(Function other, XPathContext context, AtomicComparer comparer, int flags) throws XPathException
deepEquals
in interface Function
other
- the other function itemcontext
- the dynamic evaluation contextcomparer
- the object to perform the comparisonflags
- options for how the comparison is performedXPathException
- if the comparison cannot be performedpublic Function itemAt(int n)
itemAt
in interface GroundedValue
itemAt
in interface Item
n
- the index of the required item, with 0 representing the first item in the sequencepublic GroundedValue subsequence(int start, int length)
subsequence
in interface GroundedValue
subsequence
in interface Item
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 returnedlength
- 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 sequencepublic int getLength()
getLength
in interface GroundedValue
getLength
in interface Item
public boolean effectiveBooleanValue() throws XPathException
effectiveBooleanValue
in interface GroundedValue
XPathException
- if the sequence has no effective boolean value (for example a sequence of two integers)public UserFunction reduce()
reduce
in interface GroundedValue
reduce
in interface Item
public UserFunction head()
Sequence
in that
no exception is thrown.public UnicodeString getUnicodeStringValue()
getUnicodeStringValue
in interface GroundedValue
getUnicodeStringValue
in interface Item
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)public AtomicSequence atomize() throws XPathException
atomize
in interface Item
XPathException
- if atomization is not allowed
for this kind of itempublic void incrementReferenceCount()
public int getReferenceCount()
public void prepareForStreaming() throws XPathException
XPathException
Copyright (c) 2004-2022 Saxonica Limited. All rights reserved.