oracle.xml.xquery

## Interface OXQDynamicContext

All Known Subinterfaces:
  OXQExpression, OXQPreparedExpression

    public interface OXQDynamicContext

Extensions to `javax.xml.xquery.XQDynamicContext`.

Use method `OXQView.getDynamicContext(XQDynamicContext)` to obtain access to these extensions. For example:

     OXQDataSource ds = new OXQDataSource();
     XQConnection con = ds.getConnection();
     XQPreparedExpression expr = con.prepareExpression(query);
     OXQDynamicContext octx = OXQView.getDynamicContext(expr);
     ...

Since:
  12.1

### Method Summary

All Methods Instance Methods Abstract Methods
`void` `bindBigDecimal(javax.xml.namespace.QName varName, java.math.BigDecimal value, XQItemType type)` Binds a value to the given external variable or the context item.
`void` `bindBigInteger(javax.xml.namespace.QName varName, java.math.BigInteger value, XQItemType type)` Binds a value to the given external variable or the context item.
`void` `bindBinary(javax.xml.namespace.QName varName, byte[] value, XQItemType type)` Binds a value to the given external variable or the context item.
`void` `bindCalendar(javax.xml.namespace.QName varName, javax.xml.datatype.XMLGregorianCalendar value, XQItemType type)` Binds a value to the given external variable or the context item.
`void` `bindDocument(javax.xml.namespace.QName varName, OXQEntity value, XQItemType type)` Binds a value to the given external variable or the context item.
`void` `bindDuration(javax.xml.namespace.QName varName, javax.xml.datatype.Duration value, XQItemType type)` Binds a value to the given external variable or the context item.
`void` `bindQName(javax.xml.namespace.QName varName, javax.xml.namespace.QName value, XQItemType type)` Binds a value to the given external variable or the context item.
`XQConnection` `getConnection()` Gets the XQuery connection associated with this dynamic context.
`OXQDebugListener` `getDebugListener()` Gets the debug listener.
`java.lang.String` `getDefaultCollection()` Gets the default collection that will be used when `fn:collection` is invoked with no arguments.
`java.lang.String` `getDefaultResourceCollection()` Gets the default resource collection that will be used when `fn:uri-collection` is invoked with no arguments.
`PageManager` `getPageManager()` Gets the `PageManager`.
`int` `getUpdateMode()` Gets the default update mode.
`java.lang.Object` `getUserExtension()` Returns the user extension.
`XQDynamicContext` `getXQView()` Returns the `XQDynamicContext` instance corresponding to this instance.
`void` `setDebugListener(OXQDebugListener listener)` Sets the debug listener.
`void` `setDefaultCollection(java.lang.String uri)` Sets the default collection that will be used when `fn:collection` is invoked with no arguments.
`void` `setDefaultResourceCollection(java.lang.String uri)` Sets the default resource collection that will be used when `fn:uri-collection` is invoked with no arguments.
`void` `setPageManager(PageManager pageManager)` Sets the `PageManager`.
`void` `setUpdateMode(int mode)` Sets the update mode.
`void` `setUserExtension(java.lang.Object extension)` Sets the user extension.
`void` `unbindAllExternalVariablesAndContextItem()` Unbinds all external variables and context item.

### Method Detail

#### getXQView

    XQDynamicContext getXQView()

Returns the `XQDynamicContext` instance corresponding to this instance.

Returns:
  the dynamic context

#### getConnection

    XQConnection getConnection()
                        throws XQException

Gets the XQuery connection associated with this dynamic context.

Returns:
  the connection associated with this dynamic context
Throws:
  `XQException` - if the context is in a closed state

#### setDefaultCollection

    void setDefaultCollection(java.lang.String uri)
                       throws XQException

Sets the default collection that will be used when `fn:collection` is invoked with no arguments.

Parameters:
  `uri` - the absolute URI of the default collection
Throws:
  `XQException` - if the URI is not absolute or if the context is in a closed state

#### setDefaultResourceCollection

    void setDefaultResourceCollection(java.lang.String uri)
                               throws XQException

Sets the default resource collection that will be used when `fn:uri-collection` is invoked with no arguments.

Parameters:
  `uri` - the URI of the default resource collection
Throws:
  `XQException`

