Package net.sf.saxon.query

## Class DynamicQueryContext

- java.lang.Object
- - net.sf.saxon.query.DynamicQueryContext

-     public class DynamicQueryContext
      extends java.lang.Object

  This object represents a dynamic context for query execution. This class is used by the application writer to set up aspects of the dynamic context; it is not used operationally (or modified) by the XQuery processor itself, which copies all required information into its own internal representation.

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `DynamicQueryContext​(Configuration config)` | Create the dynamic context for a query

  - ### Method Summary

    All Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `clearParameters()` | Reset the parameters to an empty list.
    `Configuration` | `getConfiguration()` | Get the Configuration associated with this dynamic query context
    `Item` | `getContextItem()` | Get the context item for the query, as set using setContextItem().
    `DateTimeValue` | `getCurrentDateTime()` | Get the date and time set previously using `setCurrentDateTime(net.sf.saxon.value.DateTimeValue)` or null if none has been set.
    `javax.xml.transform.ErrorListener` | `getErrorListener()` | Deprecated. since 10.0.
    `ErrorReporter` | `getErrorReporter()` | Get the callback that will be used when reporting a dynamic error or warning
    `GroundedValue` | `getParameter​(StructuredQName expandedName)` | Get the actual value of a parameter to the query.
    `GlobalParameterSet` | `getParameters()` | Get all the supplied parameters.
    `int` | `getSchemaValidationMode()` | Ask whether source documents loaded using the doc(), document(), and collection() functions, or supplied as a StreamSource or SAXSource to the transform() or addParameter() method should be subjected to schema validation
    `Logger` | `getTraceFunctionDestination()` | Get the destination for output from the fn:trace() function.
    `TraceListener` | `getTraceListener()` | Get the trace listener.
    `UnparsedTextURIResolver` | `getUnparsedTextURIResolver()` | Get the URI resolver for unparsed text.
    `javax.xml.transform.URIResolver` | `getURIResolver()` | Get the URI resolver.
    `void` | `initializeController​(Controller controller)` | Apply the settings from this DynamicQueryContext to a Controller
    `boolean` | `isApplyFunctionConversionRulesToExternalVariables()` | Ask whether the function conversion rules should be applied to supplied parameter values.
    `void` | `setApplyFunctionConversionRulesToExternalVariables​(boolean convert)` | Say whether the function conversion rules should be applied to supplied parameter values.
    `void` | `setContextItem​(Item item)` | Set the context item for evaluating the expression.
    `void` | `setCurrentDateTime​(DateTimeValue dateTime)` | Set a value to be used as the current date and time for the query.
    `void` | `setErrorListener​(javax.xml.transform.ErrorListener listener)` | Deprecated. since 10.0.
    `void` | `setErrorReporter​(ErrorReporter reporter)` | Set a callback that will be used when reporting a dynamic error or warning
    `void` | `setParameter​(StructuredQName expandedName, GroundedValue value)` | Set a parameter for the query.
    `void` | `setSchemaValidationMode​(int validationMode)` | Say whether source documents loaded using the doc(), document(), and collection() functions, or supplied as a StreamSource or SAXSource to the transform() or addParameter() method, should be subjected to schema validation.
    `void` | `setTraceFunctionDestination​(Logger stream)` | Set the destination for output from the fn:trace() function.
    `void` | `setTraceListener​(TraceListener listener)` | Set the trace listener.
    `void` | `setUnparsedTextURIResolver​(UnparsedTextURIResolver resolver)` | Set an object that will be used to resolve URIs used in fn:unparsed-text() and related functions.
    `void` | `setURIResolver​(javax.xml.transform.URIResolver resolver)` | Set an object that will be used to resolve URIs used in fn:document() and related functions.

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

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

