29
Resource Management and Access Control for PL/SQL

Resource Management and Access Control APIs for PL/SQL are contained in the DBMS_XDB Package.

This chapter contains the following sections:

• Description of DBMS_XDB
• Functions and Procedures of DBMS_XDB

  See Also: Oracle9i XML Database Developer's Guide - Oracle XML DB Oracle9i Supplied PL/SQL Packages and Types Reference

---

DBMS_XDB Package

---

Description of DBMS_XDB

The DBMS_XDB package provides the PL/SQL application developer with APIs that allow resource management in the Oracle XML DB Hierarchy, support for Oracle XML DB's Access Control List (ACL) Security and Oracle XML DB Configuration sessional management.

The Oracle XML DB Resource Management functionality provides Link(), LockResource(), GetLockToken(), UnlockResource(), CreateResource(), CreateFolder(), DeleteResource(),Link() and functions. These methods complement the functionality provided by Resource Views.

The ACL-based security mechanism can be used with either in-hierarchy ACLs (ACLs stored by the Oracle XML DB resource API) or in-memory ACLs (that may be stored by the user outside Oracle XML DB). Some of these methods can be used for both Oracle XML DB resources and arbitrary database objects.

The Access Control Security functionality provides checkPrivileges(), getAclDocument(), changePrivileges() and getPrivileges() functions for Oracle XML DB Resources. AclCheckPrivileges() function enables database users access to Oracle XML DB's ACL-based Security mechanism without having to have their objects stored in the Oracle XML DB Hierarchy.

Oracle XML DB Configuration session management provides CFG_Refresh(), CFG_Get() and CFG_Update().

---

Functions and Procedures of DBMS_XDB

Table 29-1 Summary of Functions and Procedures of DBMS_XDB  

Function/Procedure	Description
getAclDocument()	Retrieves ACL document that protects resource given its path name.
getPrivileges()	Gets all privileges granted to the current user on the given Oracle XML DB resource.
changePrivileges()	Adds the given ACE to the given resource's ACL.
checkPrivileges()	Checks access privileges granted to the current user on the specified Oracle XML DB resource.
setacl()	Sets the ACL on the given Oracle XML DB resource to be the ACL specified.
AclCheckPrivileges()	Checks access privileges granted to the current user by specified ACL document on a resource whose owner is specified by the 'owner' parameter.
LockResource()	Gets a WebDAV-style lock on that resource given a path to that resource.
GetLockToken()	Returns that resource's lock token for the current user given a path to a resource.
UnlockResource()	Unlocks the resource given a lock token and a path to the resource.
CreateResource()	Creates a new resource.
CreateFolder()	Creates a new folder resource in the hierarchy.
DeleteResource()	Deletes a resource from the hierarchy.
Link()	Creates a link to an existing resource.
CFG_Refresh()	Refreshes the session's configuration information to the latest configuration.
CFG_Get()	Retrieves the session's configuration information.
CFG_Update()	Updates the configuration information.

getAclDocument()

Description

Retrieves ACL document that protects resource given its path name; returns the xmltype for ACL document.

Syntax

FUNCTION getAclDocument( abspath  IN  VARCHAR2)
                         RETURN sys.xmltype;

Parameter	IN / OUT	Description
abspath	(IN)	Pathname of the resource whose ACL doc is required.

getPrivileges()

Description

Gets all privileges granted to the current user on the given Oracle XML DB resource. Returns an XMLType instance of <privilege> element, which contains the list of all leaf privileges granted on this resource to the current user. For example,

     <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"
           <read-contents/>
           <read-properties/>
           <resolve/>
           <read-acl/>
      </privilege>

Syntax

FUNCTION getPrivileges( res_path IN VARCHAR2) RETURN sys.xmltype;

Parameter	IN / OUT	Description
res_path	(IN)	Absolute path in the Hierarchy of the Oracle XML DB resource.

changePrivileges()

Description

Adds the given ACE to the given resource's ACL. Returns positive integer if ACL was successfully modified. For example,

     <ace  xmlns="http://xmlns.oracle.com/xdb/acl.xsd"
               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xmlns:dav="DAV:"
               xsi:schemaLocation="http://xmlns.oracle.com/xdb/acl.xsd
                                   http://xmlns.oracle.com/xdb/acl.xsd
                                   DAV:http://xmlns.oracle.com/xdb/dav.xsd"
          <grant>true</grant>
          <principal>SCOTT</principal>
          <privilege>
               <read-contents/>
               <read-properties/>
               <resolve/>
               <dav:waste/>
          </privilege>
     </ace>

Syntax

FUNCTION changePrivileges( res_path  IN  VARCHAR2,
                           ace       IN  xmltype)
                           RETURN pls_integer;

Parameter	IN / OUT	Description
res_path	(IN)	Pathname of the Oracle XML DB resource for which privileges need to be changed.
ace	(IN)	An XMLType instance of the <ace> element which specifies the <principal>, the operation <grant> and the list of privileges. See the preceding code example.

If no ACE with the same principal and the same operation (grant/deny) already exists in the ACL, the new ACE is added at the end of the ACL.

checkPrivileges()

Description

Checks access privileges granted to the current user on the specified Oracle XML DB resource. Returns positive integer if all requested privileges granted. For example, check for <read.contents>, <read.properties> and <dav:waste> privileges using the following <privilege> XMLType instance.

     <privilege xmlns="http://xmlns.oracle.com/xdb/acl.xsd"
               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xmlns:dav="DAV:"
               xsi:schemaLocation="http://xmlns.oracle.com/xdb/acl.xsd
                                   http://xmlns.oracle.com/xdb/acl.xsd
                                   DAV: http://xmlns.oracle.com/xdb/dav.xsd"
          <read-contents/>
          <read-properties/>
          <resolve/>
          <dav:waste/>
     </privilege>

