34 Administering Oracle XML DB

This chapter describes how to administer Oracle XML DB. It includes information about installing, upgrading, and configuring Oracle XML DB.

This chapter contains these topics:

See Also:

"Configuring Resources for XLink and XInclude" for information on configuring Oracle XML DB Repository resources for use with XLink and XInclude

Installing Oracle XML DB

You can perform a new installation of Oracle XML DB with or without Database Configuration Assistant (DBCA). You are required to install Oracle XML DB manually without DBCA if you upgrade an existing installation.

Caution:

Do not uninstall Oracle XML DB in a database that contains any XMLType data without first contacting Oracle Support.

Installing Oracle XML DB with Database Configuration Assistant

Oracle XML DB is part of the seed database and is installed by Database Configuration Assistant (DBCA) by default. No additional steps are required to install Oracle XML DB.

However, if you select the advanced database configuration, then you can configure the SYSAUX tablespace, which is used for Oracle XML DB Repository, and the port numbers for protocols FTP, HTTP(S), and WebDAV.

By default, DBCA performs the following tasks during installation:

  • Creates tablespace SYSAUX for Oracle XML DB Repository

  • Enables all protocol access

Tablespace SYSAUX holds the data stored in Oracle XML DB Repository, including data stored using:

  • SQL, for example using RESOURCE_VIEW and PATH_VIEW

  • Protocols such as FTP, HTTP(S), and WebDAV

You can store data in tables outside of this tablespace and access the data through Oracle XML DB Repository, by having REFs to that data stored in the tables in this tablespace.

See Also:

"Anonymous Access to Oracle XML DB Repository using HTTP" for information about allowing unauthenticated access to the repository

Dynamic Protocol Registration of FTP and HTTP(S) Services with Local Listener

Oracle XML DB installation dynamically registers FTP and HTTP(S) services with the local listener. You can perform start, stop, and query with lsnrctl. For example:

  • start: lsnrctl start

  • stop: lsnrctl stop

  • query: lsnrctl status

Changing FTP or HTTP(S) Port Numbers

To change FTP and HTTP(S) port numbers, update elements <ftp-port>, <http-port>, and <http2-port> in file /xdbconfig.xml in Oracle XML DB Repository.

After updating the port numbers, dynamic protocol registration automatically stops FTP/HTTP(S) service on old port numbers and starts them on new port numbers if the local listener is up. If the local listener is not up, restart the listener after updating the port numbers.

See Also:

Chapter 28, "Accessing the Repository using Protocols" for information about configuring protocols
Post-installation

Oracle XML DB uses dynamic protocol registration to set up FTP and HTTP listener services with the local listener. Ensure that the listener is up when you access Oracle XML DB protocols.

Note:

If the listener is running on a port that is not standard (for example, not 1521), then, in order for the protocols to register with the correct listener, the init.ora file must contain a local_listener entry. This references a TNSNAME entry that points to the correct listener. After editing the init.ora parameter, you must regenerate the SPFILE entry using CREATE SPFILE.

Installing Oracle XML DB Manually without DBCA

You can install Oracle XML DB manually, by running the catqm SQL script in directory rdbms/admin as database user SYS. Before running the script, you must install the database. If you expect Oracle XML DB Repository to contain a large amount of data, then you might also want to create a separate tablespace for Oracle XML DB.

Here is the syntax for catqm, where:

  • xdb_password is the password

  • xdb_ts_name is the tablespace to use for Oracle XML DB

  • temp_ts_name is the temporary tablespace

  • secure_file_for_repo is YES or NO (uppercase), YES meaning to use SecureFile LOB storage for Oracle XML DB Repository

catqm.sql xdb_password xdb_ts_name temp_ts_name secure_file_for_repos

For example:

catqm.sql change_on_install SYSAUX TEMP YES

Note:

  • SecureFile LOB storage can be created only in a tablespace that uses automatic segment space management. See Oracle Database Administrator's Guide.

  • Database compatibility must be 11.0.0.0 or greater, in order to use SecureFile LOB storage.

Post-Installation

After the manual installation, carry out these tasks:

  1. Add the following dispatcher entry to the init.ora file:

    dispatchers="(PROTOCOL=TCP) (SERVICE=<sid>XDB)"
    
  2. Restart the database and the listener to enable Oracle XML DB protocol access.

