Package net.sf.saxon.instruct
Class UserFunction
- java.lang.Object
-
- net.sf.saxon.instruct.Procedure
-
- net.sf.saxon.instruct.UserFunction
-
- All Implemented Interfaces:
java.io.Serializable
,javax.xml.transform.SourceLocator
,LocationProvider
,SaxonLocator
,Container
,InstructionInfo
,org.xml.sax.Locator
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.
- See Also:
- Serialized Form
-
-
Constructor Summary
Constructors Constructor Description 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
All Methods Instance Methods Concrete Methods Modifier and Type Method Description ValueRepresentation
call(ValueRepresentation[] actualArgs, Controller controller)
Call this function.ValueRepresentation
call(ValueRepresentation[] actualArgs, XPathContextMajor context)
Call this function to return a value.void
callUpdating(ValueRepresentation[] actualArgs, XPathContextMajor context, PendingUpdateList pul)
Call an updating function.void
computeEvaluationMode()
Determine the preferred evaluation mode for this functionboolean
containsTailCalls()
Determine whether the function contains tail calls (on this or other functions)void
gatherDirectContributingCallees(java.util.Set result)
Gather the direct contributing callees of this function.SequenceType
getArgumentType(int n)
Get the required types of an argument to this functionint
getConstructType()
Get the type of construct.int
getEvaluationMode()
Get the evaluation mode.StructuredQName
getFunctionName()
Get the function nameint
getNumberOfArguments()
Get the arity of this functionStructuredQName
getObjectName()
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 functionSequenceType
getResultType(TypeHierarchy th)
Get the type of value returned by this functionboolean
isMemoFunction()
Ask whether this function is a memo functionboolean
isTailRecursive()
Determine whether the function contains a tail call, calling itselfboolean
isUpdating()
Ask whether this is an updating function (as defined in XQuery Update)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 namevoid
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 functionvoid
setResultType(SequenceType resultType)
Set the declared result type of the functionvoid
setTailRecursive(boolean tailCalls, boolean recursiveTailCalls)
Indicate whether the function contains a tail callvoid
setUpdating(boolean isUpdating)
Set whether this is an updating function (as defined in XQuery Update)-
Methods inherited from class net.sf.saxon.instruct.Procedure
getBody, getColumnNumber, getColumnNumber, getExecutable, getHostLanguage, getLineNumber, getLineNumber, getLocationProvider, getProperties, getProperty, getPublicId, getStackFrameMap, getSystemId, getSystemId, replaceSubExpression, setBody, setExecutable, setHostLanguage, setLineNumber, setStackFrameMap, setSystemId
-
-
-
-
Constructor Detail
-
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 Detail
-
setFunctionName
public void setFunctionName(StructuredQName name)
Set the function name- Parameters:
name
- the function name
-
getFunctionName
public StructuredQName getFunctionName()
Get the function name- Returns:
- the function name, as a StructuredQName
-
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.- Returns:
- the QName of the object declared or manipulated by this instruction or expression
-
computeEvaluationMode
public void computeEvaluationMode()
Determine the preferred evaluation mode for this function
-
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
-
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
-
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
-
getNumberOfArguments
public int getNumberOfArguments()
Get the arity of this function- Returns:
- the number of arguments
-
setMemoFunction
public void setMemoFunction(boolean isMemo)
Mark this function as a memo function (or not)- Parameters:
isMemo
- true if this is a memo function
-
isMemoFunction
public boolean isMemoFunction()
Ask whether this function is a memo function- Returns:
- true if this function is marked as a memo function
-
gatherDirectContributingCallees
public void gatherDirectContributingCallees(java.util.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.
-
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 aClosure
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.
- Throws:
XPathException
-
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 aClosure
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.- Throws:
XPathException
-
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 aClosure
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
- Throws:
XPathException
-
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 aClosure
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 callingXQueryExpression.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.
- Throws:
XPathException
-
callUpdating
public void callUpdating(ValueRepresentation[] 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 aClosure
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.- Throws:
XPathException
-
getConstructType
public int getConstructType()
Get the type of construct. This will either be the fingerprint of a standard XSLT instruction name (values inStandardNames
: all less than 1024) or it will be a constant in classLocation
.- Returns:
- an integer identifying the kind of construct
-
-