Skip Headers

Oracle® XML DB Developer's Guide
10g Release 1 (10.1)

Part Number B10790-01
Go to Documentation Home
Go to Book List
Book List
Go to Table of Contents
Go to Index
Go to Master Index
Master Index
Go to Feedback page

Go to previous page
Go to next page
View PDF

A Installing and Configuring Oracle XML DB

This appendix describes how you install, reinstall, upgrade, manage, and configure Oracle XML DB.

This appendix contains these topics:

Installing Oracle XML DB

You are required to install Oracle XML DB under the following conditions:

Installing or Reinstalling Oracle XML DB From Scratch

You can perform a new installation of Oracle XML DB with or without Database Configuration Assistant (DBCA). If Oracle XML DB is already installed, complete the steps in "Reinstalling Oracle XML DB".

Installing a New Oracle XML DB With Database Configuration Assistant

Oracle XML DB is part of the seed database and 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 Oracle XML DB tablespace and FTP, HTTP, and WebDAV port numbers.

By default DBCA performs the following tasks during installation:

  • Creates an Oracle XML DB tablespace for Oracle XML DB Repository

  • Enables all protocol access

  • Configures FTP at port 2100

  • Configures HTTP/WebDAV at port 8080

The Oracle XML DB tablespace 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, and WebDAV

You can store data in tables outside this tablespace and access the data through the repository by having REFs to that data stored in the tables in this tablespace.


The Oracle XML DB tablespace should not be dropped. If dropped, then it renders all repository data inaccessible.

Dynamic Protocol Registration Registers FTP and HTTP Services with Local Listener

Oracle XML DB installation, includes a dynamic protocol registration that registers FTP and HTTP 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 Port Numbers

To change FTP or HTTP port numbers, update the tags <ftp-port> and <http-port> in file, /xdbconfig.xml in Oracle XML DB repository.

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

See Also:

Chapter 24, " FTP, HTTP, and WebDAV Access to Repository Data" for a description of how to update /xdbconfig.xml


As explained in the previous section, Oracle XML DB uses dynamic protocol registration to setup FTP and HTTP Listener services with the local Listener. So, make certain that the Listener is up when accessing Oracle XML DB protocols.

To allow for unauthenticated access to your Oracle XML DB repository data through HTTP, you must unlock the ANONYMOUS user account.


