oracle.xml.xquery

## Class OXQDataSource

- java.lang.Object
- - oracle.xml.xquery.OXQDataSource

All Implemented Interfaces:
  XQDataSource

    public final class OXQDataSource
    extends java.lang.Object
    implements XQDataSource

Implements `javax.xml.xquery.XQDataSource`.

Since:
  12.1
See Also:
  `XQDataSource`

### Field Summary

Fields
`static java.lang.String` `DEBUG_MODE` A property that when set to `"true"`, debugging will be enabled; otherwise, debugging will be disabled.
`static java.lang.String` `DISABLE_EXPRESSION_TRACKING` A property that when set to `"true"` will prevent a connection from tracking open expressions that are created from it.
`static java.lang.String` `DOM_PASS_THROUGH` A property that when set to `"true"` relaxes XML data model conversions.
`static java.lang.String` `IMPORT_SHARING` A property that when set to `"true"`, schema and module imports will be shared among queries from the same connection.
`static java.lang.String` `PESSIMISTIC_TYPE_CHECKING` A property that determines if optimistic or pessimistic type checking will be used at compile time.
`static java.lang.String` `USE_EXTERNAL_STORAGE` A property that when set to `"true"` will cause the query processor use an instance of `oracle.xml.scalable.PageManager` when materializing XML.

### Constructor Summary

Constructors
Constructor and Description
`OXQDataSource()` Constructs a data source with default properties.
`OXQDataSource(java.util.Properties inProperties)` Constructs a data source with the specified properties.

### Method Summary

All Methods Instance Methods Concrete Methods
`XQConnection` `getConnection()` Attempts to create a connection to an XML datasource.
`XQConnection` `getConnection(java.sql.Connection con)` Attempts to create a connection to an XML datasource using an existing JDBC connection.
`XQConnection` `getConnection(java.lang.String username, java.lang.String passwd)` Attempts to establish a connection to an XML datasource using the supplied username and password.
`int` `getLoginTimeout()` Gets the maximum time in seconds that this datasource can wait while attempting to connect to a database.
`java.io.PrintWriter` `getLogWriter()` Retrieves the log writer for this `XQDataSource` object.
`java.lang.String` `getProperty(java.lang.String name)` Returns the current value of the named property if set, else `null`.
`java.lang.String[]` `getSupportedPropertyNames()` Returns an array containing the property names supported by this `XQDataSource`.
`void` `setLoginTimeout(int seconds)` Sets the maximum time in seconds that this datasource will wait while attempting to connect to a database.
`void` `setLogWriter(java.io.PrintWriter out)` Sets the log writer for this `XQDataSource` object to the given `java.io.PrintWriter` object.
`void` `setProperties(java.util.Properties props)` Sets the data source properties from the specified `Properties` instance.
`void` `setProperty(java.lang.String name, java.lang.String value)` Sets the named property to the specified value.

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

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

### Field Detail

#### PESSIMISTIC_TYPE_CHECKING

    public static final java.lang.String PESSIMISTIC_TYPE_CHECKING

A property that determines if optimistic or pessimistic type checking will be used at compile time. In general, pessimistic type checking will fail whenever the derived type of an expression is not a subtype of the expected type. Optimistic type checking will fail whenever the derived type of an expression does not intersect the expected type. More simply put, pessimistic mode raises an error at compile time if a type might not be correct at runtime. Optimistic mode, on the other hand, only raises an error at compile time when the runtime type check will certainly fail.

When set to `"true"`, pessimistic type checking will be used. For any other value, optimistic type checking will be used. The default value is `"false"`.

See Also:
  `XQDataSource.setProperty(String, String)`, Constant Field Values

#### DEBUG_MODE

    public static final java.lang.String DEBUG_MODE

A property that when set to `"true"`, debugging will be enabled; otherwise, debugging will be disabled. The default value of this property is `"false"`

See Also:
  `XQDataSource.setProperty(String, String)`, Constant Field Values

#### IMPORT_SHARING

    public static final java.lang.String IMPORT_SHARING

A property that when set to `"true"`, schema and module imports will be shared among queries from the same connection. The default value of this property is `"false"`

See Also:
  `XQDataSource.setProperty(String, String)`, `OXQConnection.getEntityLoader(int)`, Constant Field Values

#### DOM_PASS_THROUGH

    public static final java.lang.String DOM_PASS_THROUGH

