Elements of the Source Configuration File

This section provides definitions and examples of all elements possible in a DataDirect XQuery source configuration file. The elements are presented in hierarchical order.

The order in which the elements are listed in this section is the order in which they must be specified in the file. The bold typeface in the examples indicates the element being defined.

XQJConnection: Root Element

The root element in the source configuration file. The namespace is http://www.datadirect.com/xquery.

baseUri Element

Specifies the baseURI property in the XQuery static context, which is the base URI used to resolve relative URIs in fn:doc().

<?xml version="1.0" ?> 
<XQJConnection xmlns="http://www.datadirect.com/xquery"> 
  <baseUri>file:///c:/programs/ddxq/examples/</baseUri>

collation Element

Specifies the collation URI for the default collation to be used by the Java Virtual Machine.

<?xml version="1.0" ?> 
<XQJConnection xmlns="http://www.datadirect.com/xquery"> 
  <baseUri>file:///c:/programs/ddxq/examples/</baseUri> 
  <collation>http://www.datadirect.com/xquery/collation?lang=de</collation>

spyAttributes Element

Enables and sets attributes for DataDirect Spy, a tool that logs detailed information about XQJ calls issued by a Java application. For example, you may want to log all XQJ activity to a log file on your local machine.

Once enabled, you can turn DataDirect Spy on and off at runtime using the setEnableLogging() method of the com.ddtek.xquery.ExtLogControl interface.

spy_attribute=value[;spy_attribute=value]...

where spy_attribute=value is a DataDirect Spy attribute and a valid value for that attribute.

<?xml version="1.0" ?> 
<XQJConnection xmlns="http://www.datadirect.com/xquery"> 
  <baseUri>file:///c:/programs/ddxq/examples/</baseUri> 
  <collation>http://www.datadirect.com/xquery/collation?lang=de</collation> 
  <spyAttributes>log=(file)/tmp/spy.log;logSAX=yes</spyAttributes>

documentUriResolver Element

Specifies 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 construct a Java class to resolve a set of XML documents to an alias.

<?xml version="1.0" ?> 
<XQJConnection xmlns="http://www.datadirect.com/xquery"> 
  <baseUri>file:///c:/programs/ddxq/examples/</baseUri> 
  <collation>http://www.datadirect.com/xquery/collation?lang=de</collation> 
  <spyAttributes>log=(file)/tmp/spy.log;logSAX=yes</spyAttributes> 
  <documentUriResolver> 
     com.tagsalad.transform.StreamSource 
  </documentUriResolver>

moduleUriResolver Element

Specifies a Java class that implements the com.ddtek.xquery.ModuleURIresolver interface to resolve the module to be imported. For example, you may want to create a Java class to resolve custom URLs that point to a custom repository that stores XQuery modules.

<?xml version="1.0" ?> 
<XQJConnection xmlns="http://www.datadirect.com/xquery"> 
  <baseUri>file:///c:/programs/ddxq/examples/</baseUri> 
  <collation>http://www.datadirect.com/xquery/collation?lang=de</collation> 
  <spyAttributes>log=(file)/tmp/spy.log;logSAX=yes</spyAttributes> 
  <documentUriResolver> 
     com.tagsalad.transform.StreamSource 
  </documentUriResolver> 
  <moduleUriResolver> 
    customModuleResolver 
  </moduleUriResolver>

collectionUriResolver Element

Specifies 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 XML files.

<?xml version="1.0" ?> 
<XQJConnection xmlns="http://www.datadirect.com/xquery"> 
  <baseUri>file:///c:/programs/ddxq/examples/</baseUri> 
  <collation>http://www.datadirect.com/xquery/collation?lang=de</collation> 
  <spyAttributes>log=(file)/tmp/spy.log;logSAX=yes</spyAttributes> 
  <documentUriResolver> 
     com.tagsalad.transform.StreamSource 
  </documentUriResolver> 
  <moduleUriResolver> 
    customModuleResolver 
  </moduleUriResolver> 
  <collectionUriResolver> 
     com.tagfolders.fetch.StreamSource 
  </collectionUriResolver>

maxPooledQueries Element

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 the value of this element is set to 20, the driver caches the last 20 queries executed by the application. If the value set for this element is greater than the number of queries used by the application, all queries are cached. By default, query pooling is disabled.

