DDXQDataSource and DDXQJDBCConnection Properties

The class name of the DataDirect XQuery XQDataSource implementation is:

com.ddtek.xquery3.xqj.DDXQDataSource

It provides properties that allow you to configure most DataDirect XQuery settings and configure connections.

The following class provides additional properties for configuring connections to multiple databases:

com.ddtek.xquery3.xqj.DDXQJDBCConnection

Table 5-1 lists the properties supported by the DDXQDataSource class, DataDirect XQuery’s XQDataSource implementation, and describes each property. See Table 5-2 for a list of the properties supported by the DDXQJDBCConnection class, which is used to specify additional connection information when connecting to multiple databases.

NOTE: All property names are case-insensitive. For example, password is the same as Password.

Table 5-1. DDXQDataSource Properties  
Property
Description
AllowJavaFunctions
Specifies whether external Java functions are allowed. By default, external functions are allowed. To disable external functions for security reasons, for example, set this property to false.
BaseUri
The baseURI property in the XQuery static context, which is the base URI used to resolve relative URIs in fn:doc(). See "XML Data Sources" for rules governing URIs.
NOTE: You can also specify a base URI in the query prolog.
Collation
The collation URI for the default collation to be used by the Java Virtual Machine. See "Querying Multiple Files in a Directory" for more information.
CollectionUriResolver
A Java class that implements the com.ddtek.xquery.CollectionURIResolver interface to resolve URIs in fn:collection(). For example, you may want to create a Java class to resolve custom URLs that point to a directory that contains your XML files. See "Collection URI Resolvers" for more information.
DocumentUriResolver
A Java class that implements the javax.xml.transform.URIResolver interface to resolve URIs in fn:doc() and fn:doc-available(). For example, you may want to create a Java class to resolve custom URLs that point to a proprietary repository that stores your XML documents such as an XML database. See "Document URI Resolvers" for more information.
JdbcName
The name of the JDBC connection. A JDBC connection name identifies a specific connection to a relational database.
If specifying a JDBC connection name for multiple databases, use the Name property of the DDXQJDBCConnection class.
JdbcOptions
Specifies one or multiple option declarations for the relational database specified by the JdbcUrl property. Valid option declarations are:
sql-decimal-cast
sql-extra-checks-trailing-spaces
sql-ignore-trailing-spaces
sql-ora10-use-binary-float-double
sql-order-by-on-values
sql-rewrite-algorithm
sql-rewrite-exists-into-count
sql-simple-convert-functions
sql-simple-string-functions
sql-sybase-temptable-index
sql-sybase-use-derived-tables
sql-unicode-strings
sql-varchar-cast
See "Using Option Declarations" for a description of these option declarations.
The value of this property is a semicolon-separated list of option declaration name=value pairs:
name=value[;name=value]...
For example:
sql-unicode-strings=yes;sql-decimal-cast=10,5
You also can specify a global option declaration for all XML and relational data sources using the Options property.
NOTE: You can override this setting in the query.
If specifying an option declaration for multiple databases, use the Options property of the DDXQJDBCConnection class.
JdbcSqlXmlForest
Specifies the format of the XML result that fn:collection() returns. Valid values are true and false. The default is true. See "Data Model Representation of Relational Tables" for details about the format of the XML result.
JdbcSqlXmlIdentifierEscaping
Specifies how DataDirect XQuery handles escaping of identifiers, which is needed because of mismatches that occur when characters in SQL identifiers are mapped to XML. Valid values are:
  • none (the default). No mapping is performed. An error is raised if a character in a SQL identifier cannot be mapped to XML.
  • partial. Characters in SQL identifiers that are not XML characters are escaped using an underscore character (_) followed by a lowercase x followed by the character’s Unicode representation in hexadecimal format followed by an underscore character (_). For example, sales!forecast becomes sales_x0021_forecast.
  • full. In addition to the escaping performed by partial, the character x of a SQL identifier that starts with "xml" (in any combination of upper and lowercase characters) is escaped. For example, XMLTable becomes _x0058_MLTable.
