This chapter describes how to administer Oracle XML DB. It includes information on installing, upgrading, and configuring Oracle XML DB.
This chapter contains these topics:
You are required to install Oracle XML DB manually under the following conditions:
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".
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(S), 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(S), and WebDAV
You can store data in tables outside this tablespace and access the data through Oracle XML DB Repository by having REF
s to that data stored in the tables in this tablespace.
Caution:
The Oracle XML DB tablespace should not be dropped. If dropped, then it renders all Oracle XML DB Repository data inaccessible.See Also:
"Anonymous Access to Oracle XML DB Repository using HTTP" for information on allowing unauthenticated access to the repositoryOracle XML DB installation, includes a dynamic protocol registration that 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
To change FTP and HTTP(S) port numbers, update the tags <ftp-port>
, <http-port>
, and <http2-port>
in file /xdbconfig.xml
in the 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 local Listener is not up, restart the Listener after updating the port numbers.
See Also:
Chapter 25, "FTP, HTTP(S), and WebDAV Access to Repository Data" for information on configuring protocolsAs 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.
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, theinit.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
.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 Oracle 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
Note:
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:
Add the following dispatcher entry to the init.ora
file:
dispatchers="(PROTOCOL=TCP) (SERVICE=<sid>XDB)"
Restart the database and listener to enable Oracle XML DB protocol access.
See Also:
"Anonymous Access to Oracle XML DB Repository using HTTP" for information on allowing unauthenticated access to the repositoryCaution:
All user data stored in Oracle XML DB Repository is lost if you drop userXDB
.To reinstall Oracle XML DB follow these steps:
Remove the dispatcher by removing the Oracle 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='*';
Drop user XDB
and tablespace XDB
by connecting to SYS
and running the following SQL script:
@?/rdbms/admin/catnoqm.sql ALTER TABLESPACE <XDB_TS_NAME> offline; DROP TABLESPACE <XDB_TS_NAME> including contents;
Re-create tablespace XDB
.
Execute catnoqm.sql
.
Shut down, then restart the database instance.
Execute catqm.sql
.
Execute catxdbj.sql
.
Install Oracle XML DB manually as described in "Installing Oracle XML DB Manually Without DBCA".
The following considerations apply to all upgrades to Oracle Database 10g:
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".
Any upgrade to Oracle Database 10g Release 2 (10.2) uses the default value (false
) for configuration parameter allow-repository-anonymous-access
, meaning that unauthenticated access to Oracle XML DB Repository is blocked.
See Also:
"Anonymous Access to Oracle XML DB Repository using HTTP" for information on enabling unauthenticated access to Oracle XML DB Repository
"Formatting of XML Dates and Timestamps" for information on the different treatment of XML dates and timestamps in Oracle XML DB starting with release 10gR2
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.
Note:
In Oracle Database 10g, configuration of Oracle XML DB is validated against the configuration XML schema,http://xmlns.oracle.com/xdb/xdbconfig.xsd
. Existing, invalid configuration documents must be validated before upgrading to release 10g.See Also:
Oracle Database Upgrade Guide for details about using Database Upgrade AssistantIn 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.
This section applies only to the upgrade of an existing Oracle9i release 2 (9.2) database with Oracle XML DB where the LCR XML schema has been loaded. It applies if you upgrade directly from 9.2 to Oracle Database 10g (either 10.1 or 10.2). It does not apply if you have previously upgraded from 9.2 to 10.1 and are now upgrading from 10.1 to 10.2.
Use this query to check if your 9.2 database has the LCR XML schema loaded:
SELECT count(*) FROM XDB.XDB$SCHEMA s WHERE s.xmldata.schema_url = 'http://xmlns.oracle.com/streams/schemas/lcr/streamslcr.xsd';
If this query returns 0
, the existing LCR XML schema is not registered, and you can skip the rest of this section.
As part of the upgrade process, an existing LCR XML schema is dropped (through a call to PL/SQL procedure DBMS_XMLSCHEMA.deleteSchema
), and the new version of the LCR XML schema is registered. The call to deleteSchema
fails if the LCR XML schema has any dependent objects. These objects could be XMLType
XML schema-based tables, columns, or other XML schemas that reference the LCR XML schema.
If the deleteSchema
call succeeds and the new XML schema is registered, no further action is required to upgrade the XML LCR schema. You can determine whether or not the new schema was successfully registered by running this query:
SELECT count(*) FROM XDB.XDB$ELEMENT e, XDB.XDB$SCHEMA s WHERE s.xmldata.schema_url = 'http://xmlns.oracle.com/streams/schemas/lcr/streamslcr.xsd' AND ref(s) = e.xmldata.property.parent_schema AND e.xmldata.property.name = 'extra_attribute_values';
If this query returns 1
, then no further action is required: the database has the most current version of the LCR XML schema. You can skip the rest of this section.
If the query returns 0
, then the LCR XML schema upgrade failed because of objects that depend on the schema. You need to upgrade the LCR XML schema and its dependent objects using the copyEvolve
procedure available in the Oracle Database 10g version of Oracle XML DB, as follows:
Set event 22830
to level 8
your Oracle Database 10g database session.
Call PL/SQL procedure DBMS_XMLSCHEMA.copyEvolve
. See Chapter 8, "XML Schema Evolution" for details.
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 on configuring Oracle XML DB without using Oracle Enterprise Manager, see "Configuring Oracle XML DB Using xdbconfig.xml".
Search, create, edit, and delete Oracle XML DB Repository resources and their associated access-control lists (ACLs).
For information on creating and managing resources without using Oracle Enterprise Manager, see Part V, "Oracle XML DB Repository: Foldering, Security, and Protocols".
Search, create, edit, and delete XMLType
tables and views.
Search, create, register, and delete XML schemas.
For information on manipulating XML schemas without using Oracle Enterprise Manager, see Chapter 5, "XML Schema Storage and Query: Basic".
Create function-based indexes based on XPath expressions.
For information on creating function-based indexes without using Oracle Enterprise Manager, see "Creating Function-Based Indexes on XMLType Tables and Columns".
See Also:
The online help available with Oracle Enterprise Manager, for information on using Enterprise Manager to perform these tasksOracle 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 runtime. Simply 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.
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.
See Also:
"xdbconfig.xsd: XML Schema for Configuring Oracle XML DB" for a complete listing of the Oracle XML DB configuration XML schemaElement <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>
allows users to store new custom parameters.
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.
Element <userconfig>
is a child of <xdbconfig>
. It contains any parameters that you may want to add.
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 25, "FTP, HTTP(S), and WebDAV Access to Repository Data", Table 25-1, Table 25-2, and Table 25-3, for a list of protocol configuration parametersElement <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> (Descendent of <httpconfig>)").
<plsql>
– used in connection with Oracle HTML DB. This element is managed by PL/SQL package DBMS_EPG
and must not be changed by hand.
See Also:
%%% For 11g: Use conditionalized text (condition X) hidden now %%%
Chapter 25, "FTP, HTTP(S), and WebDAV Access to Repository Data", Table 25-1, Table 25-2, and Table 25-3, for a list of protocol configuration parameters
Oracle Database Application Developer's Guide - Fundamentals, for complete information on configuring and using the embedded PL/SQL gateway, including the available global parameters and their values
Oracle HTML DB User's Guide, for information on Oracle HTML DB
Oracle Database PL/SQL Packages and Types Reference, for information on package DBMS_EPG
Element <servlet>
is a descendent of <httpconfig>
– see "<httpconfig> (Child of <protocolconfig>)". It is used to configure servlets, including Java servlets.
An optional <plsql>
element, child of <servlet>
, is used in connection with Oracle HTML DB. It is managed by PL/SQL package DBMS_EPG
and must not be changed by hand.
See Also:
%%% For 11g: Use conditionalized text (condition X) hidden now %%%
Chapter 27, "Writing Oracle XML DB Applications in Java" for information on configuring Java servlets
Oracle Database Application Developer's Guide - Fundamentals, for complete information on configuring and using the embedded PL/SQL gateway, including the available DAD attributes and their values
Oracle HTML DB User's Guide, for information on Oracle HTML DB
Oracle Database PL/SQL Packages and Types Reference, for information on package DBMS_EPG
The following is a sample Oracle XML DB configuration file:
Example 28-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>
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, there is a PL/SQL API provided as part of the DBMS_XDB
package for configuration access. It exposes the following functions:
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 28-2 Updating the Configuration File Using cfg_update() and cfg_get()
This example updates parameters ftp-port
and http-port
in the configuration file.
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, rather than cfg_update
.
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, the specified schema location URL is used to lookup 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 will be 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:
If the Oracle XML DB configuration file has a mapping for N and R, the corresponding schema location is used.
If the configuration file has a mapping for N, but not R, the schema location for N is used.
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:
Namespace = http://www.oracle.com/example
Root Element = root
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/">
Namespace = http://www.oracle.com/example2
Root Element = null
(any global element in the namespace) Schema URL = http://www.oracle.com/example2/sch.xsd
This mapping is used when the instance document specifies:
<root xmlns="http://www.oracle.example2">
Namespace = null
(i.e null namespace) Root Element = specialRoot
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 appropriatexsi:
attribute is still required.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>