A property that when set to `"true"` relaxes XML data model conversions. XQuery is designed to process instances of the XQuery and XPath data model (XDM). In several places, the XQJ API facilitates consuming XDM as DOM. For example, `XQItemAccessor.getNode()` returns the XDM node as a DOM node. The conversion from XDM to DOM is specified in two parts: XDM Infoset Mapping and Appendix C of the DOM specification.

When the input data to the query is DOM and the output of the query is consumed as DOM, it may be desirable to avoid the required data model conversions to improve performance. When this this property is set to `"true"` DOM may be queried directly without conversion. Note, the processor can not conform strictly to the specifications when in this mode. For example, CDATA nodes, adjacent text nodes, empty text nodes, entity reference nodes, and document type nodes may all appear in the result. The default value of this property is `"false"`.

See Also:
  `XQDataSource.setProperty(String, String)`, Constant Field Values

#### USE_EXTERNAL_STORAGE

    public static final java.lang.String USE_EXTERNAL_STORAGE

A property that when set to `"true"` will cause the query processor use an instance of `oracle.xml.scalable.PageManager` when materializing XML. There are two scenarios in which the `PageManager` may be used:

1. If data is bound to the query and the binding mode is `BINDING_MODE_IMMEDIATE`, then the bound value will be copied into the `PageManager`. In this case, all pages will be released (deleted) by the time the corresponding `XQPreparedExpression` or `XQExpression` is closed.
2. If the query processor needs to materialize intermediate results while processing the query, it will use the `PageManager`. In this case, all pages will be released (deleted) by the time the corresponding `XQResultSequence` is closed.

This property must be used in combination with `OXQDynamicContext.setPageManager(oracle.xml.scalable.PageManager)` Using external storage may drastically reduce the main memory needed to process a query but it may also make query processing take longer.

See Also:
  `XQDataSource.setProperty(String, String)`, Constant Field Values

#### DISABLE_EXPRESSION_TRACKING

    public static final java.lang.String DISABLE_EXPRESSION_TRACKING

A property that when set to `"true"` will prevent a connection from tracking open expressions that are created from it. This is intended for use in cases where multiple threads access the connection and the synchronization needed to track open expressions causes performance problems. When expression tracking is disabled, an attempt to call `XQConnection.close()` will raise an error so this can only be used in cases where relying on the connection to close expressions is not needed.

See Also:
  `XQDataSource.setProperty(String, String)`, Constant Field Values

### Constructor Detail

#### OXQDataSource

    public OXQDataSource()

Constructs a data source with default properties.

#### OXQDataSource

    public OXQDataSource(java.util.Properties inProperties)
                  throws XQException

Constructs a data source with the specified properties.

Parameters:
  `inProperties` - the data source properties, may not be `null`
Throws:
  `XQException` - if `inProperties` is `null` or if a given property is not supported

### Method Detail

#### getConnection

    public XQConnection getConnection()
                               throws XQException

Attempts to create a connection to an XML datasource.

Specified by:
  `getConnection` in interface `XQDataSource`
Returns:
  a connection to the XML datasource
Throws:
  `XQException` - if a datasource access error occurs

#### getConnection

    public XQConnection getConnection(java.sql.Connection con)
                               throws XQException

Attempts to create a connection to an XML datasource using an existing JDBC connection. An XQJ implementation is not required to support this method. If it is not supported, then an exception (`XQException`) is thrown. The XQJ and JDBC connections will operate under the same transaction context.

Specified by:
  `getConnection` in interface `XQDataSource`
Parameters:
  `con` - an existing JDBC connection
Returns:
  a connection to the XML datasource
Throws:
  `XQException` - if (1) a datasource access error occurs, (2) the implementation does not support this method of getting an `XQConnection`, or (3) if the `con` parameter is `null`

#### getConnection

    public XQConnection getConnection(java.lang.String username,
                                      java.lang.String passwd)
                               throws XQException

Attempts to establish a connection to an XML datasource using the supplied username and password.

Specified by:
  `getConnection` in interface `XQDataSource`
Parameters:
  `username` - the user on whose behalf the connection is being made
  `passwd` - the user's password
Returns:
  a connection to the XML datasource
Throws:
  `XQException` - if a datasource access error occurs

#### setLoginTimeout

    public void setLoginTimeout(int seconds)
                         throws XQException

Sets the maximum time in seconds that this datasource will wait while attempting to connect to a database. A value of zero specifies that the timeout is the default system timeout if there is one; otherwise, it specifies that there is no timeout. When a `XQDataSource` object is created, the login timeout is initially zero. It is implementation-defined whether the specified login timeout is actually used by the data source implementation. If the connection is created over an existing JDBC connection, then the login timeout value from the underlying JDBC connection may be used.

