net.sf.saxon.instruct

Class UserFunction

public class UserFunction extends Procedure

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 Summary
protected intevaluationMode
Constructor Summary
UserFunction()
Create a user-defined function (the body must be added later)
Method Summary
ValueRepresentationcall(ValueRepresentation[] actualArgs, XPathContextMajor context)
Call this function to return a value.
ValueRepresentationcall(ValueRepresentation[] actualArgs, Controller controller)
Call this function.
voidcallUpdating(ValueRepresentation[] actualArgs, XPathContextMajor context, PendingUpdateList pul)
Call an updating function.
voidcomputeEvaluationMode()
Determine the preferred evaluation mode for this function
booleancontainsTailCalls()
Determine whether the function contains tail calls (on this or other functions)
voidgatherDirectContributingCallees(Set result)
Gather the direct contributing callees of this function.
SequenceTypegetArgumentType(int n)
Get the required types of an argument to this function
intgetConstructType()
Get the type of construct.
SequenceTypegetDeclaredResultType()
Get the declared result type
intgetEvaluationMode()
Get the evaluation mode.
StructuredQNamegetFunctionName()
Get the function name
intgetNumberOfArguments()
Get the arity of this function
StructuredQNamegetObjectName()
Get a name identifying the object of the expression, for example a function name, template name, variable name, key name, element name, etc.
UserFunctionParameter[]getParameterDefinitions()
Get the definitions of the declared parameters for this function
SequenceTypegetResultType(TypeHierarchy th)
Get the type of value returned by this function
booleanisMemoFunction()
Ask whether this function is a memo function
booleanisTailRecursive()
Determine whether the function contains a tail call, calling itself
booleanisUpdating()
Ask whether this is an updating function (as defined in XQuery Update)
EventIteratoriterateEvents(ValueRepresentation[] actualArgs, XPathContextMajor context)
Call this function in "pull" mode, returning the results as a sequence of PullEvents.
voidprocess(ValueRepresentation[] actualArgs, XPathContextMajor context)
Call this function in "push" mode, writing the results to the current output destination.
voidsetFunctionName(StructuredQName name)
Set the function name
voidsetParameterDefinitions(UserFunctionParameter[] params)
Set the definitions of the declared parameters for this function
voidsetResultType(SequenceType resultType)
Set the declared result type of the function
voidsetTailRecursive(boolean tailCalls, boolean recursiveTailCalls)
Indicate whether the function contains a tail call
voidsetUpdating(boolean isUpdating)
Set whether this is an updating function (as defined in XQuery Update)

Field Detail

evaluationMode

protected int evaluationMode

Constructor Detail

UserFunction

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

Method Detail

call

public ValueRepresentation call(ValueRepresentation[] actualArgs, XPathContextMajor context)
Call this function to return a value.

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

Returns: a Value representing the result of the function.

call

public ValueRepresentation call(ValueRepresentation[] actualArgs, Controller controller)
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. 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.

callUpdating

public void callUpdating(ValueRepresentation[] actualArgs, XPathContextMajor context, PendingUpdateList pul)
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.

computeEvaluationMode

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

containsTailCalls

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

Returns: true if the function contains tail calls

gatherDirectContributingCallees

public void gatherDirectContributingCallees(Set result)
Gather the direct contributing callees of this function. A callee is a function that this one calls. A contributing callee is a function whose output is added directly to the output of this function without further processing (other than by attaching it to a parent element or document node). A direct contributing callee is a function that is called directly, rather than indirectly.

Parameters: result the list into which the callees are gathered.

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

getConstructType

public int getConstructType()
Get the type of construct. This will either be the fingerprint of a standard XSLT instruction name (values in StandardNames: all less than 1024) or it will be a constant in class Location.

getDeclaredResultType

public SequenceType getDeclaredResultType()
Get the declared result type

Returns: the declared result type

getEvaluationMode

public int getEvaluationMode()
Get the evaluation mode. The evaluation mode will be computed if this has not already been done

Returns: the computed evaluation mode

getFunctionName

public StructuredQName getFunctionName()
Get the function name

Returns: the function name, as a StructuredQName

getNumberOfArguments

public int getNumberOfArguments()
Get the arity of this function

Returns: the number of arguments

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.

getParameterDefinitions

public UserFunctionParameter[] getParameterDefinitions()
Get the definitions of the declared parameters for this function

Returns: an array of parameter definitions

getResultType

public SequenceType getResultType(TypeHierarchy th)
Get the type of value returned by this function

Parameters: th the type hierarchy cache

Returns: the declared result type, or the inferred result type if this is more precise

isMemoFunction

public boolean isMemoFunction()
Ask whether this function is a memo function

Returns: false (overridden in a subclass)

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

isUpdating

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

Returns: true if this is an updating function

iterateEvents

public EventIterator iterateEvents(ValueRepresentation[] actualArgs, XPathContextMajor context)
Call this function in "pull" mode, returning the results as a sequence of PullEvents.

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

Returns: an iterator over the results of the function call

process

public void process(ValueRepresentation[] actualArgs, XPathContextMajor context)
Call this function in "push" mode, writing the results to the current output destination.

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

setFunctionName

public void setFunctionName(StructuredQName name)
Set the function name

Parameters: name the function name

setParameterDefinitions

public void setParameterDefinitions(UserFunctionParameter[] params)
Set the definitions of the declared parameters for this function

Parameters: params 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)

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