26 PL/SQL Access to Oracle XML DB Repository

This chapter describes the Oracle XML DB resource application program interface (API) for PL/SQL. There are two PL/SQL packages for this:

  • DBMS_XDB_CONFIG – Configure Oracle XML DB and its repository

  • DBMS_XDB_REPOS – Other, non-configuration operations on the repository

The chapter contains these topics:

DBMS_XDB_REPOS: Access and Manage Repository Resources

PL/SQL package DBMS_XDB_REPOS is used by application developers to access and manage resources in Oracle XML DB Repository. It includes methods for managing resource security based on access control lists (ACLs). An ACL is a list of access control entries (ACEs) that determines which principals (users and roles) have access to which resources.

Table 26-1 describes the functions and procedures in package DBMS_XDB_REPOS.

Table 26-1 DBMS_XDB_REPOS Resource Access and Management Subprograms

Function/Procedure Description

addResource

Insert a new file resource into the repository hierarchy, with the given string as its contents.

appendResourceMetadata

Add user-defined metadata to a resource.

createFolder

Create a new folder resource.

createOIDPath

Create a virtual path to a resource, based on its object identifier (OID).

createResource

Create a new file resource.

deleteResource

Delete a resource from the repository.

deleteResourceMetadata

Delete specific user-defined metadata from a resource.

existsResource

Indicate whether or not a resource exists, given its absolute path.

getContentBLOB

Return the contents of a resource as a BLOB instance.

getContentVARCHAR2

Return the contents of a resource as a VARCHAR2 value.

getContentXMLRef

Return the contents of a resource as a reference to an XMLType instance.

getContentXMLType

Return the contents of a resource as an XMLType instance.

getLockToken

Return a resource lock token for the current user, given a path to the resource.

getResOID

Return the object identifier (OID) of a resource, given its absolute path.

getResource

Return the instance of class DBMS_XDBRESOURCE.XDBResource that is located at a given path in the repository.

getXDB_tablespace

Return the current tablespace of database schema (user account) XDB.

hasBLOBContent

Return TRUE if a given resource has BLOB content.

hasCharContent

Return TRUE if a given resource has character content.

hasXMLContent

Return TRUE if a given resource has XMLType content.

hasXMLReference

Return TRUE if a given resource has a reference to XMLType content.

isFolder

Return TRUE if a given resource is a folder.

link

Create a link to an existing resource.

lockResource

Obtain a WebDAV-style lock on a resource, given a path to the resource.

processLinks

Process all XLink and XInclude links in a document or folder.

purgeResourceMetadata

Delete all user-defined metadata from a given resource.

refreshContentSize

Recompute the content size of a given resource.

renameResource

Rename a given resource.

touchResource

Change the last-modified time to the current time.

unlockResource

Unlock a resource, given its lock token and path.

updateResourceMetadata

Modify user-defined resource metadata.


Example 26-1 uses package DBMS_XDB_REPOS to manage repository resources. It creates the following:

  • A folder, mydocs, under folder /public

  • Two file resources, emp_selby.xml and emp_david.xml

  • Two links to the file resources person_selby.xml and person_david.xml

It then deletes each of the newly created resources and links. The folder contents are deleted before the folder itself.

Example 26-1 Managing Resources Using DBMS_XDB_REPOS

DECLARE
  retb BOOLEAN;
BEGIN
  retb := DBMS_XDB_REPOS.createfolder('/public/mydocs');
  retb := DBMS_XDB_REPOS.createresource('/public/mydocs/emp_selby.xml',
                                        '<emp_name>selby</emp_name>');
  retb := DBMS_XDB_REPOS.createresource('/public/mydocs/emp_david.xml',
                                        '<emp_name>david</emp_name>');
END;
/
PL/SQL procedure successfully completed.
 
CALL DBMS_XDB_REPOS.link('/public/mydocs/emp_selby.xml',
                         '/public/mydocs',
                         'person_selby.xml');
Call completed.
 
CALL DBMS_XDB_REPOS.link('/public/mydocs/emp_david.xml',
                         '/public/mydocs',
                         'person_david.xml');
