13
Oracle XML DB Foldering

This chapter describes how to access data in Oracle XML DB Repository using standard protocols such as FTP, HTTP/WebDAV and other Oracle XML DB Resource APIs. It also introduces you to using RESOURCE_VIEW and PATH_VIEW as the SQL mechanism for accessing and manipulating Repository data. It includes a table for comparing Repository operations through the various Resource APIs.

This chapter contains the following sections:

• Introducing Oracle XML DB Foldering
• Oracle XML DB Repository
• Oracle XML DB Resources
• Accessing Oracle XML DB Repository Resources
• Navigational or Path Access
• Query-Based Access
• Accessing Repository Data Using Servlets
• Accessing Data Stored in Oracle XML DB Repository Resources
• Managing and Controlling Access to Resources
• Extending Resource Metadata Properties
• Frequently Asked Questions (FAQs): XML DB Repository

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 13-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 13-1 A Typical Folder Tree Showing Hierarchical Structures in Oracle XML Repository

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

Repository Terminology

The following lists describes terms used in Oracle XML DB Repository:

• Resource: A resource is any object or node in the hierarchy. Resources are identified by URLs. See "Oracle XML DB Resources".
• Folder: A folder is a node (or directory) in the hierarchy that can contain a collection of resources. A folder is also a resource.
• Pathname: A hierarchical name composed of a root element (the first /), element separators /, and various subelements (or path elements). A path element may be composed of any character in the database character set except \ and /, which have special meanings in Oracle XML DB. The forward slash is the default name separator in a path name, and the backward slash is used to escape characters. The Oracle XML DB configuration file xdbconfig.xml also contains a list of user-defined characters that may not appear within a path name (<invalid-pathname-chars>).
• Resource or Link name: The name of a resource within its parent folder. Resource names must be unique (case-sensitive in this release) within a folder. Resource names are always in the UTF8 character set (NVARCHAR).
• Contents: The body of a resource, what you get when you treat the resource like a file and ask for its contents. Contents is always an XMLType.
• XDBBinary: An XML element defined by the Oracle XML DB schema that contains binary data. XDBBinary elements are stored in the Repository when unstructured binary data is uploaded into Oracle XML DB.
• Access Control List (ACL): Restricts access to a resource or resources. Oracle XML DB uses ACLs to restrict access to any Oracle XML DB resource (any XMLType object that is mapped into the Oracle XML DB file system hierarchy).

  See Also: Chapter 18, "Oracle XML DB Resource Security"

Many terms used by Oracle XML DB have common synonyms used in other contexts, as shown in Table 13-1.

Table 13-1 Synonyms for Oracle XML DB Foldering Terms    

Synonym	Oracle XML DB Foldering Term	Usage
Collection	Folder	WebDAV
Directory	Folder	Operating systems
Privilege	Privilege	Permission
Right	Privilege	Various
WebDAV Folder	Folder	Web Folder
Role	Group	Access control
Revision	Version	RCS, CVS
File system	Repository	Operating systems
Hierarchy	Repository	Various
File	Resource	Operating systems
Binding	Link	WebDAV

Oracle XML DB Resources

Oracle XML DB resources conform to the xdbresource.xsl schema, which 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.

Contents Element in Resource Index

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

any Element

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.

Where Exactly Is Repository Data Stored?

Oracle XML DB stores Repository data in a set of tables and indexes in the Oracle XML DB database schema. These tables are accessible. If you register an XML schema and request the tables be generated by Oracle XML DB, the tables are created in your database schema. This means that you are able to see or modify them. However, other users will not be able to see your tables unless you explicitly grant them permission to do so.

Generated Table Names

The names of the generated tables are assigned by Oracle XML DB and can be obtained by finding the xdb:defaultTable=XXX attribute in your XML schema document (or the default XML schema document). When you register an XML schema, you can also provide your own table name, and override the default created by Oracle XML DB.

Defining Structured Storage for Resources

Applications that need to define structured storage for resources can do so by either:

