net.sf.saxon.instruct
Class UserFunction

java.lang.Object
  |
  +--net.sf.saxon.instruct.Procedure
        |
        +--net.sf.saxon.instruct.UserFunction
All Implemented Interfaces:
Container, InstructionInfoProvider, java.io.Serializable, javax.xml.transform.SourceLocator

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.

See Also:
Serialized Form

Constructor Summary
UserFunction()
           
UserFunction(Expression body)
           
 
Method Summary
 Value call(Value[] actualArgs, Controller controller)
          Call this function.
 Value call(Value[] actualArgs, XPathContextMajor context, boolean evaluateTailCalls)
          Call this function.
 SequenceType[] getArgumentTypes()
          Get the required types of the arguments to this function, as an array
 java.lang.String getFunctionDisplayName(NamePool pool)
          Get the display name of the function (a lexical QName), for diagnostics
 int getFunctionFingerprint()
          Get the name of the function, as a namepool fingerprint
 int getFunctionNameCode()
          Get the namepool name code of the function
 InstructionInfo getInstructionInfo()
          Get the InstructionInfo details about the construct.
 int getNumberOfArguments()
          Get the arity of this function
 SequenceType getResultType()
          Get the type of value returned by this function
 void setArgumentTypes(SequenceType[] argumentTypes)
           
 void setFunctionNameCode(int nameCode)
          Set the namepool name code of the function
 void setMemoFunction(boolean isMemo)
          Mark this function as a memo function (or not)
 void setResultType(SequenceType resultType)
           
 
Methods inherited from class net.sf.saxon.instruct.Procedure
getBody, getColumnNumber, getExecutable, getLineNumber, getPublicId, getStackFrameMap, getSystemId, setBody, setExecutable, setLineNumber, setStackFrameMap, setSystemId
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

UserFunction

public UserFunction()

UserFunction

public UserFunction(Expression body)
Method Detail

setArgumentTypes

public void setArgumentTypes(SequenceType[] argumentTypes)

setResultType

public void setResultType(SequenceType resultType)

getFunctionFingerprint

public int getFunctionFingerprint()
Get the name of the function, as a namepool fingerprint

Returns:
the fingerprint of the function name

getFunctionDisplayName

public java.lang.String getFunctionDisplayName(NamePool pool)
Get the display name of the function (a lexical QName), for diagnostics


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

getArgumentTypes

public SequenceType[] getArgumentTypes()
Get the required types of the arguments to this function, as an array

Returns:
an array of SequenceType objects, one for each formal argument, indicating the required type of the argument

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

setFunctionNameCode

public void setFunctionNameCode(int nameCode)
Set the namepool name code of the function

Parameters:
nameCode - represents the function name

getFunctionNameCode

public int getFunctionNameCode()
Get the namepool name code of the function

Returns:
a name code representing the function name

call

public Value call(Value[] actualArgs,
                  XPathContextMajor context,
                  boolean evaluateTailCalls)
           throws XPathException
Call this 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 - 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.
evaluateTailCalls - if true, then any function calls contained in the body of the function are evaluated in the normal way, whether or not they are marked as tail calls. If the argument is false, then tail calls are not evaluated, and instead a FunctionCallPackage is returned containing the information needed to evaluate the function. The caller must then be prepared to deal with this returned value by evaluating the packaged function call (which may return further packaged function calls, and so on).
Returns:
a Value representing the result of the function.
XPathException

call

public Value call(Value[] 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.getController(). 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.
XPathException

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