If the Listener is running on a non-standard port (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 a New Oracle XML DB Manually Without Database Configuration Assistant

After the database installation, you must run the following SQL scripts in rdbms/admin connecting to SYS to install Oracle XML DB after creating a new tablespace for Oracle XML DB repository. Here is the syntax for this:

catqm.sql <XDB_password> <XDB_TS_NAME> <TEMP_TS_NAME>
#Create the tables and views needed to run XML DB

For example:

catqm.sql change_on_install XDB TEMP

Reconnect to SYS again and run the following:

catxdbj.sql          #Load xdb java library


Make sure that the database is started with Oracle9i release 2 (9.2.0) compatibility or higher, and Java Virtual Machine (JVM) is installed.


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 listener to enable Oracle XML DB protocol access.

  3. To allow for unauthenticated access to your Oracle XML DB repository data through HTTP, you must also unlock the ANONYMOUS user account.

Reinstalling Oracle XML DB


All user data stored in Oracle XML DB repository is also lost when you drop user XDB!

To reinstall Oracle XML DB follow these steps:

  1. Remove the dispatcher by removing the XML DB dispatcher entry from the init.ora file as follows:

    dispatchers="(PROTOCOL=TCP) (SERVICE=<sid>XDB)"

    If the server parameter file is used, run the following command when the instance is up and while logged in as SYS:

    ALTER SYSTEM RESET dispatchers scope=spfile sid='*';
  2. Drop user XDB and tablespace XDB by connecting to SYS and running the following SQL script:

    DROP TABLESPACE <XDB_TS_NAME> including contents;
  3. Re-create tablespace XDB.

  4. Execute catnoqm.sql.

  5. Execute catqm.sql.

  6. Execute catxdbj.sql.

  7. Install Oracle XML DB manually as described in "Installing a New Oracle XML DB Manually Without Database Configuration Assistant".

Upgrading an Existing Oracle XML DB Installation

Run the 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 a New Oracle XML DB Manually Without Database Configuration Assistant".

Upgrading Oracle XML DB From Release 9.2 to 10g Release 1 (10.1)

All Oracle XML DB upgrade tasks are handled automatically when you use Database Upgrade Assistant to upgrade your database from any version of Oracle9i release 2 to Oracle Database 10g release 1 (10.1).


In 10g release 1 (10.1), Oracle XML DB configuration is validated against the schema. Therefore, existing, invalid configuration documents must be validated before upgrading to the new release.

See Also:

Oracle Database Upgrade Guide for details about using Database Upgrade Assistant

Privileges for Nested XMLType Tables When Upgrading to Oracle Database 10g

In Oracle9i release 2 (9.2), when you granted privileges on an XMLType table, they were not propagated to nested tables deeper than one level. In Oracle Database 10g, these privileges are propagated to all levels of nested tables.

When you upgrade from Oracle9i release 2 (9.2) to Oracle Database 10g with these nested tables, the corresponding nested tables (in Oracle Database 10g) will not have the right privileges propagated and users will not be able to access data from these tables. A typical error encountered is, ORA-00942:table or view not found. The workaround is to reexecute the original GRANT statement in Oracle Database 10g. This ensures that all privileges are propagated correctly.

Configuring Oracle XML DB

The following sections describe how to configure Oracle XML DB. You can also configure Oracle XML DB using Oracle Enterprise Manager.

Oracle XML DB is managed through a configuration resource stored in Oracle XML DB repository, /xdbconfig.xml.

The Oracle XML DB configuration file is alterable at runtime. Simply updating the configuration file, causes a new version of the file to be generated. At the start of each session, the current version of the configuration is bound to that session. The session will use this configuration for its life, unless you make an explicit call to refresh to the latest configuration.

Oracle XML DB Configuration File, xdbconfig.xml

Oracle XML DB configuration is stored as an XML resource, /xdbconfig.xml conforming to the Oracle XML DB configuration XML schema:

To configure or modify the configuration of Oracle XML DB, update the /xdbconfig.xml file by inserting, removing, or editing the appropriate XML elements in xdbconfig.xml.

Oracle XML DB configuration XML schema has the following structure:

Top Level Tag <xdbconfig>

A top level tag, <xdbconfig> is divided into two sections:

  • <sysconfig> This keeps system-specific, built-in parameters.

  • <userconfig> This allows users to store new custom parameters.

The following describes the syntax:

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


The <sysconfig> section is further subdivided as follows:

    General parameters
      <protocolconfig> ... </protocolconfig> 

It stores several general parameters that apply to all Oracle XML DB, for example, the maximum age of an access control list (ACL), whether Oracle XML DB should be case sensitive, and so on.

Protocol-specific parameters are grouped inside the <protocolconfig> tag.


The <userconfig> section contains any parameters that you may want to add.


The structure of the <protocolconfig> section is as follows:

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

Under <common> Oracle Database 10g stores parameters that apply to all protocols, such as MIME type information. There are also HTTP and FTP specific parameters under sections <httpconfig> and <ftpconfig> respectively.


Inside <httpconfig> there is a further subsection, <webappconfig> that corresponds to Web-based applications. It includes Web application specific parameters, for example, icon name, display name for the application, list of servlets in Oracle XML DB, and so on.

Oracle XML DB Configuration Example

The following is a sample Oracle XML DB configuration file:

Example A-1 Oracle XML DB Configuration File

<xdbconfig xmlns="" 



                    <encoding>zip file</encoding>      
                    <encoding>tar file</encoding>        



            <server-name>XDB HTTP Server</server-name>
            <servlet-realm>Basic realm="XDB"</servlet-realm>
                    <description>Servlet for accessing DBURIs</description>


Oracle XML DB Configuration API

The Oracle XML DB Configuration application program interface (API) can be accessed just like any other XML schema-based resource in the hierarchy. It can be accessed and manipulated using FTP, HTTP, WebDAV, Oracle Enterprise Manager, or any of the resource and Document Object Model (DOM) APIs for Java, PL/SQL, or C (OCI).

For convenience, there is a PL/SQL API provided as part of the DBMS_XDB package for configuration access. It exposes the following functions:

Get Configuration, cfg_get()

The cfg_get() function returns a copy of the configuration as an XMLType:


Update Configuration, cfg_update()

The cfg_update() function updates the configuration with a new one:


cfg_update() is auto-commit.

Example A-2 Updating the Configuration File Using cfg_update() and cfg_get()

If you have a few parameters to update in the configuration file, then you can use the following:

        /xdbconfig/descendant::ftp-port/text()',   '2121'), 

If you have many parameters to update, then the preceding example may prove too cumbersome. Use instead FTP, HTTP, or Oracle Enterprise Manager.

Refresh Configuration, cfg_refresh()

The cfg_refresh() function updates the configuration snapshot to correspond to the latest version on disk at that instant:


Typically, cfg_refresh() is called in one of the following scenarios:

  • 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.