22 Configuring Oracle XML DB Repository

This chapter describes how to configure Oracle XML DB Repository. It contains these topics:

Resource Configuration Files Configure a Resource
Configuring a Resource
Common Configuration Parameters

This chapter describes general configuration that applies to all repository resources. It does not describe configuration parameters for specific uses of resources. In particular, it does not describe configuration parameters for handling events or managing XLink and XInclude processing.

See Also:

Resource Configuration Files Configure a Resource

Resource configuration is a general mechanism that you can use for events, mime-type mappings, servlet parameters, XLink and XInclude processing, default ACL specifications, and more.

You configure a Oracle XML DB Repository resource for any purpose by associating it with a resource configuration file, which defines configurable parameters for the resource. A resource configuration file is an XML file that conforms to the XML schema XDBResConfig.xsd, which is accessible in Oracle XML DB Repository at path /sys/schemas/PUBLIC/xmlns.oracle.com/xdb/XDBResConfig.xsd. This XML schema is defined by Oracle XML DB, and you cannot alter it.

A resource configuration file is itself a resource in Oracle XML DB Repository. You use PL/SQL procedure DBMS_RESCONFIG.addResConfig to map a resource to the file that configures it. A single resource configuration file can alternatively apply to all resources in the repository. In that case, you use PL/SQL procedure DBMS_RESCONFIG.addRepositoryResConfig to map it to the repository as a whole.

The same resource configuration file can be used to configure more than one resource, if appropriate. Oracle recommends that you have resources share a configuration file this way whenever the same configuration makes sense. This can improve runtime performance. It also simplifies repository management by letting you update a configuration in a single place and have the change affect multiple resources.

Avoid creating multiple, equivalent resource configuration files, because that can impact performance negatively. If Oracle XML DB detects duplicate resource configuration files, it raises an error.

Typically, you configure a resource for use with a particular application. In order for a resource to be shared by multiple applications, it must be possible for different applications to configure it differently. You do this by creating multiple resource configuration files and mapping them to the same resource. Each resource is thus associated with a list of configurations, a resource configuration list. Configurations in a configuration list are processed in the list order.

The repository itself has a list of resource configuration files, for repository-wide configuration, which really means configuration of all resources in the repository. The same configuration file must not be used for both the repository itself and a specific resource; otherwise, an error is raised. An error is also raised if the same resource configuration file appears more than once in any given resource configuration list.

The resource configuration list of a new resource is based on the information in the configuration elements of all resource configuration files for the parent folder of the new resource. If there is no such information (no configuration file or no defaultChildConfig elements in the files), then the configuration elements of the repository resource configuration list are used. If that information is also missing, then the new resource has an empty resource configuration list.

You can view the configuration list for a particular resource by extracting element /Resource/RCList from column RES of view RESOURCE_VIEW, or by using PL/SQL procedure DBMS_RESCONFIG.getResConfigPath. You can view the configuration list for the repository as a whole by using PL/SQL procedure DBMS_RESCONFIG.getRepositoryResConfigPath. To modify the repository-wide configuration list, you must be granted role XDBADMIN.

Configuring a Resource

Follow these steps to configure an Oracle XML DB Repository resource or the repository as a whole (all resources):

Create a resource configuration file that defines the configuration. This XML file must conform to XML schema XDBResConfig.xsd.
Add the resource configuration file to the repository as a resource in its own right: a configuration resource. You can use PL/SQL procedure DBMS_XDB.createResource to do this.
Map this configuration resource to the resources that it configures, or to the repository if it applies to all resources. Use PL/SQL procedure DBMS_RESCONFIG.addResConfig or DBMS_RESCONFIG.appendResConfig to map an individual resource. Use DBMS_RESCONFIG.addRepositoryResConfig to map the repository as a whole.
Commit.

Note:

Before performing any operation that uses a resource configuration file, you must perform a COMMIT operation. Until you do that, an ORA-22881 "dangling REF" error will be raised whenever you use the configuration file.

PL/SQL package DBMS_RESCONFIG provides additional procedures to delete a configuration from a configuration list, obtain a list of paths to configurations in a configuration list, and more.

Note:

If you delete a resource configuration file that is referenced by another resource, a dangling REF error will be raised whenever an attempt is made to access the configured resource.

