|Oracle9i XML Database Developer's Guide - Oracle XML DB
Release 2 (9.2)
Part Number A96620-02
This appendix describes the ways you can manage and configure your Oracle XML DB applications. It contains the following sections:
You will need to install Oracle XML DB under the following conditions:
You can perform a new installation of Oracle XML DB with or without Database Configuration Assistant (DBCA):
Oracle XML DB is part of the seed database and installed by DBCA as part of database installation by default. No additional steps are required to install Oracle XML DB, however, if you choose to install "Customized" database, you can configure Oracle XML DB tablespace and FTP, HTTP, and WebDAV port numbers.
By default DBCA performs the following tasks:
The Oracle XML DB tablespace holds the data that is stored in Oracle XML DB Repository. This includes data that is stored in the Repository using:
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 it renders all Repository data inaccessible.
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:
To change FTP or HTTP port numbers, update the tags
<http-port> in file,
/xdbconfig.xml in Oracle XML DB Repository.
Chapter 19, "Using FTP, HTTP, and WebDAV Protocols" for a description of how to update
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.
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
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:
SYS again and run the following:
Make sure that the database is started with Oracle9i Release 2 (9.2.0) compatibility or higher.
After the manual installation, carry out these tasks:
To reinstall Oracle XML DB, run following SQL commands connecting to SYS to drop Oracle XML DB user and tablespace:
drop user xdb cascade; alter tablespace <XDB_TS_NAME> offline; drop tablespace <XDB_TS_NAME> including contents;
Install Oracle XML DB manually as described in "Installing a New Oracle XML DB Manually Without DBCA".
Run the script,
catproc.sql, as always.
As a post upgrade step, if you want Oracle XML DB functionality, you must install Oracle XML DB manually as described in "Installing a New Oracle XML DB Manually Without DBCA" .
Oracle9i Release 2 (184.108.40.206) patchset for the Oracle9i Release 2 (9.2) database is a required upgrade for users of Oracle XML DB Release 2 (220.127.116.11). Oracle XML DB requires schema based
XMLType tables and columns from release 18.104.22.168 to be migrated to release 22.214.171.124. This mandatory migration is done automatically as part of the database upgrade process. The migration is transparent except for a few restrictions.
At this point, Oracle XML DB is automatically upgraded and schema based XML data is migrated to a new format usable by the new release Oracle9i Release 2 (126.96.36.199). Verify that all components are valid and have been upgraded to the new release:
If you have the ability to restore all your XML schema and documents from scratch, Oracle strongly recommends that you uninstall XML DB before the upgrade, then reinstall XML DB and reload all data after the upgrade has succeeded. This approach has two benefits: the risk of an unsuccessful migration of the user's XML data is eliminated, and all optimizations coded into Release 2 (188.8.131.52) will be used to their fullest extent if the data is freshly loaded into the database post-migration rather than if it is migrated from the Release 2 (184.108.40.206) format.
If you are migrating your data, follow these important instructions:
You must back up all your XML schema-based data that is stored as object-relational. This minimizes any data-corruption during the migration process by deleting the corrupted rows and reloading the XML from scratch.
Also, before the upgrade, you must ensure that all XML schema-based
XMLType rows and columns stored as object-relational are schema-valid. In Release 2 (220.127.116.11), Oracle XML DB did not perform rigorous checks that an XML document being inserted into a table was valid against its XML schema. However, in Release 2 (18.104.22.168), certain aspects of data storage rely on the schema-validity of XML documents stored. For this reason, non-conforming XML documents stored using Release 2 (22.214.171.124) may not migrate to Release 2 (126.96.36.199).
There are two instances where an XML schema-based document cannot be migrated to Release 2 (188.8.131.52). If your data falls in either of these two categories, Oracle recommends that you do the following:
If you try to migrate data that falls under one of the two following categories, an error is logged in the trace file for each row that fails migration.
The first type of XML document that cannot be migrated is one whose XML schema contains the
anyType element. Due to storage limitations for
anyType in Release 2 (184.108.40.206), Oracle changed the storage format of
anyType in Release 2 (220.127.116.11) so that XML documents with one or more non-NULL
anyType element cannot be migrated.
The second type of XML document that cannot be migrated is one whose XML schema contains a subtyped element with a namespace that differs from the namespace of its parent element. This is because in Release 2 (18.104.22.168), Oracle XML DB required and assumed the namespace of the subtyped element to be that of its parent's namespace, and thus the real namespace of the subtyped element was lost during the storage phase. For this reason, you cannot migrate these XML schema, along with their conforming XML documents, to Release 2 (22.214.171.124).
The migration of
XMLType data happens transparently within the upgrade script
Errors occurring during Oracle XML DB migration are reported to the trace file, along with the table name and ROWID of the row for which the migration failed. If an error occurs during migration of a row, the migration script simply reports the error to the trace file and continues migrating the next row. In other words, the script is not interrupted by errors.
If all rows are successfully migrated, Oracle XML DB is ready to use once the database has been restarted.
If the trace file shows that errors occurred during migration of one or more
XMLType rows, the remainder of Oracle XML DB should remain usable despite the lack of completion. If you later try to access an non-migrated row, Oracle throws an ORA-1038 error. You can delete non-migrated rows from
XMLType tables without harm.
When a row is migrated and does not produce an error yet yields the row unusable after the upgrade is complete, you should delete the row then restore it using the raw XML data, assuming that a backup was taken prior to upgrade.
Even after upgrade, any
XMLType table, migrated or not, can be re-run through the migration engine. This may be useful when a particular
XMLType row fails to be migrated as a part of
catpatch.sql, but you have since taken some action to make the migration run successfully.
Table A-1 lists the migration procedures available from
XDB.DBMS_XDB package after upgrading to Release 2 (126.96.36.199).
MigrateColumnFrom9201(owner IN VARCHAR2, table_name IN VARCHAR2, column_name IN VARCHAR2)
MigrateTableFrom9201(owner IN VARCHAR2, table_name IN VARCHAR2);
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,
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 invoke an explicit call to refresh to the latest configuration.
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
Oracle XML DB configuration XML schema has the following structure:
A top level tag,
<xdbconfig> is divided into two sections:
The following describes the syntax:
<sysconfig> section is further subdivided as follows:
It stores several general parameters that apply to all Oracle XML DB, for example, the maximum age for an ACL, whether Oracle XML DB should be case sensitive, and so on.
Protocol-specific parameters are grouped inside the
<userconfig> section contains any parameters that you may want to add.
The structure of the
<protocolconfig> section is as follows:
<protocolconfig> <common> ... </common> <httpconfig> ... </httpconfig> <ftpconfig> ... </ftpconfig> </protocolconfig>
<common> Oracle9i stores parameters that apply to all protocols, such as MIME type information. There are also HTTP and FTP specific parameters under sections
<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.
The following is a sample 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> <invalid-pathname-chars>,</invalid-pathname-chars> <call-timeout>300</call-timeout> <max-session-use>100</max-session-use> <default-lock-timeout>3600</default-lock-timeout> <xdbcore-logfile-path>/sys/log/xdblog.xml</xdbcore-logfile-path> <xdbcore-log-level>1</xdbcore-log-level> <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> <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> </ftpconfig> <httpconfig> <http-port>8080</http-port> <http-listener>local_listener</http-listener> <http-protocol>tcp</http-protocol> <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> </sysconfig> <userconfig><numusers>40</numusers></userconfig> </xdbconfig>
The Oracle XML DB Configuration 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 DOM APIs for Java or PL/SQL.
For convenience, there is a PL/SQL API provided as part of the
DBMS_XDB package for configuration access. It exposes the following functions:
The cfg_get() function returns a copy of the configuration as an
cfg_get() is auto-commit.
The cfg_update() function updates the configuration with a new one:
If you have a few parameters to update in the configuration file, you can use the following:
BEGIN DBMS_XDB.CFG_UPDATE(UPDATEXML(UPDATEXML (DBMS_XDB.CFG_GET(), /xdbconfig/descendant::ftp-port/text()', '2121'), '/xdbconfig/descendant::http-port/text()', 19090')) END; /
If you have many parameters to update, the preceding example may prove too cumbersome. Use instead FTP, HTTP, or Oracle Enterprise Manager.
The cfg_refresh() function updates the configuration snapshot to correspond to the latest version on disk at that instant:
refresh() is called in one of the following scenarios:
Oracle9i XML API Reference - XDK and Oracle XML DB the chapter on