18 Accessing Oracle XML DB Repository Data

Introducing Oracle XML DB Foldering

Using the foldering feature in Oracle XML DB you can store content in the database in hierarchical structures, as opposed to traditional relational database structures.

Figure 18-1 is an example of a hierarchical structure that shows a typical tree of folders and files in Oracle XML DB repository. The top of the tree shows '/', the root folder.

Foldering allows applications to access hierarchically indexed content in the database using the FTP, HTTP, and WebDAV protocol standards as if the database content is stored in a file system.

This chapter provides an overview of how to access data in Oracle XML DB repository folders using the standard protocols. There are other APIs available in this release, which allow you to access the repository object hierarchy using Java, SQL, and PL/SQL.

Figure 18-1 A Typical Folder Tree Showing Hierarchical Structures in Oracle XML Repository

Description of the illustration adxdb004.gif

Oracle XML DB Repository

Oracle XML DB repository (repository) is the set of database objects, across all XML and database schemas, that are mapped to path names. It is a connected, directed, acyclic graph of resources with a single root node (/). Each resource in the graph has one or more associated path names.

The repository can be thought of as a file system of objects rather than files.

/public
/sys
/sys/acls
/sys/acls/all_all_acl.xml
/sys/acls/all_owner_acl.xml
/sys/acls/bootstrap_acl.xml
/sys/acls/ro_all_acl.xml
/sys/apps
/sys/log
/sys/schemas
/sys/schemas/PUBLIC
/sys/schemas/PUBLIC/www.w3.org
/sys/schemas/PUBLIC/www.w3.org/2001
/sys/schemas/PUBLIC/www.w3.org/2001/xml.xsd
/sys/schemas/PUBLIC/xmlns.oracle.com
/sys/schemas/PUBLIC/xmlns.oracle.com/xdb
/sys/schemas/PUBLIC/xmlns.oracle.com/xdb/XDBFolderListing.xsd
/sys/schemas/PUBLIC/xmlns.oracle.com/xdb/XDBResource.xsd
/sys/schemas/PUBLIC/xmlns.oracle.com/xdb/XDBSchema.xsd
/sys/schemas/PUBLIC/xmlns.oracle.com/xdb/XDBStandard.xsd
/sys/schemas/PUBLIC/xmlns.oracle.com/xdb/acl.xsd
/sys/schemas/PUBLIC/xmlns.oracle.com/xdb/dav.xsd
/sys/schemas/PUBLIC/xmlns.oracle.com/xdb/log
/sys/schemas/PUBLIC/xmlns.oracle.com/xdb/log/ftplog.xsd
/sys/schemas/PUBLIC/xmlns.oracle.com/xdb/log/httplog.xsd
/sys/schemas/PUBLIC/xmlns.oracle.com/xdb/log/xdblog.xsd
/sys/schemas/PUBLIC/xmlns.oracle.com/xdb/stats.xsd
/sys/schemas/PUBLIC/xmlns.oracle.com/xdb/xdbconfig.xsd
/xdbconfig.xml

Oracle XML DB Resources

Oracle XML DB resources conform to the xdbresource.xsd schema. This XML schema is defined by Oracle XML DB. The elements in a resource include those needed to persistently store WebDAV-defined properties, such as creation date, modification date, WebDAV locks, owner, ACL, language, and character set.

A resource index has a special element called Contents which contains the contents of the resource.

The XML schema for a resource also defines an any element, with maxoccurs unbounded, which allowed to contain any element outside the Oracle XML DB XML namespace. This way, arbitrary instance-defined properties can be associated with the resource.

Accessing Oracle XML DB Repository Resources

Oracle XML DB provides two techniques for accessing resources:

• "Navigational or Path Access". Navigational/or path access to content in Oracle XML DB is achieved using a hierarchical index of objects or resources. Each resource has one or more unique path names that reflect its location in the hierarchy. You can use navigational access to reference any object in the database without regard to its location in the tablespace.

• "Query-Based Access". SQL access to the repository is done using a set of views that expose resource properties and path names and map hierarchical access operators onto the Oracle XML DB schema.

Figure 18-2 illustrates Oracle XML DB data access options. A high level discussion of which data access option to select is described in Chapter 2, " Getting Started with Oracle XML DB", "Oracle XML DB Application Design: a. How Structured Is Your Data?".

Figure 18-2 Oracle XML DB Repository Data Access Options

Description of the illustration adxdb027.gif

A Uniform Resource Locator (URL) is used to access an Oracle XML DB resource. A URL includes the host name, protocol information, path name, and resource name of the object.

Navigational or Path Access

Oracle XML DB folders support the same protocol standards used by many operating systems. This allows an Oracle XML DB folder to function just like a native folder or directory in supported operating-system environments. For example, you can:

• Use Windows Explorer to open and access Oracle XML DB folders and resources the same way you access other directories or resources in the Windows NT file system, as shown in Figure 18-3.

• Access repository data using HTTP/WebDAV from an Internet Explorer browser, such as when viewing Web Folders, as shown in Figure 18-4.

Figure 18-3 Oracle XML DB Folders in Windows Explorer

Description of the illustration 4_xfoldr.jpg

Figure 18-4 Accessing Repository Data Using HTTP/WebDAV and Navigational Access From IE Browser: Viewing Web Folders

Description of the illustration 3_f_http.gif

Configuring Default Namespace to Schema Location Mappings

In general, 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. 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. The XDB Configuration Schema has an element "schemaLocation-mappings" that can be used to specify the mapping between (namespace, element) pairs and its 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 in the XDB configuration file <xdbconfig> 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 XDB 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 XDB 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, if your XDB 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