JdbcTempTableColumns
xquerytype="value" sqlType="value". Specifies which SQL type is used for columns when DataDirect XQuery creates temporary tables for query optimization.
If you do not specify a value for this property, DataDirect XQuery uses the SQL/XML mappings to determine which SQL type to use for the columns of temporary tables; however, this can sometimes cause problems. For example, if your database table has a case-sensitive collation and the temporary table is created with a case-insensitive collation, an error is raised. In this case, use this property to specify that the temporary tables be created with a case-sensitive collation.
A value for xqueryType is required and specifies one of the following values: boolean, byte, date, dateTime, decimal, double, float, hexBinary, int, integer, long, short, string, or time.
A value for sqlType is required and determines the database type declaration that is appended to the column names when temporary tables are created. The specified data type must be supported by the database used to create the temporary tables.
For example:
xqueryType="string" sqlType="nvarchar(2000) collate SQL_Latin1_General_CP1_CS_AS"
JdbcTempTableSuffix
CCSID UNICODE ON COMMIT PRESERVE ROWS. You must specify this property if you are connecting to a DB2 for z/OS Unicode database.
JdbcTransactionIsolationLevel
Specifies the transaction isolation level. Valid values are:
  • java.sql.Connection.TRANSACTION_READ_UNCOMMITTED. Locks are obtained on modifications to the database and held until end of transaction (EOT). Reading from the database does not involve any locking.
  • java.sql.Connection.TRANSACTION_READ_COMMITTED. Locks are acquired for reading and modifying the database. Locks are released after reading, but locks on modified objects are held until EOT.
  • java.sql.Connection.TRANSACTION_REPEATABLE_READ. Locks are obtained for reading and modifying the database. Locks on all modified objects are held until EOT. Locks obtained for reading data are held until EOT. Locks on non-modified access structures (such as indexes and hashing structures) are released after reading.
  • java.sql.Connection.TRANSACTION_SERIALIZABLE. All data read or modified is locked until EOT. All access structures that are modified are locked until EOT. Access structures used by the query are locked until EOT.
  • java.sql.Connection.TRANSACTION_NONE. Transactions are not supported.
  • -1. The default transaction isolation level is used, which is Read Committed.