#### getDefaultCollection

    java.lang.String getDefaultCollection()
                                   throws XQException

Gets the default collection that will be used when `fn:collection` is invoked with no arguments.

Returns:
  the URI of the default collection
Throws:
  `XQException`

#### getDefaultResourceCollection

    java.lang.String getDefaultResourceCollection()
                                           throws XQException

Gets the default resource collection that will be used when `fn:uri-collection` is invoked with no arguments.

Returns:
  the URI of the default resource collection
Throws:
  `XQException`

#### setUserExtension

    void setUserExtension(java.lang.Object extension)
                   throws XQException

Sets the user extension. Allows custom data to be stored in the dynamic context and serves as a way to provide state to external function implementations. This data can be retrieved by an implementation of `OXQFunctionEvaluator`.

Parameters:
  `extension` - the user extension
Throws:
  `XQException`

#### getUserExtension

    java.lang.Object getUserExtension()
                               throws XQException

Returns the user extension.

Returns:
  the user extension
Throws:
  `XQException`

#### bindDocument

    void bindDocument(javax.xml.namespace.QName varName,
                      OXQEntity value,
                      XQItemType type)
               throws XQException

Binds a value to the given external variable or the context item.

If the value represents a well-formed XML document, it results in a document node. The kind of the input type must be `null`, `XQItemType.XQITEMKIND_DOCUMENT_ELEMENT` or `XQItemType.XQITEMKIND_DOCUMENT_SCHEMA_ELEMENT`.

Parameters:
  `varName` - the name of the external variable to bind to, cannot be `null`
  `value` - the value to be converted, cannot be `null`. The entity must conform to the `OXQEntity` contract for `DOCUMENT` entities.
  `type` - the type of the value for the created document node. If `null` is specified, it behaves as if `XQDataFactory.createDocumentElementType( XQDataFactory.createElementType(null, XQItemType.XQBASETYPE_XS_UNTYPED))` were passed in as the type parameter. That is, the type represents the XQuery sequence type `document-node(element(*, xs:untyped))`
Throws:
  `XQException` - if (1) the `varName` or `value` argument is `null`, (2) the conversion of the value to an XDM instance failed, (3) in case of `XQPreparedExpression`, the dynamic type of the bound value is not compatible with the static type of the variable, (4) in case of an `XQPreparedExpression`, the variable is not defined in the prolog of the expression, or (5) if the expression is in a closed state
See Also:
  `OXQEntity`

#### bindBigDecimal

    void bindBigDecimal(javax.xml.namespace.QName varName,
                        java.math.BigDecimal value,
                        XQItemType type)
                 throws XQException

Binds a value to the given external variable or the context item. The value is converted into an instance of the specified type according to the rule defined in 14.2 Mapping a Java Data Type to an XQuery Data Type, XQuery API for Java (XQJ) 1.0. If the conversion fails, or if there is a mismatch between the static and dynamic types, an exception is raised either by this method, or during query evaluation.

Parameters:
  `varName` - the name of the external variable to bind to, cannot be `null`
  `value` - the value to be converted
  `type` - the type of the value to be bound to the external variable. The default type of the value is used in case `null` is specified
Throws:
  `XQException` - if (1) the `varName` argument is `null`, (2) the conversion of the value to an XDM instance failed, (3) in case of an `XQPreparedExpression`, the dynamic type of the bound value is not compatible with the static type of the variable, (4) in case of `XQPreparedExpression`, the variable is not defined in the prolog of the expression, or (5) if the expression is in a closed state

#### bindBigInteger

    void bindBigInteger(javax.xml.namespace.QName varName,
                        java.math.BigInteger value,
                        XQItemType type)
                 throws XQException

Binds a value to the given external variable or the context item. The value is converted into an instance of the specified type according to the rule defined in 14.2 Mapping a Java Data Type to an XQuery Data Type, XQuery API for Java (XQJ) 1.0. If the conversion fails, or if there is a mismatch between the static and dynamic types, an exception is raised either by this method, or during query evaluation.

Parameters:
  `varName` - the name of the external variable to bind to, cannot be `null`
  `value` - the value to be converted
  `type` - the type of the value to be bound to the external variable. The default type of the value is used in case `null` is specified