Syntax

FUNCTION checkPrivileges( res_path   IN  VARCHAR2,
                          privs      IN  xmltype)
                          RETURN pls_integer;

Parameter	IN / OUT	Description
res_path	(IN)	Absolute path in the Hierarchy for Oracle XML DB resource.
privs	(IN)	An XMLType instance of the privilege element specifying the requested set of access privileges. See the preceding code example.

setacl()

Description

Sets the ACL on the given Oracle XML DB resource to be the ACL specified by path. The user must have <write-acl> privileges on the resource.

Syntax

PROCEDURE setacl( res_path   IN  VARCHAR2,
                 acl_path   IN  VARCHAR2);

Parameter	IN / OUT	Description
res_path	(IN)	Absolute path in the Hierarchy for Oracle XML DB resource.
acl_path	(IN)	Absolute path in the Hierarchy for Oracle XML DB ACL.

AclCheckPrivileges()

Description

Checks access privileges granted to the current user by specified ACL document on a resource whose owner is specified by the 'owner' parameter. Returns positive integer if all requested privileges granted.

Syntax

FUNCTION AclCheckPrivileges( acl_path  IN  VARCHAR2,
                             owner     IN  VARCHAR2,
                             privs     IN  xmltype)
                             RETURN pls_integer;

Parameter	IN / OUT	Description
acl_path	(IN)	Absolute path in the Hierarchy for ACL document.
owner	(IN)	Resource owner name; the pseudo user "DAV:owner" is replaced by this user during ACL privilege resolution.
privs	(IN)	An XMLType instance of the privilege element specifying the requested set of access privileges. See description for checkPrivileges()checkPrivileges()..

LockResource()

Description

Given a path to a resource, gets a WebDAV-style lock on that resource. Returns TRUE if operation successful; FALSE, otherwise. The user must have UPDATE privileges on the resource.

Syntax

FUNCTION LockResource( path      IN  VARCHAR2,
                       depthzero IN  BOOLEAN,
                       shared    IN  boolean)
                       RETURN BOOLEAN;

Parameter	IN / OUT	Description
path	(IN)	Path name of the resource to lock.
depthzero	(IN)	CURRENTLY UNSUPPORTED. At this time, only the given resource is locked by this function. In a future release, passing FALSE will obtain an infinite-depth lock.
shared	(IN)	Passing TRUE will obtain a shared write lock.

GetLockToken()

Description

Given a path to a resource, returns that resource's lock token for the current user. The user must have READPROPERTIES privilege on the resource.

Syntax

PROCEDURE GetLockToken( path      IN  VARCHAR2,
                        locktoken OUT VARCHAR2);

Parameter	IN / OUT	Description
path	(IN)	Path name to the resource.
locktoken	(OUT)	Logged-in user's lock token for the resource.

UnlockResource()

Description

Unlocks the resource given a lock token and a path to the resource. Returns TRUE if operation successful; FALSE, otherwise. The user must have UPDATE privileges on the resource.

Syntax

FUNCTION UnlockResource( path     IN  VARCHAR2,
                         deltoken IN  VARCHAR2)
                         RETURN BOOLEAN;

Parameter	IN / OUT	Description
path	(IN)	Path name to the resource.
deltoken	(IN)	Lock token to be removed.

CreateResource()

Description

Creates a new resource. Returns TRUE if operation successful; FALSE, otherwise.The options are described in the following table.

Syntax	Description
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 REF 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.

Parameter	IN / OUT	Description
path	(IN)	Path name of the resource to create. The path name's parent folder must already exist in the hierarchy. In other words, if '/foo/bar.txt' is passed in, then folder '/foo' must already exist.
data	(IN)	The new resource's contents. The data will be parsed to check if it contains a schema-based XML document, and the contents will be stored as schema-based in the schema's default table. Otherwise, it will be saved as binary data.
datarow	(IN)	REF to an XMLType row to be used as the contents.

CreateFolder()

Description

Creates a new folder resource in the hierarchy. Returns TRUE if operation successful; FALSE, otherwise. The given path name's parent folder must already exist in the hierarchy; for example, if '/folder1/folder2' is passed as the path parameter, then '/folder1' must already exist.

Syntax

FUNCTION CreateFolder( path   IN  VARCHAR2)
                       RETURN BOOLEAN;

Parameter	IN / OUT	Description
path	(IN)	Path name for the new folder.

DeleteResource()

Description

Deletes a resource from the hierarchy.

Syntax

PROCEDURE DeleteResource( path   IN  VARCHAR2);

Parameter	IN / OUT	Description
path	(IN)	Path name of the resource to delete.

Link()

Description

Creates a link to an existing resource. This procedures is analogous to creating a hard link in UNIX.

Syntax

PROCEDURE Link( srcpath    IN  VARCHAR2,
                linkfolder IN  VARCHAR2,
                linkname   IN  VARCHAR2);

Parameter	IN / OUT	Description
srcpath	(IN)	Path name of the resource to which a link is made
linkfolder	(IN)	Folder in which the new link is placed.
linkname	(IN)	Name of the new link.

CFG_Refresh()

Description

Refreshes the session's configuration information to the latest configuration.

Syntax

PROCEDURE CFG_Refresh;

CFG_Get()

Description

Retrieves the session's configuration information as an XMLType instance.

Syntax

FUNCTION CFG_Get RETURN SYS.XMLType;

CFG_Update()

Description

Updates the configuration information and commits the change.

Syntax

PROCEDURE CFG_Update( xdbconfig   IN  SYS.XMLTYPE);

Parameter	IN / OUT	Description
xdbconfig	(IN)	The new configuration data.