• Subclassing the Oracle XML DB resource type. Subclassing Oracle XML DB resources requires privileges on the table XDB$RESOURCE.
• Storing data conforming to a visible, registered XML schema.

  See Also: Chapter 5, "Structured Mapping of XMLType".

Pathname Resolution

The data relating a folder to its children is managed by the Oracle XML DB hierarchical index. This provides a fast mechanism for evaluating path names, similar to the directory mechanisms used by operating-system file systems.

Resources that are folders have the Container attribute set to TRUE.

To resolve a resource name in a folder, the current user must have the following privileges:

• resolve privilege on the folder
• read-properties on the resource in that folder

If the user does not have these privileges, he receives an access denied error. Folder listings and other queries will not return a row when the read-properties privilege is denied on its resource.

Deleting Resources

Deletion of a link deletes the resource pointed to by the link if and only if that was the last link to the resource and the resource is not versioned. Links in Oracle XML DB Repository are analogous to Unix "hard links".

Accessing Oracle XML DB Repository Resources

Oracle XML DB provides two techniques for accessing resources:

• "Navigational or Path Access". Navigational/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 13-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: b. Access Models".

Figure 13-2 Oracle XML DB Repository Data Access Options

Text description of the illustration adxdb027.gif

A Uniform Resource Locator (URL) is used to access an Oracle XML DB resource. A URL includes the hostname, 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 13-3.
• Access Repository data using HTTP/WebDAV from an Internet Explorer browser, such as when viewing Web Folders, as shown in Figure 13-4.

Figure 13-3 Oracle XML DB Folders in Windows Explorer

Text description of the illustration 4_xfoldr.jpg

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

Text description of the illustration 3_f_http.gif

Accessing Oracle XML DB Resources Using Internet Protocols

Oracle Net Services provides one way of accessing database resources. Oracle XML DB support for Internet protocols provides another way of accessing database resources.

Where You Can Use Oracle XML DB Protocol Access

Oracle Net Services is optimized for record-oriented data. Internet protocols are designed for stream-oriented data, such as binary files or XML text documents.

Oracle XML DB protocol access is a valuable alternative to Net Services in the following scenarios:

• Direct database access from file-oriented applications using the database like a file system
• Heterogeneous application server environments that want a uniform data access method (such as XML over HTTP, which is supported by most data servers, including MS SQL Server, Exchange, Notes, many XML databases, stock quote services and news feeds)
• Application server environments that want data as XML text
• Web applications using client-side XSL to format datagrams not needing much application processing
• Web applications using Java servlets running inside the database
• Web access to XML-oriented stored procedures

Protocol Access Calling Sequence

Protocol access uses the following steps in Oracle XML DB:

1. A connection object is established, and the protocol may decide to read part of the request.
2. The protocol decides if the user is already authenticated and wants to reuse an existing session or if the connection must be reauthenticated (generally the case).
3. An existing session is pulled from the session pool, or a new one is created.
4. If authentication has not been provided and the request is HTTP Get or Head, the session is run as the ANONYMOUS user. If the session has already been authenticated as the ANONYMOUS user, there is no cost to reuse the existing session. If authentication has been provided, the database reauthentication routines are used to authenticate the connection.
5. The request is parsed.
6. If the requested path name maps to a servlet (for HTTP only), the servlet is invoked using the Java VM. The servlet code writes out the response to a response stream or asks XMLType instances to do so.

Retrieving Oracle XML DB Resources

When the protocol indicates that a resource is to be retrieved, the path name to the resource is resolved. Resources being fetched are always streamed out as XML, with the exception of resources containing the XDBBinary element, an element defined to be the XML binary data type, which have their contents streamed out in RAW form.

Storing Oracle XML DB Resources

When the protocol indicates that a resource must be stored, Oracle XML DB checks the document's file name extension for .xml, .xsl, .xsd, and so on. If the document is XML, a pre-parse step is done, where enough of the resource is read to determine the XML schemaLocation and namespace of the root element in the document. This location is used to look for a registered schema with that schemaLocation URL. If a registered schema is located with a definition for the root element of the current document, the default table specified for that element is used to store that resource's contents.