Call completed.
 
CALL DBMS_XDB_REPOS.deleteresource('/public/mydocs/emp_selby.xml');
Call completed.
 
CALL DBMS_XDB_REPOS.deleteresource('/public/mydocs/person_selby.xml');
Call completed.
 
CALL DBMS_XDB_REPOS.deleteresource('/public/mydocs/emp_david.xml');
Call completed.
 
CALL DBMS_XDB_REPOS.deleteresource('/public/mydocs/person_david.xml');
Call completed.
 
CALL DBMS_XDB_REPOS.deleteresource('/public/mydocs');
Call completed.

See Also:

Chapter 29, "User-Defined Repository Metadata" for examples using appendResourceMetadata and deleteResourceMetadata

DBMS_XDB_REPOS: ACL-Based Security Management

Table 26-2 lists the DBMS_XDB_REPOS Oracle XML DB ACL- based security management functions and procedures.

Table 26-2 DBMS_XDB_REPOS: Security Management Subprograms

Function/Procedure Description

ACLCheckPrivileges

Check the access privileges granted to the current user by an ACL.

changeOwner

Change the owner of a given resource to a given user.

changePrivileges

Add an ACE to a resource ACL.

checkPrivileges

Check the access privileges granted to the current user for a resource.

getACLDocument

Return the ACL document that protects a resource, given the path name of the resource.

getPrivileges

Return all privileges granted to the current user for a resource.

setACL

Set the ACL for a resource.


The examples in this section illustrate the use of these functions and procedures.

In Example 26-2, database user HR creates two resources: a folder, /public/mydocs, with a file in it, emp_selby.xml. Procedure getACLDocument is called on the file resource, showing that the <principal> user for the document is PUBLIC.

Example 26-2 Using DBMS_XDB_REPOS.GETACLDOCUMENT

CONNECT hr
Enter password: password

Connected.

DECLARE
  retb BOOLEAN;
BEGIN
  retb := DBMS_XDB_REPOS.createFolder('/public/mydocs');
  retb := DBMS_XDB_REPOS.createResource('/public/mydocs/emp_selby.xml',
                                        '<emp_name>selby</emp_name>');
END;
/
PL/SQL procedure successfully completed.
 
SELECT XMLSerialize(DOCUMENT
                    DBMS_XDB_REPOS.getACLDocument('/public/mydocs/emp_selby.xml')
                    AS CLOB)
  FROM DUAL;
 