<?xml version="1.0" ?> 
<XQJConnection xmlns="http://www.datadirect.com/xquery"> 
  <baseUri>file:///c:/programs/ddxq/examples/</baseUri> 
  <collation>http://www.datadirect.com/xquery/collation?lang=de</collation> 
  <spyAttributes>log=(file)/tmp/spy.log;logSAX=yes</spyAttributes> 
  <documentUriResolver> 
     com.tagsalad.transform.StreamSource 
  </documentUriResolver> 
  <moduleUriResolver> 
     com.tagfolders.fetch.StreamSource 
  </moduleUriResolver> 
  <collectionUriResolver> 
    com.tagfolders.fetch.StreamSource 
  </collectionUriResolver> 
  <maxPooledQueries>20</maxPooledQueries>

allowJavaFunctions Element

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.

<?xml version="1.0" ?> 
<XQJConnection xmlns="http://www.datadirect.com/xquery"> 
  <baseUri>file:///c:/programs/ddxq/examples/</baseUri> 
  <collation>http://www.datadirect.com/xquery/collation?lang=de</collation> 
  <spyAttributes>log=(file)/tmp/spy.log;logSAX=yes</spyAttributes> 
  <documentUriResolver> 
     com.tagsalad.transform.StreamSource 
  </documentUriResolver> 
  <moduleUriResolver> 
     customModuleResolver 
  </moduleUriResolver> 
  <collectionUriResolver> 
     com.tagfolders.fetch.StreamSource 
  </collectionUriResolver> 
  <maxPooledQueries>20</maxPooledQueries> 
  <allowJavaFunctions>false</allowJavaFunctions>

option Element

Specifies a global option declaration to use as the default for all XML and relational data sources that are used by queries in your Java application.

The name attribute is required and specifies the name of the global option declaration. Option declarations that can be specified globally are detect-XPST0005, plan-explain, serialize, and xml-streaming.

You can also specify option declarations for each individual connection specified in this file.

<?xml version="1.0" ?> 
<XQJConnection xmlns="http://www.datadirect.com/xquery"> 
  <baseUri>file:///c:/programs/ddxq/examples/</baseUri> 
  <collation>http://www.datadirect.com/xquery/collation?lang=de</collation> 
  <spyAttributes>log=(file)/tmp/spy.log;logSAX=yes</spyAttributes> 
  <documentUriResolver> 
     com.tagsalad.transform.StreamSource 
  </documentUriResolver> 
  <moduleUriResolver> 
    customModuleResolver 
  </moduleUriResolver> 
  <collectionUriResolver> 
     com.tagfolders.fetch.StreamSource 
  </collectionUriResolver> 
  <maxPooledQueries>20</maxPooledQueries> 
  <allowJavaFunctions>false</allowJavaFunctions> 
  <option name="detect-XPT0005">no</option>

JDBCConnection Element

Defines all of the connection information for a single database. It is only required when specifying connection information for a database. An XQJConnection element can contain one or multiple JDBCConnection elements. This element can have two attributes: name and targetNamespace.

The name attribute is required and defines a name for the JDBC connection. This name is sometimes needed to qualify the database table when specifying it using fn:collection() in your query.

The targetNamespace attribute is optional and sets the value of the TARGETNS variable for the SQL/XML mappings used for this JDBC connection. It specifies the namespace associated with this connection.

<?xml version="1.0" ?> 
<XQJConnection xmlns="http://www.datadirect.com/xquery"> 
... 
<JDBCConnection name="example_connection_name targetNamespace= 
  "http://www.example_namespace.com">

description Element

Specifies a description for the SQL adaptor. It has no effect on query operation and is used only for documentation.

<?xml version="1.0" ?> 
<XQJConnection xmlns="http://www.datadirect.com/xquery"> 
... 
  <JDBCConnection name="example_connection_name"> 
    <description>connection_description</description>

url Element

Specifies the JDBC URL of the underlying database. It is only required when specifying connection information for a database.

... 
  <JDBCConnection name="example_connection_name"> 
    <description>connection_description</description> 
      <url> 
        jdbc:xquery:sqlserver://localhost:1433;DatabaseName=example_db 
      </url>

user Element

NOTE: Alternatively, you can specify the user ID for the underlying database in your Java application, which takes precedence over the user ID specified in the source configuration file.