See Also:

"Anonymous Access to Oracle XML DB Repository using HTTP" for information about allowing unauthenticated access to the repository

Upgrading an Existing Oracle XML DB Installation

The following considerations apply to all upgrades to Oracle Database 11g:

  • Run script catproc.sql, as always.

  • As a post-upgrade step, if you want Oracle XML DB functionality, then you must install Oracle XML DB manually as described in "Installing Oracle XML DB Manually without DBCA".

  • ACL security: In releases prior to Oracle Database 11g Release 1, conflicts among ACEs for the same principal and same privilege were resolved by giving priority to any ACE that had child deny, whether or not preceding ACEs had child grant, that is, ACE order did not matter. In Oracle Database 11g this deny-trumps-grant behavior is still available, but it is not the default behavior.

See Also:

"ACL and ACE Evaluation" for information about conflicts among ACEs

Validation of ACL Documents and Configuration File

Access control list (ACL) documents are stored in table XDB$ACL. The Oracle XML DB configuration file, xdbconfig.xml, is stored in table XDB$CONFIG. Starting with Oracle Database 11g Release 1, these tables use the post-parse (binary XML) storage model. This implies that ACL documents and the configuration file are fully validated against their respective XML schemas. Validation takes place during upgrade, using your existing ACL documents and configuration file and the corresponding existing XML schemas.

If an ACL document fails to validate during upgrade, then the document is moved to table XDB$INVALID_ACL.

If validation of configuration file xdbconfig.xml fails during upgrade, then the file is saved in table XDB$INVALID_CONFIG, the default configuration file replaces it in table XDB$CONFIG, and the XDB component of the database is marked invalid. You must then start the database in normal mode and fix the XDB component, before trying to use the database.

To fix the XDB component, you can fix the invalid files to make them valid, and then call PL/SQL procedure RecoverUpgrade. After validating, this procedure moves the fixed files to tables XDB$ACL and XDB$CONFIG, and marks the XDB component valid.

As an option, you can call procedure RecoverUpgrade with parameter use_default set to TRUE, to abandon any invalid files. In this case, any valid files are moved to tables XDB$ACL and XDB$CONFIG, and any remaining invalid files are deleted. Default files are used in place of any invalid files. For ACLs, the default ACL document is used. For the configuration file, the default xdbconfig.xml is used (in which ACE order matters).

Caution:

Use a TRUE value for parameter use_default only if you are certain that you no longer need the old ACL files or configuration file that are invalid. These files are deleted.

Administering Oracle XML DB using Oracle Enterprise Manager

Oracle Enterprise Manager is a graphical tool supplied with Oracle Database that lets you perform database administration tasks easily. You can use it to perform the following tasks related to Oracle XML DB:

  • Configure Oracle XML DB. View or edit parameters for the Oracle XML DB configuration file, /xdbconfig.xml.

    For information about configuring Oracle XML DB without using Oracle Enterprise Manager, see "Configuring Oracle XML DB using xdbconfig.xml".

  • Search, create, edit, undelete Oracle XML DB Repository resources and their associated access control lists (ACLs).

    For information about creating and managing resources without using Oracle Enterprise Manager, see Part V, "Oracle XML DB Repository".

  • Search, create, edit, and delete XMLType tables and views.

  • Search, create, register, and delete XML schemas.

    For information about manipulating XML schemas without using Oracle Enterprise Manager, see Chapter 7, "XML Schema Storage and Query: Basic".

  • Create function-based indexes based on XPath expressions.

    For information about creating function-based indexes without using Oracle Enterprise Manager, see Chapter 6, "Indexing XMLType Data".

See Also:

The online help available with Oracle Enterprise Manager, for information about using Enterprise Manager to perform these tasks

Configuring Oracle XML DB using xdbconfig.xml

Oracle XML DB is managed internally through a configuration file, /xdbconfig.xml, which is stored as a resource in Oracle XML DB Repository. As an alternative to using Oracle Enterprise Manager to configure Oracle XML DB, you can configure it directly using the Oracle XML DB configuration file.

