28 Administering Oracle XML DB

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

Oracle 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

Postinstallation

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.

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.

Upgrading an Existing LCR XML Schema

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:

1. Set event 22830 to level 8 your Oracle Database 10g database session.

2. Call PL/SQL procedure DBMS_XMLSCHEMA.copyEvolve. See Chapter 8, "XML Schema Evolution" for details.

<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> allows users to 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.

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

<servlet> (Descendent of <httpconfig>)

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.

Oracle XML DB Configuration File Example

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

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;
/ 

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, 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:

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:

• Namespace = http://www.oracle.com/exampleRoot Element = rootSchema 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/example2Root 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 = specialRootSchema URL = http://www.oracle.com/example3/sch.xsd

  This mapping is used when the instance document specifies:

  <specialRoot>
  

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>