Throws:
  `XQException` - if (1) the `varName` argument is `null`, (2) the conversion of the value to an XDM instance failed, (3) in case of an `XQPreparedExpression`, the dynamic type of the bound value is not compatible with the static type of the variable, (4) in case of `XQPreparedExpression`, the variable is not defined in the prolog of the expression, or (5) if the expression is in a closed state

#### bindBinary

    void bindBinary(javax.xml.namespace.QName varName,
                    byte[] value,
                    XQItemType type)
             throws XQException

Binds a value to the given external variable or the context item. The value is converted into an instance of the specified type according to the rule defined in 14.2 Mapping a Java Data Type to an XQuery Data Type, XQuery API for Java (XQJ) 1.0. If the conversion fails, or if there is a mismatch between the static and dynamic types, an exception is raised either by this method, or during query evaluation.

Parameters:
  `varName` - the name of the external variable to bind to, cannot be `null`
  `value` - the value to be converted
  `type` - the type of the value to be bound to the external variable. The default type of the value is used in case `null` is specified
Throws:
  `XQException` - if (1) the `varName` argument is `null`, (2) the conversion of the value to an XDM instance failed, (3) in case of `XQPreparedExpression`, the dynamic type of the bound value is not compatible with the static type of the variable, (4) in case of `XQPreparedExpression`, the variable is not defined in the prolog of the expression, or (5) if the expression is in a closed state

#### bindCalendar

    void bindCalendar(javax.xml.namespace.QName varName,
                      javax.xml.datatype.XMLGregorianCalendar value,
                      XQItemType type)
               throws XQException

Binds a value to the given external variable or the context item. The value is converted into an instance of the specified type according to the rule defined in 14.2 Mapping a Java Data Type to an XQuery Data Type, XQuery API for Java (XQJ) 1.0. If the conversion fails, or if there is a mismatch between the static and dynamic types, an exception is raised either by this method, or during query evaluation.

Parameters:
  `varName` - the name of the external variable to bind to, cannot be `null`
  `value` - the value to be converted
  `type` - the type of the value to be bound to the external variable. The default type of the value is used in case `null` is specified
Throws:
  `XQException` - if (1) the `varName` argument is `null`, (2) the conversion of the value to an XDM instance failed, (3) in case of an `XQPreparedExpression`, the dynamic type of the bound value is not compatible with the static type of the variable, (4) in case of `XQPreparedExpression`, the variable is not defined in the prolog of the expression, or (5) if the expression is in a closed state

#### bindDuration

    void bindDuration(javax.xml.namespace.QName varName,
                      javax.xml.datatype.Duration value,
                      XQItemType type)
               throws XQException

Binds a value to the given external variable or the context item. The value is converted into an instance of the specified type according to the rule defined in 14.2 Mapping a Java Data Type to an XQuery Data Type, XQuery API for Java (XQJ) 1.0. If the conversion fails, or if there is a mismatch between the static and dynamic types, an exception is raised either by this method, or during query evaluation.

Parameters:
  `varName` - the name of the external variable to bind to, cannot be `null`
  `value` - the value to be converted
  `type` - the type of the value to be bound to the external variable. The default type of the value is used in case `null` is specified
Throws:
  `XQException` - if (1) the `varName` argument is `null`, (2) the conversion of the value to an XDM instance failed, (3) in case of an `XQPreparedExpression`, the dynamic type of the bound value is not compatible with the static type of the variable, (4) in case of `XQPreparedExpression`, the variable is not defined in the prolog of the expression, or (5) if the expression is in a closed state

#### bindQName

    void bindQName(javax.xml.namespace.QName varName,
                   javax.xml.namespace.QName value,
                   XQItemType type)
            throws XQException

Binds a value to the given external variable or the context item. The value is converted into an instance of the specified type according to the rule defined in 14.2 Mapping a Java Data Type to an XQuery Data Type, XQuery API for Java (XQJ) 1.0. If the conversion fails, or if there is a mismatch between the static and dynamic types, an exception is raised either by this method, or during query evaluation.

Parameters:
  `varName` - the name of the external variable to bind to, cannot be `null`
  `value` - the value to be converted
  `type` - the type of the value to be bound to the external variable. The default type of the value is used in case `null` is specified