See Also:

Example 22-1 for an example of a simple resource configuration file
"Configuring Repository Events" for complete examples of configuring resources
"XDBResConfig.xsd: XML Schema for Resource Configuration"
Oracle Database PL/SQL Packages and Types Reference for information about package DBMS_RESCONFIG

Common Configuration Parameters

This section describes commonly used configuration parameters, that is, elements in a configuration file. Parameters specific to particular types of configuration are described elsewhere.

Configuration Element ResConfig

The top-level element of a resource configuration file is ResConfig. Besides namespace and schemaLocation attributes, it can contain an optional enable attribute. Set the value of attribute enable to false to disable the resource configuration file, so that it has no effect on the resources mapped to it. This can be useful for debugging or disabling an application. The default value of enable, used if the attribute is not present, is true.

Configuration Element defaultChildConfig

This configuration element applies to folders only. It holds configuration information that you want to be applied to all child resources in the folder. Element defaultChildConfig has one or more configuration child elements, each of which defines a possible configuration for resources in the folder.

A configuration element has the following child elements:

pre-condition (optional) – This element specifies a condition that must be met before the resource configuration identified by the path element (see next) can be used as the default configuration. If element pre-condition is absent, then the resource configuration file targeted by path applies to all resources in the folder. That is, the precondition is treated as true.

A pre-condition element has an optional existsNode child element. An existsNode element has a required XPath child element and an optional namespace child element, both strings. These define an XPath 1.0 expression and a namespace, respectively, that are used to check the existence of a resource. If that resource exists, then the precondition is satisfied, so the resource configuration file identified by path is used as a default resource configuration file for all child resources in the folder. The first component of the XPath element must be Resource.

Note:
A complex XPath expression for element XPath can impact performance negatively.

If multiple configuration elements have true preconditions, then each of the resource configuration files identified by their associated path elements applies to all of the resources in the folder.
path (required) – This element specifies an absolute repository path to a resource configuration file that is to be used as the default configuration for a new resource whenever the precondition specified by element pre-condition is satisfied.

Typically, the value of the path element is a path to the current resource configuration file, that is, the file that contains the path element. Example 22-1 illustrates this, assuming that the resource configuration file is located at path /cm/app_rc.xml in the repository. In this example, the precondition is that there be a Resource node whose content is of type xml. When that precondition is met, the resource configuration file in Example 22-1 applies to all resources in same folder as the configuration file (/cm/app_rc.xml).

Example 22-1 Resource Configuration File

<ResConfig xmlns="http://xmlns.oracle.com/xdb/XDBResConfig.xsd"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://xmlns.oracle.com/xdb/XDBResConfig.xsd
                               http://xmlns.oracle.com/xdb/XDBResConfig.xsd">
  <defaultChildConfig>
    <configuration>
      <pre-condition>
        <existsNode>
          <XPath>/Resource[ContentType="xml"]</XPath>
        </existsNode>
      </pre-condition>
      <path>/cm/app_rc.xml<path>
    </configuration>
  </defaultChildConfig>
</ResConfig>

Configuration Element applicationData

You use element applicationData to store application-specific data. An application typically passes this data to an event handler when the handler is run. You can use any XML content that you want inside element applicationData. An event handler uses PL/SQL function DBMS_XEVENT.getApplicationData or Java function oracle.xdb.XMLType.getApplicationData to access the data in the applicationData of the resource configuration file for the event listener.

Example 22-2 shows an applicationData element for use with an Oracle Spatial application.

Example 22-2 applicationData Element

<applicationData>
  <spatial:data xmlns:spatial="http://oracle/cartridge/spatial.xsd">
    <spatial:xpos>5</spatial:xpos>
    <spatial:ypos>10</spatial:ypos>
  </spatial:data>
</applicationData>

See Also:

Oracle Database PL/SQL Packages and Types Reference for information about PL/SQL function DBMS_XEVENT.getApplicationData
Oracle Database XML Java API Reference, class XDBRepositoryEvent for information about Java function oracle.xdb.XMLType.getApplicationData
Example 30-1, "Resource Configuration File for Java Event Listeners With Preconditions" for an example of a resource configuration file for event listeners