XML DB repository treats certain files as XML documents based on their file extensions. When such files are inserted into the repository, 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, XML DB provides a mechanism for applications to specify other file extensions as XML file extensions. The "xml-extensions" element is defined in the XDB Configuration schema 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 XDB 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>

Query-Based Access

Oracle XML DB provides two repository views to enable SQL access to repository data:

• PATH_VIEW

• RESOURCE_VIEW

Table 18-2 summarizes the differences between PATH_VIEW and RESOURCE_VIEW.

The single path in the RESOURCE_VIEW is arbitrarily chosen from among the many possible paths that refer to a resource. Oracle XML DB provides operators like UNDER_PATH that enable applications to search for resources contained (recursively) within a particular folder, get the resource depth, and so on. Each row in the views is of XMLType.

DML on the Oracle XML DB repository views can be used to insert, rename, delete, and update resource properties and contents. Programmatic APIs must be used for other operations, such as creating links to existing resources.

Accessing Repository Data Using Servlets

Oracle XML DB implements Java Servlet API, version 2.2, with the following exceptions:

• All servlets must be distributable. They must expect to run in different VMs.

• WAR and web.xml files are not supported. Oracle XML DB supports a subset of the XML configurations in this file. An XSL style sheet can be applied to the web.xml to generate servlet definitions. An external tool must be used to create database roles for those defined in the web.xml file.

• JSP (Java Server Pages) support can be installed as a servlet and configured manually.

• HTTPSession and related classes are not supported.

• Only one servlet context (that is, one Web application) is supported.

  
  

  See Also: Chapter 25, " Writing Oracle XML DB Applications in Java"

  
  

Accessing Data Stored in Oracle XML DB Repository Resources

The three main ways you can access data stored in Oracle XML DB repository resources are through:

• Oracle XML DB resource APIs for Java

• A combination of Oracle XML DB resource views API and Oracle XML DB resource API for PL/SQL

• Internet protocols (HTTP/WebDAV and FTP) and Oracle XML DB protocol server

Table 18-3 lists common Oracle XML DB repository operations and describes how these operations can be accomplished using each of the three methods. The table shows functionality common to three methods. Note that not all the methods are equally suited to a particular set of tasks.

Managing and Controlling Access to Resources

You can set access control privileges on Oracle XML DB folders and resources.

Setting and Accessing Custom Namespace Properties

Oracle XML DB resources declare a fixed set of metadata properties such as the Owner and CreationDate. You can specify values for these metadata attributes while creating or updating resources.

You can also store proprietary (custom) tags as extra metadata with resources, that is metadata properties that are not defined by the Resource XML schema. To do so, you must store the extra metadata as a CLOB in the ResExtra element.

Note that the default schema has a top-level any element (declared with maxOccurs= "unbounded"). This allows any valid XML data as part of the resource document and gets stored in the RESEXTRA CLOB column as shown in Example 18–1.

<Resource xmlns="http://xmlns.oracle.com/xdb/XDBResource.xsd"
         <Owner>SCOTT</Owner>
         ... <!-- other system defined metadata -->
        <!-- User Metadata (appearing within different namespace) -->
        <ResExtra>
           <myCustomAttrs xmlns="http://www.example.com/customattr">
                <attr1>value1</attr1>
                <attr2>value2</attr2>
           </myCustomAttrs>
          </ResExtra
         <!-- contents of the resource>
         <Contents>
             ...
          </Contents>
     </Resource>

You cannot extend the resource schema itself. However, you can set and access custom properties belonging to other namespaces (other than XDBResource.xsd) using DOM operations on the <RESOURCE> document. The following example shows some basic operations.

-- Utility function to append a (direct) child to given document
create or replace function appendChild(doc xmltype, child xmltype)
return xmltype as
  d dbms_xmldom.DOMDocument;
  c dbms_xmldom.DOMDocument;
  dn dbms_xmldom.DOMNode;
  cn dbms_xmldom.DOMNode;
begin
  d := dbms_xmldom.newDOMDocument(doc);
  dn := dbms_xmldom.makeNode(d);
  dn := dbms_xmldom.getFirstChild(dn);
 
  c := dbms_xmldom.newDOMDocument(child);
  cn := dbms_xmldom.makeNode(c);
  cn := dbms_xmldom.getFirstChild(cn);
  dn := dbms_xmldom.appendChild(dn, cn);
 
  return doc;
end;/
 
 
-- create a NSB resource
declare
ret boolean;
begin
ret := dbms_xdb.createresource('/public/foo1.txt', 'abc def');
end;/
 
commit;
 
-- update resource to set custom property <RANDOM> in foo namespace
-- Note : the custom properties should belong to a namespace other than
-- the XDBResource.xsd namespace
--
update resource_view
set res =
   appendChild(res, xmltype('<FOO:RANDOM xmlns:foo="foo">3456</FOO:RANDOM>'))
where any_path = '/public/foo1.txt';
commit;
 
-- select resource
select e.res.getclobval()
from resource_view e
where e.any_path = '/public/foo1.txt';
 
-- select custom property
select e.res.extract('/r:Resource/foo:random',
  'xmlns:r="http://xmlns.oracle.com/xdb/XDBResource.xsd"
   xmlns:foo="foo"').getstringval()
from resource_view e
where any_path = '/public/foo1.txt';
 
-- select custom property value
select e.res.extract('/r:Resource/foo:random/text()',
  'xmlns:r="http://xmlns.oracle.com/xdb/XDBResource.xsd"
   xmlns:foo="foo"').getstringval()
from resource_view e
where any_path = '/public/foo1.txt';