Using Internet Protocols and XMLType: XMLType Direct Stream Write

Oracle XML DB supports Internet protocols at the XMLType level by using the writeToStream() Java method on XMLType. This method is natively implemented and writes XMLType data directly to the protocol request stream. This avoids the overhead of converting database data through Java datatypes, creating Java objects, and Java VM execution costs, resulting in significantly higher performance. This is especially the case if the Java code deals with XML element trees only close to the root, without traversing too many of the leaf elements, hence minimizing the number of Java objects created.

Query-Based Access

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

• PATH_VIEW
• RESOURCE_VIEW

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

Table 13-2 Differences Between PATH_VIEW and RESOURCE_VIEW

PATH_VIEW	RESOURCE_VIEW
Contains link properties	No link properties
Contains resource properties and path name	Contains resource properties and path name
Has one row for each unique path in the Repository	Has one row for each resource in the Repository

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 the 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 stylesheet 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 20, "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/JNDI
• 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 13-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.

Table 13-3 Accessing Oracle XML DB Repository: API Options  

Data Access Operation	Query-Based Access: RESOURCE_VIEW API Path-Based Access: Resource API for PL/SQL	Path-Based Access: Protocols
Creating a resource	INSERT INTO PATH_VIEW VALUES (path, res, linkprop) See also DBMS_XDB.CreateResource.	HTTP PUT; FTP PUT
Updating contents of a resource using path name	UPDATE RESOURCE_VIEW SET resource = updateXML(res, '/Resource/Contents', lob) WHERE EQUALS_PATH(res, :path) > 0	HTTP PUT; FTP PUT
Updating properties of a resource by path name	UPDATE RESOURCE_VIEW SET resource = updateXML(res, '/Resource/propname', newval, '/Resource/propname2', newval2, ...) WHERE EQUALS_PATH(res, :path) > 0	HTTP PROPPATCH; FTP N/A
Updating the ACL of a resource	UPDATE RESOURCE_VIEW SET resource = updateXML(res, '/ Resource/ACL', XMLType) WHERE EQUALS_PATH(res, :path) > 0	N/A
Unlinking a resource, deleting it if it is the last link	DELETE FROM RESOURCE_VIEW WHERE EQUALS_PATH(res, :path) > 0	HTTP DELETE; FTP DELETE
Forcibly removing all links to a resource	DELETE FROM PATH_VIEW WHERE extractValue(res,'display_name') = 'My resource';	N/A FTP: quote rm_rf<resource>
Moving a resource or folder	UPDATE PATH_VIEW SET path = newpath WHERE EQUALS_PATH(res, :path) > 0	WebDAV MOVE; FTP RENAME
Copying a resource or folder	INSERT INTO PATH_VIEW SELECT::newpath, resource, link FROM PATH_VIEW WHERE EQUALS_PATH(res,:oldpath)> 0	WebDav COPY; FTP N/A
Creating a link to an existing resource	Call dbms_xdb.Link(srcpath IN VARCHAR2, linkfolder IN VARCHAR2, linkname IN VARCHAR2);	N/A
Getting binary/text representation of resource contents by path name	SELECT GET_CONTENTS(resource) FROM RESOURCE_VIEW p WHERE EQUALS_PATH(res, :path) > 0	HTTP GET; FTP GET
Getting XMLType representation of resource contents by path name	SELECT extract(res, '/Resource/Contents/*') FROM RESOURCE_VIEW p WHERE EQUALS_PATH(Res, :path) > 0	N/A
Getting resource properties by path name	SELECT extractValue(res, '/Resource/XXX') FROM RESOURCE_VIEW WHERE EQUALS_PATH(res,:path) > 0	WebDAVPROPFIND (depth = 0); FTP N/A
Listing a directory	SELECT * FROM PATH_VIEW WHERE UNDER_PATH(res, :path, 1) > 0	WebDAV PROPFIND (depth = 1); FTP LS
Creating a folder	ICall dbms_xdb.createFolder(VARCHAR2)	WebDAV MKCOL; FTP MKDIR
Unlinking a folder	DELETE FROM PATH_VIEW WHERE EQUALS_PATH(res, :path) > 0	HTTP DELETE;FTP RMDIR
Forcibly deleting a folder and all links to it	Call dbms_xdb.deleteFolder(VARCHAR2)	N/A FTP: quote rm_rf <folder>
Getting a resource with a row lock	SELECT ... FROM RESOURCE_VIEW FOR UPDATE ...;	N/A
Putting a WebDAV lock on the resource	DBMS_XDB.lock(lock_type INTEGER);	WebDAV LOCK; FTP: QUOTE LOCK
Removing a WebDAV lock	DBMS_XDB.unlock(path VARCHAR2);	WebDAV UNLOCK; QUOTE UNLOCK
Committing changes	COMMIT;	Automatically commits at the end of each request
Rollback changes	ROLLBACK;	N/A

