javax.xml.xquery

## Interface XQStaticContext

- All Known Implementing Classes:
    SaxonXQStaticContext

      public interface XQStaticContext

  An `XQStaticContext` represents default values for various XQuery Static Context Components. Further it includes the static XQJ properties for an `XQExpression` or `XQPreparedExpression` object.

  The following XQuery Static Context Components are supported through the `XQStaticContext` interface:

  - Statically known namespaces
  - Default element/type namespace
  - Default function namespace
  - Context item static type
  - Default collation
  - Construction mode
  - Ordering mode
  - Default order for empty sequences
  - Boundary-space policy
  - Copy-namespaces mode
  - Base URI
  As described in the XQuery specification, each of these default values can be overridden or augmented in the query prolog.

  In addition `XQStaticContext` includes the static XQJ properties for an `XQExpression` or `XQPreparedExpression` object:

  - Binding mode
  - Holdability of the result sequences
  - Scrollability of the result sequences
  - Query language
  - Query timeout

  Note that `XQStaticContext` is a value object, changing attributes in such object doesn't affect any existing `XQExpression` or `XQPreparedExpression` object.
  In order to take effect, the application needs to explicitly change the `XQConnection` default values, or specify an `XQStaticContext` object when creating an `XQExpression` or `XQPreparedExpression`.

        XQConnection conn = XQDatasource.getConnection();
        // get the default values from the implementation
        XQStaticContext cntxt = conn.getStaticContext();
        // change the base uri
        cntxt.setBaseURI("http://www.foo.com/xml/");
        // change the implementation defaults
         conn.setStaticContext(cntxt);

        // create an XQExpression using the new defaults
        XQExpression expr1 = conn.createExpression();

        // creat an XQExpression, using BaseURI "file:///root/user/john/"
        cntxt.setBaseURI("file:///root/user/john/");
        XQExpression expr2 = conn.createExpression(cntxt);
        ...

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `declareNamespace(String prefix, String uri)` Declares a namespace prefix and associates it with a namespace URI.
    `String` | `getBaseURI()` Gets the Base URI, if set in the static context, else the empty string.
    `int` | `getBindingMode()` Gets the value of the binding mode property.
    `int` | `getBoundarySpacePolicy()` Gets the boundary-space policy defined in the static context.
    `int` | `getConstructionMode()` Gets the construction mode defined in the static context.
    `XQItemType` | `getContextItemStaticType()` Gets the static type of the context item.
    `int` | `getCopyNamespacesModeInherit()` Gets the inherit part of the copy-namespaces mode defined in the static context.
    `int` | `getCopyNamespacesModePreserve()` Gets the preserve part of the copy-namespaces mode defined in the static context.
    `String` | `getDefaultCollation()` Gets the URI of the default collation.
    `String` | `getDefaultElementTypeNamespace()` Gets the URI of the default element/type namespace, the empty string if not set.
    `String` | `getDefaultFunctionNamespace()` Gets the URI of the default function namespace, the empty string if not set.
    `int` | `getDefaultOrderForEmptySequences()` Gets the default order for empty sequences defined in the static context.
    `int` | `getHoldability()` Gets the value of the holdability property.
    `String[]` | `getNamespacePrefixes()` Returns the prefixes of all the statically known namespaces.
    `String` | `getNamespaceURI(String prefix)` Retrieves the namespace URI associated with a prefix.
    `int` | `getOrderingMode()` Gets the ordering mode defined in the static context.
    `int` | `getQueryLanguageTypeAndVersion()` Gets the value of the language type and version property.
    `int` | `getQueryTimeout()` Retrieves the number of seconds an implementation will wait for a query to execute.
    `int` | `getScrollability()` Gets the value of the scrollability property.
    `void` | `setBaseURI(String baseUri)` Sets the Base URI in the static context, specify the empty string to make it undefined.
    `void` | `setBindingMode(int bindingMode)` Sets the binding mode property.
    `void` | `setBoundarySpacePolicy(int policy)` Sets the boundary-space policy in the static context.
    `void` | `setConstructionMode(int mode)` Sets the construction mode in the static context.
    `void` | `setContextItemStaticType(XQItemType contextItemType)` Sets the static type of the context item, specify `null` to make it unspecified.
    `void` | `setCopyNamespacesModeInherit(int mode)` Sets the inherit part of the copy-namespaces mode in the static context.
    `void` | `setCopyNamespacesModePreserve(int mode)` Sets the preserve part of the copy-namespaces mode in the static context.
    `void` | `setDefaultCollation(String uri)` Sets the URI of the default collation.
    `void` | `setDefaultElementTypeNamespace(String uri)` Sets the URI of the default element/type namespace, the empty string to make it unspecified.
    `void` | `setDefaultFunctionNamespace(String uri)` Sets the URI of the default function namespace, the empty string to make it unspecified.
    `void` | `setDefaultOrderForEmptySequences(int order)` Sets the default order for empty sequences in the static context.
    `void` | `setHoldability(int holdability)` Sets the holdability property.
    `void` | `setOrderingMode(int mode)` Sets the ordering mode in the static context.
    `void` | `setQueryLanguageTypeAndVersion(int langType)` Sets the input query language type and version.
    `void` | `setQueryTimeout(int seconds)` Sets the number of seconds an implementation will wait for a query to execute.
    `void` | `setScrollability(int scrollability)` Sets the scrollability of the result sequence.

