DBMS_XDB, 2 of 2

Functions and Procedures of DBMS_XDB

Table 81-1: Summary of Functions and Procedures of DBMS_XDB

Function/Procedure	Description
getAclDocument()	Retrieves ACL document that protects resource given its pathname.
getPrivileges()	Gets all privileges granted to the current user on the given XDB resource.
changePrivileges()	Adds the given ACE to the given resource's ACL.
checkPrivileges()	Checks access privileges granted to the current user on the specified XDB resource.
setacl()	Sets the ACL on the given XDB 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()

Retrieves ACL document that protects resource given its pathname; 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()

Gets all privileges granted to the current user on the given XDB 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 XDB resource.

changePrivileges()

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 XDB 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 above 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()

Checks access privileges granted to the current user on the specified XDB 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 XDB resource.
privs	(IN)	An XMLType instance of the privilege element specifying the requested set of access privileges. See the above code example.

setacl()

Sets the ACL on the given XDB 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 XDB resource.
acl_path	(IN)	Absolute path in the Hierarchy for XDB ACL.

AclCheckPrivileges()

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

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

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

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

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

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, i.e. 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()

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

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

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

Syntax

PROCEDURE CFG_Refresh;

CFG_Get()

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

Syntax

FUNCTION CFG_Get RETURN SYS.XMLType;

CFG_Update()

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.