- - ### Constructor Detail

    - #### DynamicQueryContext

          public DynamicQueryContext​(Configuration config)

      Create the dynamic context for a query
      Parameters:
        `config` - the Saxon configuration
      Since:
        8.4.

  - ### Method Detail

    - #### getSchemaValidationMode

          public int getSchemaValidationMode()

      Ask whether source documents loaded using the doc(), document(), and collection() functions, or supplied as a StreamSource or SAXSource to the transform() or addParameter() method should be subjected to schema validation
      Returns:
        the schema validation mode previously set using setSchemaValidationMode(), or the default mode `Validation.DEFAULT` otherwise.

    - #### setSchemaValidationMode

          public void setSchemaValidationMode​(int validationMode)

      Say whether source documents loaded using the doc(), document(), and collection() functions, or supplied as a StreamSource or SAXSource to the transform() or addParameter() method, should be subjected to schema validation. The default value is taken from the corresponding property of the Configuration.
      Parameters:
        `validationMode` - the validation (or construction) mode to be used for source documents. One of `Validation.STRIP`, `Validation.PRESERVE`, `Validation.STRICT`, `Validation.LAX`
      Since:
        9.2

    - #### setApplyFunctionConversionRulesToExternalVariables

          public void setApplyFunctionConversionRulesToExternalVariables​(boolean convert)

      Say whether the function conversion rules should be applied to supplied parameter values. For example, this allows an integer to be supplied as the value for a parameter where the expected type is xs:double. The default is true. The value "false" is allowed because XQJ requires that no conversion is attempted.
      Parameters:
        `convert` - true if function conversion rules are to be applied to supplied values; if false, the supplied value must match the required type exactly.
      Since:
        9.3

    - #### isApplyFunctionConversionRulesToExternalVariables

          public boolean isApplyFunctionConversionRulesToExternalVariables()

      Ask whether the function conversion rules should be applied to supplied parameter values. For example, this allows an integer to be supplied as the value for a parameter where the expected type is xs:double. The default is true.
      Returns:
        true if function conversion rules are to be applied to supplied values; if false, the supplied value must match the required type exactly.
      Since:
        9.3

    - #### setContextItem

          public void setContextItem​(Item item)

      Set the context item for evaluating the expression. If this method is not called, the context node will be undefined. The context item is available as the value of the expression ".". To obtain a node by parsing a source document, see the method `Configuration.buildDocumentTree(javax.xml.transform.Source)` in the Configuration class.
      Parameters:
        `item` - The item that is to be the context item for the query
      Throws:
        `java.lang.IllegalArgumentException` - if the supplied item is a node that was built under the wrong Saxon Configuration
        `java.lang.NullPointerException` - if the supplied item is null
      Since:
        8.4

    - #### getContextItem

          public Item getContextItem()

      Get the context item for the query, as set using setContextItem().
      Returns:
        the context item if set, or null otherwise.
      Since:
        8.4

    - #### setParameter

          public void setParameter​(StructuredQName expandedName,
                                   GroundedValue value)

      Set a parameter for the query.
      Parameters:
        `expandedName` - The name of the parameter. It is not an error to supply a value for a parameter that has not been declared, the parameter will simply be ignored. If the parameter has been declared in the query (as an external global variable) then it will be initialized with the value supplied.
        `value` - The value of the parameter.
      Since:
        8.4. Changed in 9.6 (a) to require a Sequence value, thus making the alternative method setParameterValue redundant, and (b) to accept the name as a StructuredQName Changed in 9.9 to require the second argument to be a GroundedValue

    - #### clearParameters

          public void clearParameters()

      Reset the parameters to an empty list.

    - #### getParameter

          public GroundedValue getParameter​(StructuredQName expandedName)

      Get the actual value of a parameter to the query.
      Parameters:
        `expandedName` - the name of the required parameter
      Returns:
        the value of the parameter, if it exists, or null otherwise
      Since:
        8.4. Changed in 9.6 to take a StructuredQName for the name. Changed in 9.9.1.1 to return a generified GroundedValue.

    - #### getParameters

          public GlobalParameterSet getParameters()

      Get all the supplied parameters.
      Returns:
        a structure containing all the parameters

    - #### setURIResolver

          public void setURIResolver​(javax.xml.transform.URIResolver resolver)

      Set an object that will be used to resolve URIs used in fn:document() and related functions.
      Parameters:
        `resolver` - An object that implements the URIResolver interface, or null.
      Since:
        8.4

    - #### getURIResolver

          public javax.xml.transform.URIResolver getURIResolver()

      Get the URI resolver.
      Returns:
        the user-supplied URI resolver if there is one, or the system-defined one otherwise
      Since:
        8.4

    - #### setUnparsedTextURIResolver

          public void setUnparsedTextURIResolver​(UnparsedTextURIResolver resolver)

      Set an object that will be used to resolve URIs used in fn:unparsed-text() and related functions.
      Parameters:
        `resolver` - An object that implements the UnparsedTextURIResolver interface, or null.
      Since:
        9.5

    - #### getUnparsedTextURIResolver

          public UnparsedTextURIResolver getUnparsedTextURIResolver()

      Get the URI resolver for unparsed text.
      Returns:
        the user-supplied unparsed text URI resolver if there is one, or the system-defined one otherwise
      Since:
        8.4

    - #### setErrorListener

          public void setErrorListener​(javax.xml.transform.ErrorListener listener)

      Deprecated.
      since 10.0. Use `setErrorReporter(net.sf.saxon.lib.ErrorReporter)`
      Set the error listener. The error listener receives reports of all run-time errors and can decide how to report them.
      Parameters:
        `listener` - the ErrorListener to be used
      Since:
        8.4

    - #### getErrorListener

          public javax.xml.transform.ErrorListener getErrorListener()

      Deprecated.
      since 10.0. Use `setErrorReporter(net.sf.saxon.lib.ErrorReporter)`
      Get the error listener.
      Returns:
        the ErrorListener in use
      Since:
        8.4

    - #### setErrorReporter

          public void setErrorReporter​(ErrorReporter reporter)

      Set a callback that will be used when reporting a dynamic error or warning
      Since:
        10.0

    - #### getErrorReporter

          public ErrorReporter getErrorReporter()

      Get the callback that will be used when reporting a dynamic error or warning
      Since:
        10.0

    - #### setTraceListener

          public void setTraceListener​(TraceListener listener)

      Set the trace listener. The trace listener receives reports of all run-time expression evaluation.
      Parameters:
        `listener` - the TraceListener to be used
      Since:
        9.0

    - #### getTraceListener

          public TraceListener getTraceListener()

      Get the trace listener.
      Returns:
        the TraceListener in use, or null if none is in use
      Since:
        9.0

    - #### setTraceFunctionDestination

          public void setTraceFunctionDestination​(Logger stream)

      Set the destination for output from the fn:trace() function. By default, the destination is System.err. If a TraceListener is in use, this is ignored, and the trace() output is sent to the TraceListener.
      Parameters:
        `stream` - the PrintStream to which trace output will be sent. If set to null, trace output is suppressed entirely. It is the caller's responsibility to close the stream after use.
      Since:
        9.1. Changed in 9.6 to use a Logger.

    - #### getTraceFunctionDestination

          public Logger getTraceFunctionDestination()

      Get the destination for output from the fn:trace() function.
      Returns:
        the PrintStream to which trace output will be sent. If no explicitly destination has been set, returns System.err. If the destination has been set to null to suppress trace output, returns null.
      Since:
        9.1. Changed in 9.6 to use a Logger

    - #### getCurrentDateTime

          public DateTimeValue getCurrentDateTime()

      Get the date and time set previously using `setCurrentDateTime(net.sf.saxon.value.DateTimeValue)` or null if none has been set.
      Returns:
        the current date and time, if it has been set.
      Since:
        8.5

    - #### setCurrentDateTime

          public void setCurrentDateTime​(DateTimeValue dateTime)
                                  throws XPathException

      Set a value to be used as the current date and time for the query. By default, the "real" current date and time are used. The main purpose of this method is that it allows repeatable results to be achieved when testing queries.

      This method also has the effect of setting the implicit timezone.

      Parameters:
        `dateTime` - The value to be used as the current date and time. This must include a timezone. The timezone from this value will also be used as the implicit timezone
      Throws:
        `XPathException` - if the dateTime does not include a timezone
      Since:
        8.5

    - #### getConfiguration

          public Configuration getConfiguration()

      Get the Configuration associated with this dynamic query context
      Returns:
        the Configuration
      Since:
        8.8

    - #### initializeController

          public void initializeController​(Controller controller)
                                    throws XPathException

      Apply the settings from this DynamicQueryContext to a Controller
      Parameters:
        `controller` - the Controller whose settings are to be initialized
      Throws:
        `XPathException`