... 
  <JDBCConnection name="example_connection_name"> 
    <description>connection_description</description> 
    <url> 
      jdbc:xquery:sqlserver://localhost:1433;DatabaseName=example_db 
    </url> 
    <user>example_db_user</user>

password Element

NOTE: Alternatively, you can specify the password for the underlying database in your Java application, which takes precedence over the password specified in the source configuration file.

... 
  <JDBCConnection name="example_connection_name"> 
    <description>connection_description</description> 
    <url> 
      jdbc:xquery:sqlserver://localhost:1433;DatabaseName=example_db 
    </url> 
    <user>example_db_user</user> 
    <password>example_db_user_pswd</password>

transactionIsolationLevel Element

Specifies the transaction isolation level of a connection (XQConnection object).

readUncommitted. Locks are obtained on modifications to the database and held until end of transaction (EOT). Reading from the database does not involve any locking.

readCommitted. Locks are acquired for reading and modifying the database. Locks are released after reading but locks on modified objects are held until EOT.

repeatableRead. 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 nonmodified access structures (such as indexes and hashing structures) are released after reading.

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.

none. Transactions are not supported.

-1. The default transaction isolation level of the database 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).

... 
  <JDBCConnection name="example_connection_name"> 
    <description>connection_description</description> 
    <url> 
      jdbc:xquery:sqlserver://localhost:1433;DatabaseName=example_db 
    </url> 
    <user>example_db_user</user> 
    <password>example_db_user_pswd</password> 
    <transactionIsolationLevel>repeatableRead</transactionIsolationLevel>

sqlxmlMapping Element, forest and identifierEscaping Child Elements

sqlxmlMapping: Child element of JDBCConnection
forest: Child element of sqlxmlMapping
identifierEscaping: Child element of sqlxmlMapping

The sqlxmlMapping element configures SQL/XML mappings for relational data. This element can contain two child elements: forest and identifierEscaping.

The forest element specifies the format of the XML result that fn:collection() returns. Valid values are true and false. If this element is not specified, DataDirect XQuery uses true by default.

The identifierEscaping element controls 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. If the identifierEscaping element is not specified, DataDirect XQuery uses full by default.

... 
  <JDBCConnection name="example_connection_name"> 
    <description>connection_description</description> 
    <url> 
      jdbc:xquery:sqlserver://localhost:1433;DatabaseName=example_db 
    </url> 
    <user>example_db_user</user> 
    <password>example_db_user_pswd</password> 
    <transactionIsolationLevel>repeatableRead</transactionIsolationLevel> 
    <sqlxmlMapping> 
      <forest>false</forest> 
      <identifierEscaping>full</identifierEscaping> 
    </sqlxmlMapping>

tempTable Element, column and createStmtSuffix Child Elements

tempTable: Child element of JDBCConnection
column: Child element of tempTable
createStmtSuffix: Child element of tempTable

The tempTable element specifies which SQL type is used for columns when DataDirect XQuery creates temporary tables for query optimization and information you should specify if you are connecting to a DB2 for z/OS Unicode database.

If you do not specify the column element (child element of tempTable), 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 the tempTable element to specify that the temporary tables be created with a case-sensitive collation.

The sqlType attribute 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.

If you are connecting to a DB2 for z/OS Unicode database, you should specify the createStmtSuffix element (child element of tempTable) as follows:

boolean	hexBinary
byte	int
date	integer
dateTime	long
decimal	short
double	string
float	time

<tempTable> 
  <createStmtSuffix>CCSID UNICODE ON COMMIT PRESERVE ROWS</createStmtSuffix> 
</tempTable>

NOTE: Temporary tables can be used only if the database configuration and authorization settings for the user allow temporary tables to be created and populated. This is enabled by default in a typical installation of Informix, Microsoft SQL Server, MySQL, Oracle, PostgreSQL, and Sybase. For DB2, you must make sure the user has the USE privilege on a previously created USER TEMPORARY tablespace. Refer to your database documentation for details. For MySQL, DataDirect XQuery uses a regular table to store temporary data; therefore, you must create table privileges on the current schema. Refer to your database documentation for details.