The configuration file can be modified at run time. Updating the configuration file creates a new version of this repository resource. At the start of each session, the current version of the configuration file is bound to that session. The session uses this configuration-file version for its duration, unless you make an explicit call to refresh the session to the latest version.

Oracle XML DB Configuration File, xdbconfig.xml

The configuration of Oracle XML DB is defined and stored in an Oracle XML DB Repository resource, /xdbconfig.xml, which conforms to the Oracle XML DB configuration XML schema: http://xmlns.oracle.com/xdb/xdbconfig.xsd. To configure or reconfigure Oracle XML DB, update file /xdbconfig.xml. Its structure is described in the following sections. You need administrator privileges to access file /xdbconfig.xml.

See Also:

"xdbconfig.xsd: XML Schema for Configuring Oracle XML DB" for a complete listing of the Oracle XML DB configuration XML schema

<xdbconfig> (Top-Level Element)

Element <xdbconfig> is the top-level element. Its structure is as follows:

<xdbconfig> 
    <sysconfig> ... </sysconfig> 
    <userconfig> ... </userconfig> 
</xdbconfig>

Element <sysconfig> defines system-specific, built-in parameters. Element <userconfig> lets you store new custom parameters.

<sysconfig> (Child of <xdbconfig>)

Element <sysconfig> is a child of <xdbconfig>. Its structure is as follows:

<sysconfig> 
    general parameters
    <protocolconfig> ... </protocolconfig> 
</sysconfig> 

Element <sysconfig> includes as content several general parameters that apply to all of Oracle XML DB, such as the maximum age of an access control list (ACL) and whether or not Oracle XML DB is case sensitive. Child <protocolconfig> contains protocol-specific parameters.

<userconfig> (Child of <xdbconfig>)

Element <userconfig> is a child of <xdbconfig>. It contains any parameters that you may want to add.

<protocolconfig> (Child of <sysconfig>)

Element <protocolconfig> is a child of <sysconfig>. Its structure is as follows:

<protocolconfig> 
  <common> ... </common> 
  <ftpconfig> ... </ftpconfig> 
  <httpconfig> ... </httpconfig> </protocolconfig> 

Under <common>, Oracle Database stores parameters that apply to all protocols, such as MIME-type information. Parameters that are specific to protocols FTP and HTTP(S) are in elements <ftpconfig> and <httpconfig>, respectively.

See Also:

Chapter 28, "Accessing the Repository using Protocols", Table 28-1, Table 28-2, and Table 28-3, for a list of protocol configuration parameters

<httpconfig> (Child of <protocolconfig>)

Element <httpconfig> is a child of <protocolconfig>. Its structure is as follows:

<httpconfig>
  ...
  <webappconfig>
    ...
    <servletconfig>
      ...
      <servlet-list>
        <servlet> ... </servlet>
        ...
      </servlet-list>
    </servletconfig>
  </webappconfig>
  ...
  <plsql> ... </plsql>
</httpconfig>

Element <httpconfig> has the following child elements, in addition to others:

  • <webappconfig> – used to configure Web-based applications. This includes Web application-specific parameters, such as icon name, display name for the application, and a list of servlets.

    Element <servletconfig> is a child of <webappconfig> that is used to define servlets. It has child <servlet-list>, which has child <servlet> (see "<servlet> (Descendant of <httpconfig>)").

  • <plsql>Foot 1  – used to define global configuration parameters when configuring the embedded PL/SQL gateway. Each global parameter is defined with a child element of <plsql>. The element name is the same as the global parameter name. The element content is the same as the parameter value.

    The recommended way to configure the embedded PL/SQL gateway is to use the procedures in PL/SQL package DBMS_EPG, not to edit file xdbconfig.xml.

See Also:

<servlet> (Descendant of <httpconfig>)

An optional <plsql> element, child of <servlet>, configures the embedded PL/SQL gateway servlet. However, the recommended way to configure the embedded gateway is to use the procedures in PL/SQL package DBMS_EPG, not to edit file xdbconfig.xml.

Element <plsql> has a child element for each embedded PL/SQL DAD attributeFoot 2  that is needed to configure the embedded gateway. All such children are optional. The element name is the same as the DAD attribute name. The element content is the same as the DAD-attribute value.

