16
Oracle XML DB Resource API for PL/SQL (DBMS_XDB)

This chapter describes the Oracle XML DB Resource API for PL/SQL (DBMS_XDB) used for accessing and managing Oracle XML DB Repository resources and data using PL/SQL. It includes methods for managing the resource security and Oracle XML DB configuration.

It contains the following sections:

• Introducing Oracle XML DB Resource API for PL/SQL
• Overview of DBMS_XDB
• DBMS_XDB: Oracle XML DB Resource Management
• DBMS_XDB: Oracle XML DB ACL-Based Security Management
• DBMS_XDB: Oracle XML DB Configuration Management
• DBMS_XDB: Rebuilding Oracle XML DB Hierarchical Indexes

Introducing Oracle XML DB Resource API for PL/SQL

This chapter describes the Oracle XML DB Resource API for PL/SQL (PL/SQL package DBMS_XDB). This is also known as the PL/SQL foldering API.

Oracle XML DB Repository is modeled on XML and provides a database file system for any data. Oracle XML DB Repository maps path names (or URLs) onto database objects of XMLType and provides management facilities for these objects.

DBMS_XDB package provides functions and procedures for accessing and managing Oracle XML DB Repository using PL/SQL.

Overview of DBMS_XDB

The DBMS_XDB provides the PL/SQL application developer with an API that manages:

• Oracle XML DB Resources
• Oracle XML DB ACL based Security
• Oracle XML DB Configuration
• Oracle XML DB Hierarchical Index Rebuild

DBMS_XDB: Oracle XML DB Resource Management

Table 16-1 lists the DBMS_XDB Oracle XML DB resource management methods.

Table 16-1 DBMS_XDB Resource Management Methods  

DBMS_XDB Method	Arguments, Return Values
Link	Argument: (srcpath VARCHAR2, linkfolder VARCHAR2, linkname VARCHAR2) Return value: N/A
LockResource	Argument: (path IN VARCHAR2, depthzero IN BOOLEAN, shared IN boolean) Return value: TRUE if successful.
GetLockToken	Argument: (path IN VARCHAR2, locktoken OUT VARCHAR2) Return value: N/A
UnlockResource	Argument: (path IN VARCHAR2, deltoken IN VARCHAR2) Return value: TRUE if successful.
CreateResource	FUNCTION CreateResource (path IN VARCHAR2, data IN VARCHAR2) RETURN BOOLEAN; Creates a new resource with the given string as its contents. FUNCTION CreateResource (path IN VARCHAR2, data IN SYS.XMLTYPE) RETURN BOOLEAN; Creates a new resource with the given XMLType data as its contents. FUNCTION CreateResource (path IN VARCHAR2, datarow IN REF SYS.XMLTYPE) RETURN BOOLEAN; Given a PREF to an existing XMLType row, creates a resource whose contents point to that row. That row should not already exist inside another resource. FUNCTION CreateResource (path IN VARCHAR2, data IN CLOB) RETURN BOOLEAN; Creates a resource with the given CLOB as its contents. FUNCTION CreateResource (path IN VARCHAR2, data IN BFILE) RETURN BOOLEAN; Creates a resource with the given BFILE as its contents.
CreateFolder	Argument: (path IN VARCHAR2) Return value: TRUE if successful.
DeleteResource	Argument: (path IN VARCHAR2) Return value: N/A

Using DBMS_XDB to Manage Resources, Calling Sequence

Figure 16-1 describes the calling sequence when using DBMS_XDB to manage Repository resources:

1. When managing Repository resources the calling sequence diagram assumes that the resources and folders already exist. If not, you need to create the resources using createResource() or create folders using createFolder()
   • createResource() takes resource data and the resource path as parameters.
   • createFolder() takes the resource path as a parameter.
2. If the resource or folder does not need further processing or managing, they are simply output.
3. If the resource or folder need further processing or managing you can apply any or all of the following methods as listed in Table 16-1:
   • Link()
   • LockResource()
   • GetLockToken()
   • UnlockResource()
   • DeleteResource()