... 
  <JDBCConnection name="example_connection_name"> 
    <description>connection_description</description> 
    <url> 
      jdbc:xquery:sqlserver://localhost:1433;DatabaseName=example_db 
    </url> 
    <user>example_db_user</user> 
    <password>example_db_user_pswd</password> 
    ... 
   <tempTable> 
     <column xqueryType="string" sqlType="nvarchar(2000) collate
       SQL_Latin1_General_CP1_CS_AS"/> 
     <createStmtSuffix>CCSID UNICODE ON COMMIT PRESERVE ROWS</createStmtSuffix> 
  </tempTable>

option Element

Specifies an option declaration for the relational database specified by the Url element. A JDBCConnection element can contain one or multiple option elements.

The name attribute is required and specifies the name of the option declaration.

You also can specify an option declaration globally for all XML and relational data sources using the option element, a child of XQJConnection (see option Element).

... 
  <JDBCConnection name="example_connection_name"> 
    <description>connection_description</description> 
    <url> 
      jdbc:xquery:sqlserver://localhost:1433;DatabaseName=example_db 
    </url> 
    <user>example_db_user</user> 
    <password>example_db_user_pswd</password> 
    ... 
    <option name="sql-decimal-cast">10,5</option>

catalog Element

Specifies information about the catalog that is associated with the database being accessed by fn:collection(). When connecting to DB2, Informix, MySQL, Microsoft SQL Server, and Sybase, the JDBCConnection element can contain one or multiple catalog elements. This element can have three attributes: name, alias, and targetNamespace.

The name attribute is required for DB2, Informix, MySQL, Microsoft SQL Server, and Sybase databases. For Oracle and PostgreSQL databases, which do not have catalogs, a name attribute is not required. This attribute specifies the name of the database being accessed by fn:collection().

The targetNamespace attribute is optional and specifies a namespace to be assigned to elements from this catalog.

... 
 <JDBCConnection name="example_connection_name"> 
    <description>connection_description</description> 
    <url> 
      jdbc:xquery:sqlserver://localhost:1433;DatabaseName=example_db 
    </url> 
    <user>example_db_user</user> 
    <password>example_db_user_pswd</password> 
    ... 
    <catalog name="example_db" alias="example_alias" 
      targetNamespace="http://www.example_namespace.com">

schema Element

Specifies information about the schema associated with the database being accessed by fn:collection(). This element provides access to all tables found in the corresponding schema. A catalog element can contain one or more schema elements. This element can have three attributes: name, alias, and targetNamespace.

The name attribute is required for DB2, Informix, Oracle, Microsoft SQL Server, PostgreSQL, and Sybase. For MySQL, which does not have schemas, the name attribute is not required. The name attribute provides the name of a schema (user) associated with the database being accessed by fn:collection().

The targetNamespace attribute is optional and specifies a namespace to be assigned to elements from this schema.

... 
 <JDBCConnection name="example_connection_name"> 
    <description>connection_description</description> 
    <url> 
      jdbc:xquery:sqlserver://localhost:1433;DatabaseName=example_db 
    </url> 
    <user>example_db_user</user> 
    <password>example_db_user_pswd</password> 
    ... 
    <catalog name="example_db" alias="example_alias" 
      targetNamespace="http://www.example_namespace.com> 
      <schema name="example_db_user" alias="example_alias" 
        targetNamespace="http://www.example_namespace.com">

table Element

Specifies the database table being accessed by fn:collection(). A schema element can contain one or multiple table elements. This element can have three attributes: name, alias, and targetNamespace.

The name attribute is required and provides the name of a database table being accessed by fn:collection().

The targetNamespace attribute is optional and specifies a namespace to be assigned to the elements in the results.

... 
 <JDBCConnection name="example_connection_name"> 
    <description>connection_description</description> 
    <url> 
      jdbc:xquery:sqlserver://localhost:1433;DatabaseName=example_db 
    </url> 
    <user>example_db_user</user> 
    <password>example_db_user_pswd</password> 
    ... 
    <catalog name="example_db" alias="example_alias" 
      targetNamespace="http://www.example_namespace.com> 
      <schema name="example_db_user" alias="example_alias" 
        targetNamespace="http://www.example_namespace.com"> 
        <table name="example_table_name" alias="example_alias" 
          targetNamespace="http://www.example_namespace.com">

column Element

