Package 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 Detail

      • getNamespacePrefixes

        java.lang.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

        java.lang.String getNamespaceURI​(java.lang.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​(java.lang.String prefix,
                      java.lang.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

        java.lang.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​(java.lang.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

        java.lang.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​(java.lang.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

        java.lang.String getDefaultCollation()
        Gets the URI of the default collation.
        Returns:
        the URI of the default collation. Cannot be null.

      • setDefaultCollation

        void setDefaultCollation​(java.lang.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

        java.lang.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​(java.lang.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, orXQConstants.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, orXQConstants.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