Specified by:
  `setLoginTimeout` in interface `XQDataSource`
Parameters:
  `seconds` - the datasource login time limit
Throws:
  `XQException` - if a datasource access error occurs

#### getLoginTimeout

    public int getLoginTimeout()
                        throws XQException

Gets the maximum time in seconds that this datasource can wait while attempting to connect to a database. A value of zero means that the timeout is the default system timeout if there is one; otherwise, it means that there is no timeout. When a XQDataSource object is created, the login timeout is initially zero. It is implementation-defined whether the returned login timeout is actually used by the data source implementation.

Specified by:
  `getLoginTimeout` in interface `XQDataSource`
Returns:
  the datasource login time limit
Throws:
  `XQException` - if a datasource access error occurs

#### setLogWriter

    public void setLogWriter(java.io.PrintWriter out)
                      throws XQException

Sets the log writer for this `XQDataSource` object to the given `java.io.PrintWriter` object. The log writer is a character output stream to which all logging and tracing messages for this datasource will be printed. This includes messages printed by the methods of this object, messages printed by methods of other objects manufactured by this object, and so on. When a `XQDataSource` object is created the log writer is initially `null`; in other words, the default is for logging to be disabled.

Specified by:
  `setLogWriter` in interface `XQDataSource`
Parameters:
  `out` - the new log writer; to disable logging, set to `null`
Throws:
  `XQException` - if a datasource access error occurs

#### getLogWriter

    public java.io.PrintWriter getLogWriter()
                                     throws XQException

Retrieves the log writer for this `XQDataSource` object. The log writer is a character output stream to which all logging and tracing messages for this datasource will be printed. This includes messages printed by the methods of this object, messages printed by methods of other objects manufactured by this object, and so on. When a `XQDataSource` object is created, the log writer is initially `null`; in other words, the default is for logging to be disabled.

Specified by:
  `getLogWriter` in interface `XQDataSource`
Returns:
  the log writer for this datasource or `null` if logging is disabled
Throws:
  `XQException` - if a datasource access error occurs

#### getSupportedPropertyNames

    public java.lang.String[] getSupportedPropertyNames()

Returns an array containing the property names supported by this `XQDataSource`. Implementations that support user name and password must recognize the user name and password properties listed below.

`user` | the user name to use for creating a connection
`password` | the password to use for creating a connection

Any additional properties are implementation-defined.

Specified by:
  `getSupportedPropertyNames` in interface `XQDataSource`
Returns:
  `String[]` an array of property names supported by this implementation

#### setProperty

    public void setProperty(java.lang.String name,
                            java.lang.String value)
                     throws XQException

Sets the named property to the specified value. If a property with the same name was already set, then this method will override the old value for that property with the new value.

If the implementation does not support the given property or if it can determine that the value given for this property is invalid, then an exception is thrown. If an exception is thrown, then no previous value is overwritten.

Specified by:
  `setProperty` in interface `XQDataSource`
Parameters:
  `name` - the name of the property to set
  `value` - the value of the named property
Throws:
  `XQException` - if (1) the given property is not recognized, (2) the value for the given property is determined to be invalid, or (3) the `name` parameter is `null`

#### getProperty

    public java.lang.String getProperty(java.lang.String name)
                                 throws XQException

Returns the current value of the named property if set, else `null`. If the implementation does not support the given property then an exception is raised.

Specified by:
  `getProperty` in interface `XQDataSource`
Parameters:
  `name` - the name of the property whose value is needed
Returns:
  `String` representing the value of the required property if set, else `null`
Throws:
  `XQException` - if (1) a given property is not supported, or (2) the name parameter is `null`

#### setProperties

    public void setProperties(java.util.Properties props)
                       throws XQException

Sets the data source properties from the specified `Properties` instance. Properties set before this call will still apply but those with the same name as any of these properties will be replaced. Properties set after this call also apply and may replace properties set during this call.

If the implementation does not support one or more of the given property names, or if it can determine that the value given for a specific property is invalid, then an exception is thrown. If an exception is thrown, then no previous value is overwritten. is invalid, then an exception is raised.

Specified by:
  `setProperties` in interface `XQDataSource`
Parameters:
  `props` - the list of properties to set
Throws:
  `XQException` - if (1) a given property is not recognized, (2) the value for a given property is determined to be invalid, or (3) the `props` parameter is `null`

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