Element <servlet> is a descendent of <httpconfig> – see "<httpconfig> (Child of <protocolconfig>)". It is used to configure servlets, including Java servlets and embedded PL/SQL gateway servlets.

See Also:

Oracle XML DB Configuration File Example

The following is a sample Oracle XML DB configuration file:

Example 34-1 Oracle XML DB Configuration File

<xdbconfig xmlns="http://xmlns.oracle.com/xdb/xdbconfig.xsd" 
                 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                 xsi:schemaLocation="http://xmlns.oracle.com/xdb/xdbconfig.xsd 
                                    http://xmlns.oracle.com/xdb/xdbconfig.xsd">
   <sysconfig>
      <acl-max-age>900</acl-max-age>
      <acl-cache-size>32</acl-cache-size> 
      <invalid-pathname-chars>,</invalid-pathname-chars>
      <case-sensitive>true</case-sensitive>       
      <call-timeout>300</call-timeout>
      <max-link-queue>65536</max-link-queue> 
      <max-session-use>100</max-session-use>
      <persistent-sessions>false</persistent-sessions> 
      <default-lock-timeout>3600</default-lock-timeout>
      <xdbcore-logfile-path>/sys/log/xdblog.xml</xdbcore-logfile-path>
      <xdbcore-log-level>0</xdbcore-log-level>
      <resource-view-cache-size>1048576</resource-view-cache-size> 
    
      <protocolconfig> 
          <common>
             <extension-mappings>
                <mime-mappings>
                  <mime-mapping>
                    <extension>au</extension>
                    <mime-type>audio/basic</mime-type>
                  </mime-mapping>
                  <mime-mapping>
                    <extension>avi</extension>
                    <mime-type>video/x-msvideo</mime-type>
                  </mime-mapping>
                  <mime-mapping>
                    <extension>bin</extension>
                    <mime-type>application/octet-stream</mime-type>
                  </mime-mapping>
                </mime-mappings> 

                <lang-mappings>
                  <lang-mapping>
                    <extension>en</extension>
                    <lang>english</lang>
                  </lang-mapping>
                </lang-mappings>

                <charset-mappings>
                </charset-mappings>

                <encoding-mappings>
                  <encoding-mapping>
                    <extension>gzip</extension>
                    <encoding>zip file</encoding>      
                  </encoding-mapping>
                  <encoding-mapping>
                    <extension>tar</extension>
                    <encoding>tar file</encoding>        
                  </encoding-mapping>
                </encoding-mappings>
             </extension-mappings>

             <session-pool-size>50</session-pool-size>
             <session-timeout>6000</session-timeout>
          </common>

          <ftpconfig>
            <ftp-port>2100</ftp-port>
            <ftp-listener>local_listener</ftp-listener>
            <ftp-protocol>tcp</ftp-protocol>
            <logfile-path>/sys/log/ftplog.xml</logfile-path>
            <log-level>0</log-level>
            <session-timeout>6000</session-timeout>
            <buffer-size>8192</buffer-size> 
          </ftpconfig>

          <httpconfig>
            <http-port>8080</http-port>
            <http-listener>local_listener</http-listener>
            <http-protocol>tcp</http-protocol>
            <max-http-headers>64</max-http-headers> 
            <session-timeout>6000</session-timeout>
            <server-name>XDB HTTP Server</server-name>
            <max-header-size>16384</max-header-size>
            <max-request-body>2000000000</max-request-body>
            <logfile-path>/sys/log/httplog.xml</logfile-path>
            <log-level>0</log-level>    
            <servlet-realm>Basic realm="XDB"</servlet-realm>
            <webappconfig>
              <welcome-file-list>
                <welcome-file>index.html</welcome-file>
                <welcome-file>index.htm</welcome-file>
              </welcome-file-list>
              <error-pages>
              </error-pages>
              <servletconfig> 
                <servlet-mappings>
                  <servlet-mapping>
                    <servlet-pattern>/oradb/*</servlet-pattern>
                    <servlet-name>DBURIServlet</servlet-name>
                  </servlet-mapping>
                </servlet-mappings>
                               
                <servlet-list>
                  <servlet>
                    <servlet-name>DBURIServlet</servlet-name>
                    <display-name>DBURI</display-name>
                    <servlet-language>C</servlet-language>
                    <description>Servlet for accessing DBURIs</description>
                    <security-role-ref>
                      <role-name>authenticatedUser</role-name>
                      <role-link>authenticatedUser</role-link>
                    </security-role-ref>
                  </servlet>
                </servlet-list>
              </servletconfig>
            </webappconfig>
          </httpconfig> 
      </protocolconfig>
    <xdbcore-xobmem-bound>1024</xdbcore-xobmem-bound> 
    <xdbcore-loadableunit-size>16</xdbcore-loadableunit-size> 
   </sysconfig>
</xdbconfig>

Oracle XML DB Configuration API

You can access the Oracle XML DB configuration file, xdbconfig.xml, the same way you access any other XML schema-based resource in the hierarchy. It can be accessed using FTP, HTTP(S), WebDAV, Oracle Enterprise Manager, or any of the resource and Document Object Model (DOM) APIs for Java, PL/SQL, or C (OCI).

For convenience, you can use PL/SQL package DBMS_XDB package for configuration access. It exposes the following functions and procedures:

  • cfg_get – Returns the configuration information for the current session.

  • cfg_refresh – Refreshes the session configuration information using the current configuration file. Typical uses of cfg_refresh include the following:

    • You have modified the configuration and now want the session to pick up the latest version of the configuration information.

    • It has been a long running session, the configuration has been modified by a concurrent session, and you want the current session to pick up the latest version of the configuration information.

  • cfg_update – Updates the configuration information, writing the configuration file. A COMMIT is performed.

Example 34-2 updates parameters ftp-port and http-port in the configuration file.

Example 34-2 Updating the Configuration File using CFG_UPDATE and CFG_GET

DECLARE
  v_cfg XMLType;
BEGIN
  SELECT updateXML(DBMS_XDB.cfg_get(), 
                   '/xdbconfig/descendant::ftp-port/text()',
                   '2121', 
                   '/xdbconfig/descendant::http-port/text()', 
                   '19090')
    INTO v_cfg FROM DUAL;
  DBMS_XDB.cfg_update(v_cfg);
  COMMIT; 
END;
/ 

If you have many parameters to update, then it can be easier to use FTP, HTTP(S), or Oracle Enterprise Manager to update the configuration.

Configuring Default Namespace to Schema Location Mappings

Oracle XML DB identifies schema-based XMLType instances by pre-parsing the input XML document. If the appropriate xsi:schemaLocation or xsi:noNamespaceSchemaLocation attribute is found, then the specified schema location URL is used to consult the registered schema. If the appropriate xsi: attribute is not found, the XML document is considered to be non-schema-based.Oracle XML DB provides a mechanism to configure default schema location mappings. If the appropriate xsi: attribute is not specified in the XML document, the default schema location mappings is used. Element schemaLocation-mappings of the Oracle XML DB configuration XML schema, xdbconfig.xsd, can be used to specify the mapping between (namespace, element) pairs and the default schema location. If the element value is empty, the mapping applies to all global elements in the specified namespace. If the namespace value is empty, it corresponds to the null namespace.

The definition of the schemaLocation-mappings element is as follows:

 <element name="schemaLocation-mappings"
          type="xdbc:schemaLocation-mapping-type" minOccurs="0"/> 
 <complexType name="schemaLocation-mapping-type"><sequence>
      <element name="schemaLocation-mapping"
               minOccurs="0" maxOccurs="unbounded">
      <complexType><sequence>
        <element name="namespace" type="string"/>
        <element name="element" type="string"/>
        <element name="schemaURL" type="string"/>
      </sequence></complexType>
      </element></sequence> 
 </complexType> 

The schema location used depends on mappings in the Oracle XML DB configuration file for the namespace used and the root document element. For example, assume that the document does not have the appropriate xsi: attribute to indicate the schema location. Consider a document root element R in namespace N. The algorithm for identifying the default schema location is as follows:

  1. If the Oracle XML DB configuration file has a mapping for N and R, the corresponding schema location is used.

  2. If the configuration file has a mapping for N, but not R, the schema location for N is used.

  3. If the document root R does not have any namespace, the schema location for R is used.

For example, suppose that your Oracle XML DB configuration file includes the following mapping:

      <schemaLocation-mappings>
         <schemaLocation-mapping>
            <namespace>http://www.oracle.com/example</namespace>
            <element>root</element>
            <schemaURL>http://www.oracle.com/example/sch.xsd</schemaURL>
         </schemaLocation-mapping>
         <schemaLocation-mapping>
            <namespace>http://www.oracle.com/example2</namespace>
            <element></element>
            <schemaURL>http://www.oracle.com/example2/sch.xsd</schemaURL>
         </schemaLocation-mapping>
         <schemaLocation-mapping>
           <namespace></namespace>
           <element>specialRoot</element>
           <schemaURL>http://www.oracle.com/example3/sch.xsd</schemaURL>
         </schemaLocation-mapping>
      </schemaLocation-mappings>
 

The following schema locations are used:

  • Root element = root

    • Namespace = http://www.oracle.com/example

    • Schema URL = http://www.oracle.com/example/sch.xsd

    This mapping is used when the instance document specifies:

    <root xmlns="http://www.oracle.com/example/">
    
  • Root element = null (any global element in the namespace)

    • Namespace = http://www.oracle.com/example2

    • Schema URL = http://www.oracle.com/example2/sch.xsd

    This mapping is used when the instance document specifies:

    <root xmlns="http://www.oracle.example2">
    
  • Root element = specialRoot

    • Namespace = null (i.e null namespace)

    • Schema URL = http://www.oracle.com/example3/sch.xsd

    This mapping is used when the instance document specifies:

    <specialRoot>
    

Note:

This functionality is available only on the server side, that is, when XML is parsed on the server. If XML is parsed on the client side, the appropriate xsi: attribute is still required.

Configuring XML File Extensions

Oracle XML DB Repository treats certain files as XML documents, based on their file extensions. When such files are inserted into the repository, Oracle XML DB pre-parses them to identify the schema location (or uses the default mapping if present) and inserts the document into the appropriate default table. By default, the following extensions are considered as XML file extensions: xml, xsd, xsl, xlt. In addition, Oracle XML DB provides a mechanism for applications to specify other file extensions as XML file extensions. The xml-extensions element is defined in the configuration schema, http://xmlns.oracle.com/xdb/xdbconfig.xsd, as follows:

 <element name="xml-extensions"
          type="xdbc:xml-extension-type" minOccurs="0"/> 
 
 <complexType name="xml-extension-type"><sequence>
      <element name="extension" type="xdbc:exttype"
               minOccurs="0" maxOccurs="unbounded">
      </element></sequence> 
  </complexType> 

For example, the following fragment from the Oracle XML DB configuration file, xdbconfig.xml, specifies that files with extensions vsd, vml, and svgl should be treated as XML files:

 <xml-extensions>
   <extension>vsd</extension>
   <extension>vml</extension>
   <extension>svgl</extension>
 </xml-extensions>

Package DBMS_XDB_ADMIN

Table 34-1 describes DBMS_XDB_ADMIN PL/SQL procedures for managing and configuring Oracle XML DB and Oracle XML DB Repository.

Table 34-1 DBMS_XDB_ADMIN Management Procedures

Function/Procedure Description

moveXDB_tablespace

Move database schema XDB to the specified tablespace.

rebuildHierarchicalIndex

Rebuild the hierarchical repository index. This can be needed from time to time, in particular after invoking moveXDB_tablespace.


Note:

In a default, general-purpose database, where database schema XDB is in tablespace SYSAUX, you must use DBMS_XDB_ADMIN.moveXDB_tablespace before performing a full database export. A full database export does not export data from tablespaces SYSTEM or SYSAUX.

Note:

Prior to Oracle Database 11g Release 2 (11.2.0.3), these procedures belonged to PL/SQL package DBMS_XDB. These two procedures in package DBMS_XDB are deprecated as of release 11.2.0.3.


Footnote Legend

Footnote 1: There are two different <plsql> elements that are used to configure the embedded PL/SQL gateway. One, a child of <httpconfig>, defines global parameters. The other, a child of <servlet>, defines DAD attributes.
Footnote 2: DAD is an abbreviation for Database Access Descriptor. DAD attributes are parameters that define such a descriptor.