net.sf.saxon.expr.instruct

## Class UserFunction

- java.lang.Object
- - net.sf.saxon.expr.instruct.Procedure
  - - net.sf.saxon.expr.instruct.UserFunction

- All Implemented Interfaces:
    Serializable, SourceLocator, LocationProvider, SaxonLocator, Container, InstructionInfo, Locator
  Direct Known Subclasses:
    MemoFunction

      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

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected int` | `evaluationMode`

    - ### Fields inherited from class net.sf.saxon.expr.instruct.Procedure

      `body`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `UserFunction()` Create a user-defined function (the body must be added later)

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `Callable` | `asCallable()`
    `Sequence` | `call(Sequence[] actualArgs, Controller controller)` Call this function.
    `Sequence` | `call(XPathContextMajor 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)
    `SequenceType` | `getArgumentType(int n)` Get the required types of an argument to this function
    `int` | `getConstructType()` Get the type of construct.
    `SequenceType` | `getDeclaredResultType()` Get the declared result type
    `int` | `getEvaluationMode()` Get the evaluation mode.
    `StructuredQName` | `getFunctionName()` Get the function name
    `FunctionItemType` | `getFunctionType()` Get the type of the function
    `int` | `getNumberOfArguments()` Get the arity of this function
    `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.
    `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` | `isInlineable()` Ask whether the function can be inlined
    `boolean` | `isMemoFunction()` Ask whether this function is a memo function
    `boolean` | `isTailRecursive()` Determine whether the function contains a tail call, calling itself
    `boolean` | `isUpdating()` Ask whether this is an updating function (as defined in XQuery Update)
    `EventIterator` | `iterateEvents(Sequence[] actualArgs, XPathContextMajor context)` Call this function in "pull" mode, returning the results as a sequence of PullEvents.
    `void` | `process(Sequence[] actualArgs, XPathContextMajor context)` Call this function in "push" mode, writing the results to the current output destination.
    `void` | `setAnnotationMap(Map<StructuredQName,Annotation> map)` Supply a set of annotations
    `void` | `setFunctionName(StructuredQName name)` Set the function name
    `void` | `setInlineable(boolean inlineable)` Say whether this function can be inlined
    `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)

    - ### Methods inherited from class net.sf.saxon.expr.instruct.Procedure

      `getBody, getColumnNumber, getColumnNumber, getContainerGranularity, getExecutable, getHostLanguage, getLineNumber, getLineNumber, getLocationProvider, getProperties, getProperty, getPublicId, getStackFrameMap, getSystemId, getSystemId, setBody, setExecutable, setHostLanguage, setLineNumber, setStackFrameMap, setSystemId`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### evaluationMode

          protected int evaluationMode

  - ### Constructor Detail

    - #### UserFunction

          public UserFunction()

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

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

    - #### getFunctionType

          public FunctionItemType getFunctionType()

      Get the type of the function
      Returns:
        the function type

    - #### asCallable

          public Callable asCallable()

    - #### setAnnotationMap

          public void setAnnotationMap(Map<StructuredQName,Annotation> map)

      Supply a set of annotations
      Parameters:
        `map` - the new set of annotations, which will replace any previous annotations on the function

    - #### computeEvaluationMode

          public void computeEvaluationMode()

      Determine the preferred evaluation mode for this function

    - #### isInlineable

          public Boolean isInlineable()

      Ask whether the function can be inlined
      Returns:
        true (yes), false (no), or null (don't know)

    - #### setInlineable

          public void setInlineable(boolean inlineable)

      Say whether this function can be inlined
      Parameters:
        `inlineable` - true or false

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

    - #### getDeclaredResultType

          public SequenceType getDeclaredResultType()

      Get the declared result type
      Returns:
        the declared result type

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

    - #### isMemoFunction

          public boolean isMemoFunction()

      Ask whether this function is a memo function
      Returns:
        false (overridden in a subclass)

    - #### call

          public Sequence call(XPathContextMajor context,
                      Sequence[] actualArgs)
                        throws XPathException

      Call this function to return a value.
      Parameters:
        `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.
      Returns:
        a Value representing the result of the function.
      Throws:
        `XPathException` - if a dynamic error occurs while evaluating the function

    - #### process

          public void process(Sequence[] 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.
      Throws:
        `XPathException` - if a dynamic error occurs while evaluating the function

    - #### iterateEvents

          public EventIterator iterateEvents(Sequence[] 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
      Throws:
        `XPathException` - if a dynamic error occurs while evaluating the function

    - #### call

          public Sequence call(Sequence[] 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.
      Throws:
        `XPathException` - if a dynamic error occurs while evaluating the function.

    - #### callUpdating

          public void callUpdating(Sequence[] 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 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.
      Throws:
        `XPathException` - if a dynamic error occurs while evaluating the function.

    - #### 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`.
      Returns:
        an integer identifying the kind of construct

Copyright (c) 2004-2013 Saxonica Limited. All rights reserved.