Specifies information about the database table column. The table element can contain one or multiple column elements. This element can have four attributes: name, isPrimaryKey, alias, and schemaType.

The name attribute is required and provides the name of a column in a database table being accessed by fn:collection().

The isPrimaryKey attribute is optional and indicates if the column is part of the primary key. Valid values are true and false. If the column is part of a primary key, setting true as a value for this attribute improves performance.

The schemaType attribute is optional and overrides the default mapping for data type conversions. Valid values are any XQuery atomic type supported by DataDirect XQuery.

... 
<JDBCConnection name="example_connection_name"> 
    <description>connection_description</description> 
    <url> 
      jdbc:xquery:sqlserver://localhost:1433;DatabaseName=example_db 
    </url> 
    <user>example_db_user</user> 
    <password>example_db_user_pswd</password> 
    ... 
    <catalog name="example_db" alias="example_alias" 
      targetNamespace="http://www.example_namespace.com> 
      <schema name="example_db_user" alias="example_alias" 
        targetNamespace="http://www.example_namespace.com">          
        <table name="example_table_name" alias="example_alias" 
          targetNamespace="http://www.example_namespace.com"> 
          <column name="example_column_name" alias="example_alias"
            isPrimaryKey="true" schemaType="xs:string"/> 
        </table> 
      </schema> 
    </catalog> 
  </JDBCConnection> 
</XQJConnection>

tableFunction Element

Specifies a SQL table function to use in DataDirect XQuery. DataDirect XQuery must know the details of the result set returned from the SQL table function so that it can correctly fetch the results and build the correct XML mapping (if needed).

This element has three attributes: name, alias, and targetNamespace. In addition, it can have one resultSet element, which can contain one or more column child elements.

The targetNamespace attribute is optional and specifies a namespace to be assigned to the elements that are created according the resultSet element.

... 
 <JDBCConnection name="example_connection_name"> 
    <description>connection_description</description> 
    <url> 
      jdbc:xquery:sqlserver://localhost:1433;DatabaseName=example_db 
    </url> 
    <user>example_db_user</user> 
    <password>example_db_user_pswd</password> 
    ... 
    <catalog name="example_db" alias="example_alias" 
      targetNamespace="http://www.example_namespace.com> 
      <schema name="example_db_user" alias="example_alias" 
        targetNamespace="http://www.example_namespace.com"> 
          <tableFunction name="DB_PARTITIONS">

resultSet Element, column Child Element

The resultSet element configures the result set returned from the SQL table function specified by the name attribute of the tableFunction element. This element must contain one or more column child elements.

The column element defines the columns of the result set returned from the SQL table function. This element can have five attributes: name, alias, isPrimaryKey, isPseudo, and schemaType.

The name attribute is required and specifies the name of the column. When no alias attribute is specified, the value of the name attribute is also the name of the element that is created to wrap the values from the column.

The alias attribute is optional and is used to rename the column name.

The isPrimaryKey attribute indicates if the column is part of the primary key. Valid values are true and false. This attribute is required only when the result set of the table function will be used to populate parent nodes in a hierarchical XML structure.

The isPseudo attribute is optional and specifies whether this column is a pseudo column. Valid values are true and false. This is useful when the column does not have to be included in the resulting XML mapping of the table function.

The schemaType attribute is required and specifies the XML schema type of the column. See the tables in Data Type Mappings for the mapping of database data types to XML schema types.

... 
 <JDBCConnection name="example_connection_name"> 
    <description>connection_description</description> 
    <url> 
      jdbc:xquery:sqlserver://localhost:1433;DatabaseName=example_db 
    </url> 
    <user>example_db_user</user> 
    <password>example_db_user_pswd</password> 
    ... 
    <catalog name="example_db" alias="example_alias" 
      targetNamespace="http://www.example_namespace.com> 
      <schema name="example_db_user" alias="example_alias" 
        targetNamespace="http://www.example_namespace.com">          
          <tableFunction name="DB_PARTITIONS"> 
            <resultSet> 
              <column name="PARTITION_NUMBER" schemaType="short"/> 
              <column name="HOST_NAME" schemaType="string"/> 
              <column name="PORT_NUMBER" schemaType="short"/> 
              <column name="SWITCH_NAME" schemaType="string"/> 
            </resultSet> 
          </tableFunction>