See Example 16-1 for an examples of using DBMS_XDB to manage Repository resources.

Figure 16-1 Using DBMS_XDB to Manage Resources: Calling Sequence

Text description of the illustration adxdb040.gif

Example 16-1 Using DBMS_XDB to Manage Resources

DECLARE
   retb boolean;
BEGIN
   retb := dbms_xdb.createfolder('/public/mydocs');
   commit;
END;
/

declare
  bret boolean;
begin
  bret :=
dbms_xdb.createresource('/public/mydocs/emp_scott.xml','<emp_name>scott</emp_nam
e>');
  commit;
end;
/

declare
  bret boolean;
begin
  bret :=
dbms_xdb.createresource('/public/mydocs/emp_david.xml','<emp_name>david</emp_nam
e>');
  commit;
end;
/

call dbms_xdb.link('/public/mydocs/emp_scott.xml','/public/mydocs',
'person_scott.xml');
call dbms_xdb.link('/public/mydocs/emp_david.xml','/public/mydocs',
'person_david.xml');
commit;

call dbms_xdb.deleteresource('/public/mydocs/emp_scott.xml');
call dbms_xdb.deleteresource('/public/mydocs/person_scott.xml');
call dbms_xdb.deleteresource('/public/mydocs/emp_david.xml');
call dbms_xdb.deleteresource('/public/mydocs/person_david.xml');
call dbms_xdb.deleteresource('/public/mydocs');
commit;

DBMS_XDB: Oracle XML DB ACL-Based Security Management

Table 16-2 lists the DBMS_XDB Oracle XML DB ACL- based security management methods. Because the arguments and return values for the methods are self-explanatory, only a brief description of the methods is provided here.

Table 16-2 DBMS_XDB: Security Management Methods  

DBMS_XDB Method	Arguments, Return Values
getAclDocument	Argument: (abspath VARCHAR2) Return value: XMLType for the ACL document
ACLCheckPrivileges	Argument: (acl_path IN VARCHAR2, owner IN VARCHAR2, privs IN XMLType) Return value: Positive integer if privileges are granted.
checkPrivileges	Argument: (res_path IN VARCHAR2, privs IN XMLType Return value: Positive integer if privileges are granted.
getprivileges	Argument: (res_path IN VARCHAR2) Return value: XMLType instance of the <privilege> element.
changePrivileges	Argument: (res_path IN VARCHAR2, ace IN XMLType) Return value: Positive integer if ACL was successfully modified.
setAcl	Argument: (res_path IN VARCHAR2, acl_path IN VARCHAR2). This sets the ACL of the resource at res_path to the ACL located at acl_path. Return value: N/A

Using DBMS_XDB to Manage Security, Calling Sequence

Figure 16-2 describes the calling sequence when using DBMS_XDB to manage security.

1. Each DBMS_XDB security management method take in a path (resource_path, abspath, or acl_path).
2. You can then use any or all of the DBMS_XDB methods listed in Table 16-2 to perform security management tasks:
   • getAclDocument()
   • ACLCheckPrivileges()
   • checkPrivileges()
   • getPrivileges()
   • changePrivileges()
   • setACL()

See Example 16-2 for an examples of using DBMS_XDB to manage Repository resource security.

Figure 16-2 Using DBMS_XDB to Manage Security: Calling Sequence

Text description of the illustration adxdb041.gif

Example 16-2 Using DBMS_XDB to Manage ACL-Based Security

DECLARE
   retb boolean;
BEGIN
   retb := dbms_xdb.createfolder('/public/mydocs');
   commit;
END;
/

declare
  bret boolean;
begin
  bret :=
dbms_xdb.createresource('/public/mydocs/emp_scott.xml','<emp_name>scott</emp_nam
e>');
  commit;
end;
/

call dbms_xdb.setacl('/public/mydocs/emp_scott.xml',
'/sys/acls/all_owner_acl.xml');
commit;

select dbms_xdb.getacldocument('/public/mydocs/emp_scott.xml') from
dual;
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>SCOTT</principal>
    <grant>true</grant>
    <privilege>
      <all/>
    </privilege>
 </ace>';
  ace := xmltype.createxml(ace_data);
  r := dbms_xdb.changeprivileges('/public/mydocs/emp_scott.xml', ace);
  dbms_output.put_line('retval = ' || r);
  commit;
end;
/

select dbms_xdb.getacldocument('/public/mydocs/emp_scott.xml') from
dual;
select dbms_xdb.getprivileges('/public/mydocs/emp_scott.xml') from dual;
call dbms_xdb.deleteresource('/public/mydocs/emp_scott.xml');
call dbms_xdb.deleteresource('/public/mydocs');
commit;

DBMS_XDB: Oracle XML DB Configuration Management

Table 16-3 lists the DBMS_XDB Oracle XML DB Configuration Management Methods. Because the arguments and return values for the methods are self-explanatory, only a brief description of the methods is provided here.

Table 16-3 DBMS_XDB: Configuration Management Methods

DBMS_XDB Method	Arguments, Return Value
CFG_get	Argument: None Return value: XMLType for session configuration information
CFG_refresh	Argument: None Return value: N/A
CFG_update	Argument: (xdbconfig IN XMLType) Return value: N/A

Using DBMS_XDB for Configuration Management, Calling Sequence

Figure 16-3 shows the calling sequence when using DBMS_XDB for configuration management.

The diagram shows the following sequence:

1. To manage the Oracle XML DB configuration you must first retrieve the configuration instance using cfg_get.
2. You can then optionally also modify the Oracle XML DB configuration xmltype instance in order to update it, or simply output the Oracle XML DB configuration.
3. To update the Oracle XML DB configuration resource use cfg_update. You need to either input a new Oracle XML DB configuration xmltype instance or use a modified version of the current configuration.
4. To refresh the Oracle XML DB configuration resource use cfg_refresh. You do not need to input a configuration xmltype instance.

See Example 16-3 for an example of using DBMS_XDB for configuration management of Repository resources.

Figure 16-3 Using DBMS_XDB for Configuration Management: Calling Sequence

Text description of the illustration adxdb043.gif

Example 16-3 Using DBMS_XDB for Configuration Management of Oracle XML DB

connect system/manager
select dbms_xdb.cfg_get() from dual;
declare
  config   xmltype;
begin
  config := dbms_xdb.cfg_get();
  -- Modify the xdb configuration using updatexml, etc ...
  dbms_xdb.cfg_update(config);
end;
/

-- To pick up the latest XDB Configuration
--   In this example it is not needed as cfg_update(), 
--   automatically does a cfg_refresh().
call dbms_xdb.cfg_refresh();

DBMS_XDB: Rebuilding Oracle XML DB Hierarchical Indexes

Table 16-4 lists the DBMS_XDB Oracle XML DB hierarchical index rebuild methods. Because the arguments and return values for the methods are self-explanatory, only a brief description of the methods is provided here.

Table 16-4 DBMS_XDB: Hierarchical Index Rebuild Method

DBMS_XDB Method	Arguments, Return Values
RebuildHierarchicalIndex	Argument: None Return value: N/A

Using DBMS_XDB to Rebuild Hierarchical Indexes, Calling Sequence

Figure 16-4 shows the calling sequence when using DBMS_XDB for rebuilding hierarchical indexes. To rebuild the hierarchical indexes, first delete the entries from xdb.xdb$h_index and rebuild the hierarchical index by executing DBMS_XDB.RebuildHierachicalIndex. Example 16-4 shows how to use DBMS_XDB to rebuild the Repository hierarchical indexes.

Figure 16-4 Using DBMS_XDB to Rebuild Hierarchical Indexes: Calling Sequence

Text description of the illustration adxdb042.gif

Example 16-4 Using DBMS_XDB for to Rebuild a Hierarchical index

connect system/manager
delete from xdb.xdb$h_index;
commit;
execute dbms_xdb.RebuildHierarchicalIndex;