The database to which you are connecting may not support all of these isolation levels. See "Transaction Isolation Levels" for details.
NOTE: Once a connection is made, the transaction isolation level cannot be changed for that connection (XQConnection object).
JdbcUrl
The JDBC URL of the database. See "Specifying Connection URLs" for the syntax of URLs.
If specifying a URL for multiple databases, use the Url property of the DDXQJDBCConnection class.
MaxPooledQueries
Specifies the maximum number of queries that can be placed in the pool when DataDirect XQuery’s internal query pooling is enabled. When enabled, DataDirect XQuery caches a certain number of queries executed by an application. For example, if this property is set to 20, DataDirect XQuery caches the last 20 queries executed by the application. If the value set for this property is greater than the number of queries used by the application, all queries are cached. By default, query pooling is disabled. See "Using Query Pooling" for more information.
ModuleUriResolver
A Java class that implements the com.ddtek.xquery.ModuleURIResolver interface to resolve the library module to be imported. For example, you may want to create a Java class to resolve URLs that point to a custom repository that stores XQuery modules. See also"Library Module URI Resolvers".
Options
Specifies a global option declaration to use as the default for all XML and relational data sources that are used by XQuery queries in your Java application. Valid global option declarations are:
detect-XPST0005
plan-explain
serialize
xml-streaming
See "Using Option Declarations" for a description of these option declarations.
The value of this property is a name=value pair:
name=value
For example:
detect-XPST0005=no
Password
A password used to connect to the database.
If specifying a password for multiple databases, use the Password property of the DDXQJDBCConnection class.
SpyAttributes
Enables and sets attributes for DataDirect Spy, a tool that logs detailed information about XQJ calls issued by a running Java application. For example, you may want to log all XQJ activity to a log file on your local machine.
The format for the value of this property is:
(spy_attribute=value[;spy_attribute=value]...)
where spy_attribute=value is a DataDirect Spy attribute and a valid value for that attribute. The following example specifies that DataDirect Spy log all XQJ activity to a log file, including the content of SAX streams passed through XQJ.
ds.setspyAttributes("log=(file)/tmp/spy.log;
logSAX=yes")
NOTE: When coding a path on Windows to the log file in a Java string, the backslash character (\) must be preceded by the Java escape character, a backslash. For example:
ds.setspyAttributes("log=(file)C:\\temp\\spy.log;
logSAX=yes")
Once enabled. you can turn DataDirect Spy on and off at runtime using the setEnableLogging() method of the com.ddtek.xquery.ExtLogControl interface.
See "Logging XQJ Calls with DataDirect Spy™ for XQJ" for instructions on using DataDirect Spy and a list of supported attributes.
User
A user name used to connect to the database.
If specifying a user for multiple databases, use the User property of the DDXQJDBCConnection class.

Table 5-2 lists the properties supported by the DDXQJDBCConnection class and describes each property (see Table 5-1 for a list of the properties supported by the DDXQDataSource class).

Table 5-2. DDXQJDBCConnection Properties  
Property
Description
Name
The name of the JDBC connection. A JDBC connection name identifies a specific connection to a relational database.
If specifying a JDBC connection name for a single database, use the JdbcName property of the DDXQDataSource class.
Options
Specifies one or multiple option declarations for the relational database specified by the Url property. Valid option declarations are:
sql-decimal-cast
sql-extra-checks-trailing-spaces
sql-ignore-trailing-spaces
sql-ora10-use-binary-float-double
sql-order-by-on-values
sql-rewrite-algorithm
sql-rewrite-exists-into-count
sql-simple-convert-functions
sql-simple-string-functions
sql-sybase-temptable-index
sql-sybase-use-derived-tables
sql-unicode-strings
sql-varchar-cast
See "Using Option Declarations" for a description of these option declarations.
The value of this property is a semicolon-separated list of option declaration name=value pairs:
name=value[;name=value]...
For example:
sql-unicode-literals=yes;sql-decimal-cast=10,5
You also can specify a global option declaration for all XML and relational data sources using the Options property of the DDXQDataSource class.
NOTE: You can override this setting in the query.
If specifying an option declaration for a single database, use the JdbcOptions property of the DDXQDataSource class.
Password
A password used to connect to the database. A password is required only if security is enabled on the database. Contact your system administrator to obtain your password.
If specifying a password for a single database, use the Password property of the DDXQDataSource class.
SqlXmlForest
Specifies the format of the XML result that fn:collection() returns. Valid values are true and false. The default is true. See "Data Model Representation of Relational Tables" for details about the format of the XML result.
SqlXmlIdentifierEscaping
Specifies how DataDirect XQuery handles escaping of identifiers, which is needed because of mismatches that occur when characters in SQL identifiers are mapped to XML. Valid values are:
  • none (the default). No mapping is performed. An error is raised if a character in a SQL identifier cannot be mapped to XML.
  • partial. Characters in SQL identifiers that are not XML characters are escaped using an underscore character (_) followed by a lowercase x followed by the character’s Unicode representation in hexadecimal format followed by an underscore character (_). For example, sales!forecast becomes sales_x0021_forecast.
  • full. In addition to the escaping performed by partial, the character x of a SQL identifier that starts with "xml" (in any combination of upper and lowercase characters) is escaped. For example, XMLTable becomes _x0058_MLTable.
TempTableColumns
xquerytype="value" sqlType="value". Specifies which SQL type is used for columns when DataDirect XQuery creates temporary tables for query optimization.
If you do not specify a value for this property, DataDirect XQuery uses the SQL/XML mappings to determine which SQL type to use for the columns of temporary tables; however, this can sometimes cause problems. For example, if your database table has a case-sensitive collation and the temporary table is created with a case-insensitive collation, an error is raised. In this case, use this property to specify that the temporary tables be created with a case-sensitive collation.
A value for xqueryType is required and specifies one of the following values: boolean, byte, date, dateTime, decimal, double, float, hexBinary, int, integer, long, short, string, or time.
A value for sqlType is required and determines the database type declaration that is appended to the column names when temporary tables are created. The specified data type must be supported by the database used to create the temporary tables.
For example:
xqueryType="string" sqlType="nvarchar(2000) collate SQL_Latin1_General_CP1_CS_AS"
TempTableSuffix
CCSID UNICODE ON COMMIT PRESERVE ROWS. You must specify this property if you are connecting to a DB2 for z/OS Unicode database.
TransactionIsolationLevel
Specifies the transaction isolation level. Valid values are:
  • java.sql.Connection.TRANSACTION_READ_UNCOMMITTED. Locks are obtained on modifications to the database and held until end of transaction (EOT). Reading from the database does not involve any locking.
  • java.sql.Connection.TRANSACTION_READ_COMMITTED. Locks are acquired for reading and modifying the database. Locks are released after reading, but locks on modified objects are held until EOT.
  • java.sql.Connection.TRANSACTION_REPEATABLE_READ. Locks are obtained for reading and modifying the database. Locks on all modified objects are held until EOT. Locks obtained for reading data are held until EOT. Locks on non-modified access structures (such as indexes and hashing structures) are released after reading.
  • java.sql.Connection.TRANSACTION_SERIALIZABLE. All data read or modified is locked until EOT. All access structures that are modified are locked until EOT. Access structures used by the query are locked until EOT.
  • java.sql.Connection.TRANSACTION_NONE. Transactions are not supported.
  • -1. The default transaction isolation level is used, which is Read Committed.
The database to which you are connecting may not support all of these isolation levels. See "Transaction Isolation Levels" for details.
NOTE: Once a connection is made, the transaction isolation level cannot be changed for that connection (XQConnection object).
Url
The JDBC URL of the database. See "Specifying Connection URLs" for the syntax of URLs.
If specifying a URL for a single database, use the JdbcUrl property of the DDXQDataSource class.
User
A user name used to connect to the database.
If specifying a user name for a single database, use the User property of the DDXQDataSource class.