XMLSERIALIZE(DOCUMENTDBMS_XDB_REPOS.GETACLDOCUMENT('/PUBLIC/MYDOCS/EMP_SELBY.XML
--------------------------------------------------------------------------------
<acl description="Public:All privileges to PUBLIC" xmlns="http://xmlns.oracle.co
m/xdb/acl.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaL
ocation="http://xmlns.oracle.com/xdb/acl.xsd                           http://xm
lns.oracle.com/xdb/acl.xsd" shared="true">
  <ace>
    <grant>true</grant>
    <principal>PUBLIC</principal>
    <privilege>
      <all/>
    </privilege>
  </ace>
</acl>
 
1 row selected.

In Example 26-3, the system manager connects and uses procedure setACL to give the owner (database schema HR) all privileges on the file resource created in Example 26-2. Procedure getACLDocument then shows that the <principal> user is dav:owner, the owner (HR).

Example 26-3 Using DBMS_XDB_REPOS.SETACL

CONNECT SYSTEM
Enter password: password

Connected.
 
-- Give all privileges to owner, HR.
CALL DBMS_XDB_REPOS.setACL('/public/mydocs/emp_selby.xml',
                           '/sys/acls/all_owner_acl.xml');
Call completed.
COMMIT;
Commit complete.

SELECT XMLSerialize(DOCUMENT
                    DBMS_XDB_REPOS.getACLDocument('/public/mydocs/emp_selby.xml')
                    AS CLOB)
  FROM DUAL;

XMLSERIALIZE(DOCUMENTDBMS_XDB_REPOS.GETACLDOCUMENT('/PUBLIC/MYDOCS/EMP_SELBY.XML
--------------------------------------------------------------------------------
<acl description="Private:All privileges to OWNER only and not accessible to oth
ers" xmlns="http://xmlns.oracle.com/xdb/acl.xsd" xmlns:dav="DAV:" xmlns:xsi="htt
p://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://xmlns.oracle.
com/xdb/acl.xsd http://xmlns.oracle.com/xdb/acl.xsd" shared="true">
  <ace>
    <grant>true</grant>
    <principal>dav:owner</principal>
    <privilege>
      <all/>
    </privilege>
  </ace>
</acl>
 
1 row selected.

In Example 26-4, user HR connects and uses function changePrivileges to add a new access control entry (ACE) to the ACL, which gives all privileges on resource emp_selby.xml to user oe. Procedure getACLDocument shows that the new ACE was added to the ACL.

Example 26-4 Using DBMS_XDB_REPOS.CHANGEPRIVILEGES

CONNECT hr
Enter password: password

Connected.

SET SERVEROUTPUT ON

-- Add an ACE giving privileges to user OE
DECLARE
  r        PLS_INTEGER;
  ace      XMLType;
  ace_data VARCHAR2(2000);
BEGIN
  ace_data := '<ace xmlns="http://xmlns.oracle.com/xdb/acl.xsd"
                    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                    xsi:schemaLocation="http://xmlns.oracle.com/xdb/acl.xsd
                                        http://xmlns.oracle.com/xdb/acl.xsd
                                        DAV:http://xmlns.oracle.com/xdb/dav.xsd">
                 <principal>OE</principal>
                 <grant>true</grant>
                 <privilege><all/></privilege>
               </ace>';
  ace := XMLType.createXML(ace_data);
  r := DBMS_XDB_REPOS.changePrivileges('/public/mydocs/emp_selby.xml', ace);
END;
/
 
PL/SQL procedure successfully completed.

COMMIT;

SELECT XMLSerialize(DOCUMENT
                    DBMS_XDB_REPOS.getACLDocument('/public/mydocs/emp_selby.xml')
                    AS CLOB)
  FROM DUAL;
 
XMLSERIALIZE(DOCUMENTDBMS_XDB_REPOS.GETACLDOCUMENT('/PUBLIC/MYDOCS/EMP_SELBY.XML
--------------------------------------------------------------------------------
<acl description="Private:All privileges to OWNER only and not accessible to oth
ers" xmlns="http://xmlns.oracle.com/xdb/acl.xsd" xmlns:dav="DAV:" xmlns:xsi="htt
p://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://xmlns.oracle.
com/xdb/acl.xsd                           http://xmlns.oracle.com/xdb/acl.xsd" s
hared="false">
  <ace>
    <grant>true</grant>
    <principal>dav:owner</principal>
    <privilege>
      <all/>
    </privilege>
  </ace>
  <ace>
    <grant>true</grant>
    <principal>OE</principal>
    <privilege>
      <all/>
    </privilege>
  </ace>
</acl>
 
1 row selected.

In Example 26-5, user oe connects and calls DBMS_XDB_REPOS.getPrivileges, which shows all of the privileges granted to user oe on resource emp_selby.xml.

Example 26-5 Using DBMS_XDB_REPOS.GETPRIVILEGES

CONNECT oe
Enter password: password

Connected.

SELECT XMLSerialize(DOCUMENT
                    DBMS_XDB_REPOS.getPrivileges('/public/mydocs/emp_selby.xml')
                    AS CLOB)
  FROM DUAL;
 
XMLSERIALIZE(DOCUMENTDBMS_XDB_REPOS.GETPRIVILEGES('/PUBLIC/MYDOCS/EMP_SELBY.XML'
--------------------------------------------------------------------------------
<privilege xmlns="http://xmlns.oracle.com/xdb/acl.xsd" xmlns:xsi="http://www.w3.
org/2001/XMLSchema-instance" xsi:schemaLocation="http://xmlns.oracle.com/xdb/acl
.xsd http://xmlns.oracle.com/xdb/acl.xsd DAV: http://xmlns.oracle.com/xdb/dav.xs
d" xmlns:xdbacl="http://xmlns.oracle.com/xdb/acl.xsd" xmlns:dav="DAV:">
  <read-properties/>
  <read-contents/>
  <write-config/>
  <link/>
  <unlink/>
  <read-acl/>
  <write-acl-ref/>
  <update-acl/>
  <resolve/>
  <link-to/>
  <unlink-from/>
  <dav:lock/>
  <dav:unlock/>
  <dav:write-properties/>
  <dav:write-content/>
  <dav:execute/>
  <dav:take-ownership/>
  <dav:read-current-user-privilege-set/>
</privilege>
 
1 row selected.

DBMS_XDB_CONFIG: Configuration Management

Table 26-3 lists the DBMS_XDB_CONFIG Oracle XML DB configuration management functions and procedures.

Table 26-3 DBMS_XDB_CONFIG: Configuration Management Subprograms

Function/Procedure Description

addHTTPExpireMapping

Add a mapping of a URL pattern to an expiration date to table XDB$CONFIG. The mapping controls the Expire headers for URLs that match the pattern.

addMIMEMapping

Add a MIME mapping to table XDB$CONFIG.

addSchemaLocMapping

Add a schema-location mapping to table XDB$CONFIG.

addServlet

Add a servlet to table XDB$CONFIG.

addServletMapping

Add a servlet mapping to table XDB$CONFIG.

addServletSecRole

Add a security role reference to a servlet.

addXMLExtension

Add an XML extension to table XDB$CONFIG.

cfg_get

Return the configuration information for the current session.

cfg_refresh

Refresh the session configuration information using the current Oracle XML DB configuration file, xdbconfig.xml.

cfg_update

Update the Oracle XML DB configuration information. This writes the configuration file, xdbconfig.xml.

deleteHTTPExpireMapping

Delete all mappings of a given URL pattern to an expiration date from table XDB$CONFIG.

deleteMIMEMapping

Delete a MIME mapping from table XDB$CONFIG.

deleteSchemaLocMapping

Delete a schema-location mapping from table XDB$CONFIG.

deleteServlet

Delete a servlet from table XDB$CONFIG.

deleteServletMapping

Delete a servlet mapping from table XDB$CONFIG.

deleteServletSecRole

Delete a security role reference from a servlet.

deleteXMLExtension

Delete an XML extension from table XDB$CONFIG.

enableDigestAuthentication

Enable digest authentication.

getFTPPort

Return the current FTP port number.

getHTTPConfigRealm

Return the HTTP configuration realm.

getHTTPPort

Return the current HTTP port number.

getListenerEndPoint

Return the parameters of a listener end point for the HTTP server.

setFTPPort

Set the Oracle XML DB FTP port to the specified port number.

setHTTPConfigRealm

Set the HTTP configuration realm.

setHTTPPort

Set the Oracle XML DB HTTP port to the specified port number.

setListenerEndPoint

Set the parameters of a listener end point for the HTTP server.

setListenerLocalAccess

Either (a) restrict all listener end points to listen on only the localhost interface or (b) allow all listener end points to listen on both localhost and non-localhost interfaces.

usedPort

Return the ports used by other pluggable databases (PDBs) in the same multitenant container database (CDB). The return value is an XMLType instance that lists each PDB by id number and its associated ports by type and number.


See Also:

Oracle Database PL/SQL Packages and Types Reference, Chapter "DBMS_XDB_CONFIG"

The examples in this section illustrate the use of these functions and procedures.

Example 26-6 uses function cfg_get to retrieve the Oracle XML DB configuration file, xdbconfig.xml.

Example 26-6 Using DBMS_XDB_CONFIG.CFG_GET

CONNECT SYSTEM
Enter password: password

Connected.

SELECT DBMS_XDB_CONFIG.cfg_get() FROM DUAL;
 
DBMS_XDB_CONFIG.CFG_GET()
--------------------------------------------------------------------------------
<xdbconfig xmlns="http://xmlns.oracle.com/xdb/xdbconfig.xsd" xmlns:xsi="http://w
ww.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://xmlns.oracle.com/x
db/xdbconfig.xsd                                     http://xmlns.oracle.com/xdb
/xdbconfig.xsd">
  <sysconfig>
    <acl-max-age>19</acl-max-age>
    <acl-cache-size>32</acl-cache-size>
    <invalid-pathname-chars/>
    <case-sensitive>true</case-sensitive>
    <call-timeout>6000</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>
        . . .
      </common>
      <ftpconfig>
        . . .
      </ftpconfig>
      <httpconfig>
        <http-port>0</http-port>
        <http-listener>local_listener</http-listener>
        <http-protocol>tcp</http-protocol>
        <max-http-headers>64</max-http-headers>
        <max-header-size>16384</max-header-size>
        <max-request-body>2000000000</max-request-body>
        <session-timeout>6000</session-timeout>
        <server-name>XDB HTTP Server</server-name>
        <logfile-path>/sys/log/httplog.xml</logfile-path>
        <log-level>0</log-level>
        <servlet-realm>Basic realm=&quot;XDB&quot;</servlet-realm>
        <webappconfig>
        . . .
        </webappconfig>
        <authentication>
        . . .
        </authentication>
    </protocolconfig>
    <xdbcore-xobmem-bound>1024</xdbcore-xobmem-bound>
    <xdbcore-loadableunit-size>16</xdbcore-loadableunit-size>
    <acl-evaluation-method>ace-order</acl-evaluation-method>
  </sysconfig>
</xdbconfig>
 
1 row selected.

Example 26-7 illustrates the use of procedure cfg_update. The current configuration is retrieved as an XMLType instance and modified. It is then rewritten using cfg_update.

Example 26-7 Using DBMS_XDB_CONFIG.CFG_UPDATE

DECLARE
  configxml    SYS.XMLType;
  configxml2   SYS.XMLType;
BEGIN
  -- Get the current configuration
  configxml := DBMS_XDB_CONFIG.cfg_get();
 
  -- Modify the configuration
SELECT XMLQuery(
  'declare default element namespace
   "http://xmlns.oracle.com/xdb/xdbconfig.xsd"; (: :)
   copy $i := $p1 modify
     (for $j in $i/xdbconfig/sysconfig/protocolconfig/httpconfig/http-port
      return replace value of node $j with $p2)
     return $i'
    PASSING CONFIGXML AS "p1", '8000' AS "p2" RETURNING CONTENT)
  INTO configxml2 FROM DUAL;
 
  -- Update the configuration to use the modified version
  DBMS_XDB_CONFIG.cfg_update(configxml2);
END;
/
 
PL/SQL procedure successfully completed.

SELECT DBMS_XDB_CONFIG.cfg_get() FROM DUAL;
 
DBMS_XDB_CONFIG.CFG_GET()
--------------------------------------------------------------------------------
<xdbconfig xmlns="http://xmlns.oracle.com/xdb/xdbconfig.xsd" xmlns:xsi="http://w
ww.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://xmlns.oracle.com/x
db/xdbconfig.xsd http://xmlns.oracle.com/xdb/xdbconfig.xsd">
  <sysconfig>
    <acl-max-age>15</acl-max-age>
    <acl-cache-size>32</acl-cache-size>
    <invalid-pathname-chars/>
    <case-sensitive>true</case-sensitive>
    <call-timeout>6000</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>
    <resource-view-cache-size>1048576</resource-view-cache-size>
    <protocolconfig>
      <common>
      . . .
      </common>
      <ftpconfig>
      . . .
      </ftpconfig>
      <httpconfig>
        <http-port>8000</http-port>
        . . .
      </httpconfig>
    </protocolconfig>
    <xdbcore-xobmem-bound>1024</xdbcore-xobmem-bound>
    <xdbcore-loadableunit-size>16</xdbcore-loadableunit-size>
    <acl-evaluation-method>ace-order</acl-evaluation-method>
</xdbconfig>
 
1 row selected.