net.sf.saxon.instruct

Class UserFunction

Implemented Interfaces:
Container, InstructionInfoProvider, Serializable, SourceLocator, LocationProvider

public final class UserFunction
extends Procedure
implements InstructionInfoProvider

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

Fields inherited from class net.sf.saxon.instruct.Procedure

body

Constructor Summary

UserFunction()
Create a user-defined function with no body (the body must be added later)
UserFunction(Expression body)
Create a user-defined function

Method Summary

ValueRepresentation
call(ValueRepresentation[] actualArgs, Controller controller)
Call this function.
ValueRepresentation
call(ValueRepresentation[] actualArgs, XPathContextMajor context)
Call this function to return a value.
void
computeEvaluationMode()
Determine the preferred evaluation mode for this function
boolean
containsTailCalls()
Determine whether the function contains tail calls (on this or other functions)
void
gatherDirectContributingCallees(Set result)
Gather the direct contributing callees of this function.
SequenceType
getArgumentType(int n)
Get the required types of an argument to this function
int
getEvaluationMode()
Get the evaluation mode.
StructuredQName
getFunctionName()
Get the function name
InstructionInfo
getInstructionInfo()
Get the InstructionInfo details about the construct.
int
getNumberOfArguments()
Get the arity of this function
UserFunctionParameter[]
getParameterDefinitions()
Get the definitions of the declared parameters for this function
SequenceType
getResultType(TypeHierarchy th)
Get the type of value returned by this function
boolean
isMemoFunction()
Ask whether this function is a memo function
boolean
isTailRecursive()
Determine whether the function contains a tail call, calling itself
EventIterator
iterateEvents(ValueRepresentation[] actualArgs, XPathContextMajor context)
Call this function in "pull" mode, returning the results as a sequence of PullEvents.
void
process(ValueRepresentation[] actualArgs, XPathContextMajor context)
Call this function in "push" mode, writing the results to the current output destination.
void
setFunctionName(StructuredQName name)
Set the function name
void
setMemoFunction(boolean isMemo)
Mark this function as a memo function (or not)
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

Methods inherited from class net.sf.saxon.instruct.Procedure

getBody, getColumnNumber, getExecutable, getHostLanguage, getLineNumber, getLineNumber, getLocationProvider, getPublicId, getStackFrameMap, getSystemId, getSystemId, replaceSubExpression, setBody, setExecutable, setHostLanguage, setLineNumber, setStackFrameMap, setSystemId

Constructor Details

UserFunction

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

UserFunction

public UserFunction(Expression body)
Create a user-defined function
Parameters:
body - the expression comprising the body of the function, which is evaluated to compute the result of the function

Method Details

call

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

call

public ValueRepresentation call(ValueRepresentation[] actualArgs,
                                XPathContextMajor context)
            throws XPathException
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.

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

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

getInstructionInfo

public InstructionInfo getInstructionInfo()
Get the InstructionInfo details about the construct. This information isn't used for tracing, but it is available when inspecting the context stack.
Specified by:
getInstructionInfo in interface InstructionInfoProvider

getNumberOfArguments

public int getNumberOfArguments()
Get the arity of this function
Returns:
the number of arguments

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:
true if this function is marked as a memo function

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

iterateEvents

public EventIterator iterateEvents(ValueRepresentation[] actualArgs,
                                   XPathContextMajor context)
            throws XPathException
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)
            throws XPathException
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

setMemoFunction

public void setMemoFunction(boolean isMemo)
Mark this function as a memo function (or not)
Parameters:
isMemo - true if this is a memo function

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)