Throws:
  `XQException` - if (1) the `varName` argument is `null`, (2) the conversion of the value to an XDM instance failed, (3) in case of an `XQPreparedExpression`, the dynamic type of the bound value is not compatible with the static type of the variable, (4) in case of `XQPreparedExpression`, the variable is not defined in the prolog of the expression, or (5) if the expression is in a closed state

#### setDebugListener

    void setDebugListener(OXQDebugListener listener)
                   throws XQException

Sets the debug listener.

Parameters:
  `listener` - the debug listener
Throws:
  `XQException` - if the `OXQDataSource` property `OXQDataSource.DEBUG_MODE` is false
See Also:
  `OXQDataSource.DEBUG_MODE`, `OXQDebugListener`

#### getDebugListener

    OXQDebugListener getDebugListener()
                               throws XQException

Gets the debug listener.

Returns:
  listener the debug listener
Throws:
  `XQException` - if the `OXQDataSource` property `OXQDataSource.DEBUG_MODE` is false
See Also:
  `OXQDataSource.DEBUG_MODE`, `OXQDebugListener`

#### setPageManager

    void setPageManager(PageManager pageManager)
                 throws XQException

Sets the `PageManager`.

Parameters:
  `pageManager` - the page manager
Throws:
  `XQException` - if the `OXQDataSource.USE_EXTERNAL_STORAGE` property is false
See Also:
  `OXQDataSource.USE_EXTERNAL_STORAGE`

#### getPageManager

    PageManager getPageManager()
                        throws XQException

Gets the `PageManager`.

Returns:
  the page manager
Throws:
  `XQException`
See Also:
  `OXQDataSource.USE_EXTERNAL_STORAGE`

#### setUpdateMode

    void setUpdateMode(int mode)
                throws XQException

Sets the update mode. Setting the mode to `OXQConstants.UPDATE_MODE_ENABLED` will enable XQuery Update Facility extensions to update XML. Setting the mode to `OXQConstants.UPDATE_MODE_DISABLED` will prevent XQuery Update Facility extension from updating XML. Note, the transform expression is always enabled regardless of the update mode setting.

The update mode may only be set when the binding mode is `XQConstants.BINDING_MODE_DEFERRED`.

Parameters:
  `mode` - The update mode, either `OXQConstants.UPDATE_MODE_DISABLED` or `OXQConstants.UPDATE_MODE_ENABLED`.
Throws:
  `XQException` - (1) if mode is not `OXQConstants.UPDATE_MODE_DISABLED` or `OXQConstants.UPDATE_MODE_ENABLED` (2) if the binding mode is not `XQConstants.BINDING_MODE_DEFERRED`
See Also:
  `getUpdateMode()`

#### getUpdateMode

    int getUpdateMode()

Gets the default update mode.

Returns:
  either `OXQConstants.UPDATE_MODE_DISABLED` or `OXQConstants.UPDATE_MODE_ENABLED`
See Also:
  `setUpdateMode(int)`

#### unbindAllExternalVariablesAndContextItem

    void unbindAllExternalVariablesAndContextItem()
                                           throws XQException

Unbinds all external variables and context item.

This method will unbind all external variables and the context item bound via the `bindXXX` methods.

The method is intented to be used for releasing memory associated with bound values in case of an error during a `bindXXX` method invocation.

This method should not be used to release memory associated with bound variables and the context item after `XQPreparedExpression.executeQuery()` or one of the `executeQuery(...)` methods of `XQExpression` is called. Assuming deferred binding mode, the memory associated with the bindings is released automatically (note, however, that the application must call close() on the `XQResultSequence` to release the memory).

For example, assume the application creates an `XQPreparedExpression` for a query that declares two external variables: `$a` and `$b`. Assume the application binds `$a` successfully, but the `bindXXX` method invoked to bind `$b` throws an exception. Now suppose the application needs to hold on to the `XQPreparedExpression` for future use, when new values for `$a` and `$b` will be bound. This method provides the ability to unbind all external variables, and, consequently, release the reference to the `$a` bound value from the `XQPreparedExpression`.

Throws:
  `XQException` - if the binding mode is not set to deferred

Copyright © 2003, 2018, Oracle and/or its affiliates. All rights reserved.