- - ### Method Detail

    - #### getNamespacePrefixes

          String[] getNamespacePrefixes()

      Returns the prefixes of all the statically known namespaces. Use the `getNamespaceURI` method to look up the namespace URI corresponding to a specific prefix.
      Returns:
        `String` array containing the namespace prefixes. Cannot be `null`

    - #### getNamespaceURI

          String getNamespaceURI(String prefix)
                                 throws XQException

      Retrieves the namespace URI associated with a prefix. An `XQException` is thrown if an unknown prefix is specified, i.e. a prefix not returned by the `getInScopeNamespacePrefixes` method.
      Parameters:
        `prefix` - the prefix for which the namespace URI is sought. Cannot be `null`
      Returns:
        the namespace URI. Cannot be `null`
      Throws:
        `XQException` - if a `null` prefix is specified or if the prefix is unknown

    - #### declareNamespace

          void declareNamespace(String prefix,
                              String uri)
                                throws XQException

      Declares a namespace prefix and associates it with a namespace URI. If the namespace URI is the empty string, the prefix is removed from the in-scope namespace definitions.
      Parameters:
        `prefix` - the prefix for the namespace URI
        `uri` - the namespace URI. An empty string undeclares the specific prefix. Cannot be `null`
      Throws:
        `XQException` - if (1) a `null` prefix, or (2) a `null` namespace URI is specified

    - #### getDefaultElementTypeNamespace

          String getDefaultElementTypeNamespace()

      Gets the URI of the default element/type namespace, the empty string if not set.
      Returns:
        the URI of the default element/type namespace, if set, else the empty string. Cannot be `null`

    - #### setDefaultElementTypeNamespace

          void setDefaultElementTypeNamespace(String uri)
                                              throws XQException

      Sets the URI of the default element/type namespace, the empty string to make it unspecified.
      Parameters:
        `uri` - the namespace URI of the default element/type namespace, the empty string to make it unspecified. Cannot be `null`.
      Throws:
        `XQException` - if a `null` uri is specified

    - #### getDefaultFunctionNamespace

          String getDefaultFunctionNamespace()

      Gets the URI of the default function namespace, the empty string if not set.
      Returns:
        the URI of the default function namespace, if set, else the empty string. Cannot be `null`

    - #### setDefaultFunctionNamespace

          void setDefaultFunctionNamespace(String uri)
                                           throws XQException

      Sets the URI of the default function namespace, the empty string to make it unspecified.
      Parameters:
        `uri` - the namespace URI of the default function namespace, the empty string to make it unspecified. Cannot be `null`.
      Throws:
        `XQException` - if a `null` URI is specified

    - #### getContextItemStaticType

          XQItemType getContextItemStaticType()

      Gets the static type of the context item. `null` if unspecified.
      Returns:
        the static type of the context item, if set, else `null`

    - #### setContextItemStaticType

          void setContextItemStaticType(XQItemType contextItemType)
                                        throws XQException

      Sets the static type of the context item, specify `null` to make it unspecified.
      Parameters:
        `contextItemType` - the static type of the context item; `null` if unspecified.
      Throws:
        `XQException` - if the `contextItemType` is not a valid `XQItemType`

    - #### getDefaultCollation

          String getDefaultCollation()

      Gets the URI of the default collation.
      Returns:
        the URI of the default collation. Cannot be `null`.

    - #### setDefaultCollation

          void setDefaultCollation(String uri)
                                   throws XQException

      Sets the URI of the default collation.
      Parameters:
        `uri` - the namespace URI of the default collation. Cannot be `null`.
      Throws:
        `XQException` - if a `null` URI is specified

    - #### getConstructionMode

          int getConstructionMode()

      Gets the construction mode defined in the static context.
      Returns:
        construction mode value. One of: `XQConstants.CONSTRUCTION_MODE_PRESERVE`, `XQConstants.CONSTRUCTION_MODE_STRIP`

    - #### setConstructionMode

          void setConstructionMode(int mode)
                                   throws XQException

      Sets the construction mode in the static context.
      Parameters:
        `mode` - construction mode value. One of: `XQConstants.CONSTRUCTION_MODE_PRESERVE`, `XQConstants.CONSTRUCTION_MODE_STRIP`.
      Throws:
        `XQException` - the specified mode is different from `XQConstants.CONSTRUCTION_MODE_PRESERVE`, `XQConstants.CONSTRUCTION_MODE_STRIP`

    - #### getOrderingMode

          int getOrderingMode()

      Gets the ordering mode defined in the static context.
      Returns:
        ordering mode value. One of: `XQConstants.ORDERING_MODE_ORDERED`, `XQConstants.ORDERING_MODE_UNORDERED`.

    - #### setOrderingMode

          void setOrderingMode(int mode)
                               throws XQException

      Sets the ordering mode in the static context.
      Parameters:
        `mode` - ordering mode value. One of: `XQConstants.ORDERING_MODE_ORDERED`, `XQConstants.ORDERING_MODE_UNORDERED`.
      Throws:
        `XQException` - the specified mode is different from `XQConstants.ORDERING_MODE_ORDERED`, `XQConstants.ORDERING_MODE_UNORDERED`

    - #### getDefaultOrderForEmptySequences

          int getDefaultOrderForEmptySequences()

      Gets the default order for empty sequences defined in the static context.
      Returns:
        default order for empty sequences value. One of: `XQConstants.DEFAULT_ORDER_FOR_EMPTY_SEQUENCES_GREATEST`, `XQConstants.DEFAULT_ORDER_FOR_EMPTY_SEQUENCES_LEAST`.

    - #### setDefaultOrderForEmptySequences

          void setDefaultOrderForEmptySequences(int order)
                                                throws XQException

      Sets the default order for empty sequences in the static context.
      Parameters:
        `order` - the default order for empty sequences. One of: `XQConstants.DEFAULT_ORDER_FOR_EMPTY_SEQUENCES_GREATEST`, `XQConstants.DEFAULT_ORDER_FOR_EMPTY_SEQUENCES_LEAST`.
      Throws:
        `XQException` - the specified order for empty sequences is different from `XQConstants.DEFAULT_ORDER_FOR_EMPTY_SEQUENCES_GREATEST`, `XQConstants.DEFAULT_ORDER_FOR_EMPTY_SEQUENCES_LEAST`

    - #### getBoundarySpacePolicy

          int getBoundarySpacePolicy()

      Gets the boundary-space policy defined in the static context.
      Returns:
        the boundary-space policy value. One of: `XQConstants.BOUNDARY_SPACE_PRESERVE`, `XQConstants.BOUNDARY_SPACE_STRIP`.

    - #### setBoundarySpacePolicy

          void setBoundarySpacePolicy(int policy)
                                      throws XQException

      Sets the boundary-space policy in the static context.
      Parameters:
        `policy` - boundary space policy. One of: `XQConstants.BOUNDARY_SPACE_PRESERVE`, `XQConstants.BOUNDARY_SPACE_STRIP`.
      Throws:
        `XQException` - the specified mode is different from `XQConstants.BOUNDARY_SPACE_PRESERVE`, `XQConstants.BOUNDARY_SPACE_STRIP`

    - #### getCopyNamespacesModePreserve

          int getCopyNamespacesModePreserve()

      Gets the preserve part of the copy-namespaces mode defined in the static context.
      Returns:
        construction mode value. One of: `XQConstants.COPY_NAMESPACES_MODE_PRESERVE`, `XQConstants.COPY_NAMESPACES_MODE_NO_PRESERVE`.

    - #### setCopyNamespacesModePreserve

          void setCopyNamespacesModePreserve(int mode)
                                             throws XQException

      Sets the preserve part of the copy-namespaces mode in the static context.
      Parameters:
        `mode` - ordering mode value. One of: `XQConstants.COPY_NAMESPACES_MODE_PRESERVE`, `XQConstants.COPY_NAMESPACES_MODE_NO_PRESERVE`.
      Throws:
        `XQException` - the specified mode is different from `XQConstants.COPY_NAMESPACES_MODE_PRESERVE`, `XQConstants.COPY_NAMESPACES_MODE_NO_PRESERVE`

    - #### getCopyNamespacesModeInherit

          int getCopyNamespacesModeInherit()

      Gets the inherit part of the copy-namespaces mode defined in the static context.
      Returns:
        construction mode value. One of: `XQConstants.COPY_NAMESPACES_MODE_INHERIT`, `XQConstants.COPY_NAMESPACES_MODE_NO_INHERIT`.

    - #### setCopyNamespacesModeInherit

          void setCopyNamespacesModeInherit(int mode)
                                            throws XQException

      Sets the inherit part of the copy-namespaces mode in the static context.
      Parameters:
        `mode` - ordering mode value. One of: `XQConstants.COPY_NAMESPACES_MODE_INHERIT`, `XQConstants.COPY_NAMESPACES_MODE_NO_INHERIT`.
      Throws:
        `XQException` - the specified mode is different from `XQConstants.COPY_NAMESPACES_MODE_INHERIT`, `XQConstants.COPY_NAMESPACES_MODE_NO_INHERIT`

    - #### getBaseURI

          String getBaseURI()

      Gets the Base URI, if set in the static context, else the empty string.
      Returns:
        the base URI, if set, else the empty string. Cannot be `null`..

    - #### setBaseURI

          void setBaseURI(String baseUri)
                          throws XQException

      Sets the Base URI in the static context, specify the empty string to make it undefined.
      Parameters:
        `baseUri` - the new baseUri, or empty string to make it undefined. Cannot be `null`.
      Throws:
        `XQException` - if a `null` base uri is specified

    - #### getBindingMode

          int getBindingMode()

      Gets the value of the binding mode property. By default an XQJ implementation operates in immediate binding mode.
      Returns:
        the binding mode. One of `XQConstants.BINDING_MODE_IMMEDIATE`, or`XQConstants.BINDING_MODE_DEFERRED`.

    - #### setBindingMode

          void setBindingMode(int bindingMode)
                              throws XQException

      Sets the binding mode property. By default an XQJ implementation operates in immediate binding mode.
      Parameters:
        `bindingMode` - the binding mode. One of: `XQConstants.BINDING_MODE_IMMEDIATE`, or`XQConstants.BINDING_MODE_DEFERRED`.
      Throws:
        `XQException` - the specified mode is different from `XQConstants.BINDING_MODE_IMMEDIATE`, `XQConstants.BINDING_MODE_DEFERRED`

    - #### getHoldability

          int getHoldability()

      Gets the value of the holdability property.
      Returns:
        the type of a result's holdability. One of: `XQConstants.HOLDTYPE_HOLD_CURSORS_OVER_COMMIT`, or `XQConstants.HOLDTYPE_CLOSE_CURSORS_AT_COMMIT`.

    - #### setHoldability

          void setHoldability(int holdability)
                              throws XQException

      Sets the holdability property.
      Parameters:
        `holdability` - the holdability of the result. One of: `XQConstants.HOLDTYPE_HOLD_CURSORS_OVER_COMMIT`, or `XQConstants.HOLDTYPE_CLOSE_CURSORS_AT_COMMIT`.
      Throws:
        `XQException` - the specified holdability is different from `XQConstants.HOLDTYPE_HOLD_CURSORS_OVER_COMMIT`, `XQConstants.HOLDTYPE_CLOSE_CURSORS_AT_COMMIT`

    - #### getQueryLanguageTypeAndVersion

          int getQueryLanguageTypeAndVersion()

      Gets the value of the language type and version property. By default an XQJ implementation's default is `XQConstants.LANGTYPE_XQUERY`.
      Returns:
        the language type and version. One of: `XQConstants.LANGTYPE_XQUERY`, or `XQConstants.LANGTYPE_XQUERYX` or a negative value indicating a vendor specific query language type and version.

    - #### setQueryLanguageTypeAndVersion

          void setQueryLanguageTypeAndVersion(int langType)
                                              throws XQException

      Sets the input query language type and version. When this is set to a particular language type and version, then the query is assumed to be in that language and version.
      Parameters:
        `langType` - the query language type and version of the inputs. One of: `XQConstants.LANGTYPE_XQUERY` (default), or `XQConstants.LANGTYPE_XQUERYX`. A negative number indicates a vendor specific query language type and version.
      Throws:
        `XQException` - the specified langtype is different from `XQConstants.LANGTYPE_XQUERY`, `XQConstants.LANGTYPE_XQUERYX` and is not negative

    - #### getScrollability

          int getScrollability()

      Gets the value of the scrollability property. By default query results are forward only.
      Returns:
        the type of a result's scrollability. One of: `XQConstants.SCROLLTYPE_FORWARD_ONLY`, or `XQConstants.SCROLLTYPE_SCROLLABLE`.

    - #### setScrollability

          void setScrollability(int scrollability)
                                throws XQException

      Sets the scrollability of the result sequence. By default query results are forward only.
      Parameters:
        `scrollability` - the scrollability of the result. One of: `XQConstants.SCROLLTYPE_FORWARD_ONLY`, or `XQConstants.SCROLLTYPE_SCROLLABLE`.
      Throws:
        `XQException` - the specified crollability type is different from `XQConstants.SCROLLTYPE_FORWARD_ONLY`, `XQConstants.SCROLLTYPE_SCROLLABLE`

    - #### getQueryTimeout

          int getQueryTimeout()

      Retrieves the number of seconds an implementation will wait for a query to execute.
      Returns:
        the query execution timeout value in seconds. A value of 0 indicates no limit.

    - #### setQueryTimeout

          void setQueryTimeout(int seconds)
                               throws XQException

      Sets the number of seconds an implementation will wait for a query to execute. If the implementation does not support query timeout it can ignore the specified timeout value. It the limit is exceeded, the behavor of the query is the same as an execution of a cancel by another thread.
      Parameters:
        `seconds` - the query execution timeout value in seconds. A value of 0 indicates no limit
      Throws:
        `XQException` - if the passed in value is negative

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