Managing and Controlling Access to Resources

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

Extending Resource Metadata Properties

Oracle XML DB resources are described by XML schema, XDBResource.xsd. This XML schema is described in Appendix G, "Example Setup scripts. Oracle XML DB - Supplied XML Schemas". XDBResource.xsd declares a fixed set of metadata properties such as the Owner, CreationDate, and so on. You can specify values for these metadata attributes while creating or updating resources.

You have two options for storing proprietary (custom) tags as extra metadata with resources, that is metadata properties that are not defined by the Resource XML schema:

• Option 1: Storing extra metadata as a CLOB (ResExtra element). The default schema has a top-level any element (declared with maxOccurs= "unbounded"), thus allowing any valid XML data as part of the resource document, and gets stored in the RESEXTRA CLOB column:

  Note: The XML representing user level metadata must be within a namespace other than that XDBResource namespace.

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

  Though this approach works well for ad-hoc extensions to the resource metadata, the queryability and updatability of the user metadata is impacted because the user metadata is stored in a CLOB.

• Option 2: Extending the Resource XML Schema. You can extend the resource XML schema using the techniques specified by the XML schema specifications, that is, you can register a new XML schema that extends the ResourceType complexType. This triggers the creation of object subtypes under the XDB$RESOURCE_T object type, thereby adding new columns to the XDB$RESOURCE table:

  <schema xmlns="http://www.w3.org/2001/XMLSchema"
  xmlns:xdbres="http://xmlns.oracle.com/xdb/XDBResource.xsd"
      <complexType name="myCustomResourceType>
        <complexContent>
          <extension base="xdbres:ResourceType>
            <element name="custom-attr1" type="string">
            ...
          </extension>
        </complexContent>
     </complexType>
  </schema>
  
  

Frequently Asked Questions (FAQs): XML DB Repository

Why Does XML Repository Hierarchical Index Not Work?

In XML DB Release 2 (9.2) the following query worked using the hierarchical index:

SELECT XDBURITYPE(ANY_PATH).GETXML()
   FROM RESOURCE_VIEW 
   WHERE CONTAINS(RES,'MYXML') >0; 
  

But this does not work with the latest release. I get the error column not indexed. How should I use the hierarchical index to search the contents of documents in the XML Repository? In one place the documentation describes a hierarchical index that indexes path names but does not mention what type of index this is and when mentioning the DBMS_XDBT package, it describes a ConText index on the Oracle XML DB Repository hierarchy that sounds similar?

Answer: It appears that you have not created the Context index on the Repository. Note that Contains() needs the Context index for its evaluation. You can create the Context index on xdb$resource by:

(a) is the preferred solution because it takes into account the binary contents in the Repository and filters it appropriately. Solution (b) will only index the XML and text content in the Repository.

There are two different indexes on the xdb$resource table:

• Hierarchical Index. This is always present. The rebuild hierarchical index procedure is for rebuilding this index.
• Context index is an optional index, that is, your DBA can create this index if needed. You will need this index to perform Contains() queries.