108
DBMS_XDB

The DBMS_XDB package supports the following features:

• Resource Management subprograms which complement Resource Views
• The Access Control List (ACL)-based Security Mechanism
• Configuration Session Management
• Creation of the XDB username

  See Also: Oracle XML DB Developer's Guide Oracle Database New Features

This chapter contains the following topics:

• Using DBMS_XDB
  • Overview
  • Constants
• Summary of DBMS_XDB Subprograms

---

Using DBMS_XDB

• Overview
• Constants

---

Overview

The DBMS_XDB package supports the following features:

• The Resource Management functionality provides LINK Procedure, EXISTSRESOURCE Function, LOCKRESOURCE Function, GETLOCKTOKEN Procedure, UNLOCKRESOURCE Function, CREATERESOURCE Functions, RENAMERESOURCE Procedure, DELETERESOURCE Procedure, GETRESOID Function, CREATEOIDPATH Function, REBUILDHIERARCHICALINDEX Procedure and CREATEFOLDER Function methods, which complement Resource Views.
• The Access Control List (ACL)-based Security Mechanism can be used with in-hierarchy ACLs stored by the database or in-memory ACLs that may be stored outside the database. Some of these methods can be used for both Oracle resources and arbitrary database objects. Use CHECKPRIVILEGES Function, GETACLDOCUMENT Procedure, CHANGEPRIVILEGES Function and GETPRIVILEGES Function for Oracle Resources. ACLCHECKPRIVILEGES Function provides access to Oracle's ACL-based Security mechanism without storing objects in the Hierarchy.
• Configuration Session Management is supported by CFG_REFRESH Procedure, CFG_GET Function and CFG_UPDATE Procedure. methods.
• The XDB username is created during XDB installation. This user owns a set of default tables and packages. GETXDB_TABLESPACE Function and MOVEXDB_TABLESPACE Procedure enable movement of schemas to a specified tablespace, and support the default SYSAUX tablespace introduction

---

Constants

Table 108-1  Defined Constants for DBMS_XDB

Constant	Definition	Description
DELTE_RESOURCE	CONSTANT NUMBER :=1	Deletes a resource; fails if the resource has children.
DELETE_RECURSIVE	CONSTANT NUMBER :=2	Deletes a resource and its children, if any.
DELETE_FORCE	CONSTANT NUMBER :=3	Deletes the resource, even if the object it contains is invalid.
DELETE_RECURSIVE_FORCE	CONSTANT NUMBER :=4	Deletes a resource and its children, if any, even if the object it contains is invalid.

---

Summary of DBMS_XDB Subprograms

Table 108-2  DBMS_XDB Package Subprograms

Subprogram	Description
ACLCHECKPRIVILEGES Function	Checks access privileges granted to the current user by specified ACL document on a resource whose owner is specified by the 'owner' parameter.
CFG_GET Function	Retrieves the session's configuration information
CFG_REFRESH Procedure	Refreshes the session's configuration information to the latest configuration
CFG_UPDATE Procedure	Updates the configuration information
CHANGEPRIVILEGES Function	Adds the given ACE to the given resource's ACL
CHECKPRIVILEGES Function	Checks access privileges granted to the current user on the specified resource
CREATEFOLDER Function	Creates a new folder resource in the hierarchy
CREATEOIDPATH Function	Creates a virtual path to the resource based on object ID
CREATERESOURCE Functions	Creates a new resource
DELETERESOURCE Procedure	Deletes a resource from the hierarchy
EXISTSRESOURCE Function	Determines if a resource is the hierarchy, based on its absolute path
GETACLDOCUMENT Procedure	Retrieves ACL document that protects resource given its path name
GETLOCKTOKEN Procedure	Returns that resource's lock token for the current user given a path to a resource
GETPRIVILEGES Function	Gets all privileges granted to the current user on the given resource
GETRESOID Function	Returns the object ID of the resource from its absolute path
GETXDB_TABLESPACE Function	Returns the current tablespace of the XDB (user)
LINK Procedure	Creates a link to an existing resource
LOCKRESOURCE Function	Gets a WebDAV-style lock on that resource given a path to that resource
MOVEXDB_TABLESPACE Procedure	Moves the XDB (user) to the specified tablespace
REBUILDHIERARCHICALINDEX Procedure	Rebuilds the hierarchical index after import or export operations
RENAMERESOURCE Procedure	Renames the XDB resource
SETACL Procedure	Sets the ACL on the given resource
UNLOCKRESOURCE Function	Unlocks the resource given a lock token and resource path

---

ACLCHECKPRIVILEGES Function

This function checks access privileges granted to the current user by specified ACL document by the OWNER of the resource. Returns positive integer if all privileges are granted.

Syntax

DBMS_XDB.ACLCHECKPRIVILEGES(
   acl_path  IN  VARCHAR2,
   owner     IN  VARCHAR2,
   privs     IN  xmltype)
 RETURN PLS_INTEGER;

Parameters

Table 108-3  ACLCHECKPRIVILEGES Function Parameters

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

---

CFG_GET Function

This function retrieves the session's configuration information as an XMLType instance.

Syntax

DBMS_XDB.CFG_GET 
 RETURN SYS.XMLType;

---

CFG_REFRESH Procedure

This procedure refreshes the session's configuration information to the latest configuration.

Syntax

DBMS_XDB.CFG_REFRESH;

---

CFG_UPDATE Procedure

This procedure updates the configuration information and commits the change.

Syntax

DBMS_XDB.CFG_UPDATE(
   xdbconfig   IN  SYS.XMLTYPE);

Parameters

Table 108-4 CFG_UPDATE Procedure Parameters

Parameter	Description
xdbconfig	The new configuration data.

---

CHANGEPRIVILEGES Function

This function adds the given ACE to the given resource's ACL.

Syntax

DBMS_XDB.CHANGEPRIVILEGES(
   res_path   IN    VARCHAR2,
   ace        IN    xmltype)
 RETURN PLS_INTEGER;

Parameters

Table 108-5  CHANGEPRIVILEGES Function Parameters

Parameter	Description
res_path	Path name of the resource for which privileges need to be changed.
ace	An XMLType instance of the <ace> element which specifies the <principal>, the operation <grant> and the list of privileges.

Return Values

It returns a positive integer if the ACL was successfully modified.

Usage Notes

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 Function

This function checks access privileges granted to the current user on the specified resource.

Syntax

DBMS_XDB.CHECKPRIVILEGES(
   res_path   IN  VARCHAR2,
   privs      IN  xmltype)
 RETURN PLS_INTEGER;

Parameters

Table 108-6  CHECKPRIVILEGES Function Parameters

Parameter	Description
res_path	Absolute path in the Hierarchy for resource.
privs	An XMLType instance of the privilege element specifying the requested set of access privileges.

Return Values

Returns positive integer if all requested privileges granted.

---

CREATEFOLDER Function

This function creates a new folder resource in the hierarchy.

Syntax

DBMS_XDB.CREATEFOLDER(
   path   IN  VARCHAR2)
 RETURN BOOLEAN;

Parameters

Table 108-7  CREATEFOLDER Function Parameters

Parameter	Description
path	Path name for the new folder.

Return Values

Returns TRUE if operation successful; FALSE, otherwise.Returns TRUE if operation successful; FALSE, otherwise.

Usage Notes

The given path name's parent folder must already exist in the hierarchy: if '/folder1/folder2' is passed as the path parameter, then '/folder1' must already exist.

---

CREATEOIDPATH Function

This function creates a virtual path to the resource based on object ID.

Syntax

DBMS_XDB.CREATEOIDPATH(
   oid    IN   RAW)
 RETURN VARCHAR2;

Parameters

Table 108-8  CREATEOIDPATH Function Parameters

Parameter	Description
oid	Object ID of the resource.

---

CREATERESOURCE Functions

The functions create a new resource. The description of the overload options precede each version of the syntax

Syntax

Creates a new resource with the given string as its contents:

DBMS_XDB.CREATERESOURCE( 
   path    IN  VARCHAR2,
   data    IN  VARCHAR2)
 RETURN BOOLEAN;

Creates a new resource with the given XMLType data as its contents:

DBMS_XDB.CREATERESOURCE(
   path    IN  VARCHAR2,
   data    IN  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:

DBMS_XDB.CREATERESOURCE(
   path     IN  VARCHAR2,
   datarow  IN  REF SYS.XMLTYPE)
 RETURN BOOLEAN;

Creates a resource with the given BLOB as its contents, and specifies character set of the source BLOB:

DBMS_XDB.CREATERESOURCE(
   path    IN  VARCHAR2,
   data    IN  BLOB,
   csid    IN  NUMBER :=0)
 RETURN BOOLEAN; 

Creates a resource with the given BFILE as its contents, and specifies character set of the source BFILE:

DBMS_XDB.CREATERESOURCE( 
   path    IN  VARCHAR2,
   data    IN  BFILE,
   csid    IN  NUMBER :=0)
 RETURN BOOLEAN;

Creates a resource with the given CLOB as its contents:

DBMS_XDB.CREATERESOURCE(
   path    IN  VARCHAR2,
   data    IN  CLOB)
 RETURN BOOLEAN; 

Parameters

Table 108-9  CREATERESOURCE Function Parameters

Parameter	Description
path	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	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	REF to an XMLType row to be used as the contents.
csid	Character set id of the document. Must be a valid Oracle id; otherwise returns an error. If a zero CSID is specified then the data is defaulted to the database character set. Otherwise, the encoding of the data is determined as follows: From the path extension, determine the resource's MIME type. If the MIME type is */xml, then the encoding is detected based on Appendix F of the W3C XML 1.0 Reference at http://www.w3.org/TR/2000/REC-xml-20001006; otherwise, it is defaulted to the database character set.

Return Values

Returns TRUE if operation successful; FALSE, otherwise.

---

DELETERESOURCE Procedure

This procedure deletes a resource from the hierarchy.

Syntax

DBMS_XDB.DELETERESOURCE(
   path          IN      VARCHAR2,
   delete_option IN      PLS_INTEGER);

Parameters

Table 108-10  DELETERESOURCE Procedure Parameters

Parameter	Description
path	Path name of the resource to delete.
delete_option	The option that controls how a a resource is deleted; defined in Table 108-1: DELETE_RESOURCE DELETE_RECURSIVE DELETE_FORCE DELETE_RECURSIVE_FORCE

---

EXISTSRESOURCE Function

This function indicates if a resource is in the hierarchy. Matches resource by a string that represents its absolute path.

Syntax

DBMS_XDB.EXISTSRESOURCE(
   abspath    IN    VARCHAR2)
 RETURN BOOLEAN;

Parameters

Table 108-11 EXISTSRESOURCE Function Parameters

Parameter	Description
abspath	Path name of the resource whose ACL document is required.

Return Values

Returns TRUE if the resource is found.

---

GETACLDOCUMENT Procedure

This procedure retrieves ACL document that protects resource given its path name.

Syntax

DBMS_XDB.GETACLDOCUMENT(
   abspath  IN  VARCHAR2)
   RETURN sys.xmltype;

Parameters

Table 108-12 GETACLDOCUMENT Function Parameters

Parameter	Description
abspath	Path name of the resource whose ACL document is required.

Return Values

Returns the XMLType for ACL document.

---

GETLOCKTOKEN Procedure

Given a path to a resource, this procedure returns that resource's lock token for the current user.

Syntax

DBMS_XDB.GETLOCKTOKEN(
   path         IN      VARCHAR2,
   locktoken    OUT     VARCHAR2);

Parameters

Table 108-13  GETLOCKTOKEN Procedure Parameters

Parameter	Description
path	Path name to the resource.
locktoken	Logged-in user's lock token for the resource.

Usage Notes

The user must have READPROPERTIES privilege on the resource.

---

GETPRIVILEGES Function

This function gets all privileges granted to the current user on the given resource.

Syntax

DBMS_XDB.GETPRIVILEGES(
   res_path    IN     VARCHAR2)
 RETURN sys.xmltype;

Parameters

Table 108-14 GETPRIVILEGES Function Parameters

Parameter	Description
res_path	Absolute path in the hierarchy of the resource.

Return Values

Returns an XMLType instance of <privilege> element, which contains the list of all leaf privileges granted on this resource to the current user.

---

GETRESOID Function

Returns the object ID of the resource from its absolute path.

Syntax

DBMS_XDB.GETRESOID(
   abspath IN VARCHAR2)
RETURN RAW;

Parameters

Table 108-15 GETRESOID Function Parameters

Parameter	Description
abspath_path	Absolute path of the resource.

Return Values

Returns NULL if the resource is not present.

---

GETXDB_TABLESPACE Function

This function returns the current tablespace of the XDB (user).

Syntax

DBMS_XDB.GETXDB_TABLESPACE
 RETURN VARCHAR2;

---

LINK Procedure

This procedure creates a link to an existing resource.

Syntax

DBMS_XDB.LINK(
   srcpath    IN  VARCHAR2,
   linkfolder IN  VARCHAR2,
   linkname   IN  VARCHAR2);

Parameters

Table 108-16 LINK Procedure Parameters

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

---

LOCKRESOURCE Function

Given a path to a resource, this function gets a WebDAV-style lock on that resource.

Syntax

DBMS_XDB.LOCKRESOURCE(
   path      IN  VARCHAR2,
   depthzero IN  BOOLEAN,
   shared    IN  boolean)
RETURN BOOLEAN;

Parameters

Table 108-17  LOCKRESOURCE Function Parameters

Parameter	Description
path	Path name of the resource to lock.
depthzero	NOT SUPPORTED. Only given resource is locked. In future releases, passing FALSE will obtain an infinite-depth lock.
shared	Passing TRUE will obtain a shared write lock.

Return Values

Returns TRUE if successful.

Usage Notes

The user must have UPDATE privileges on the resource.

---

MOVEXDB_TABLESPACE Procedure

This procedure moves the XDB (user) to the specified tablespace.

Syntax

DBMS_XDB.MOVEXDB_TABLESPACE(
   new_tablespace   IN  VARCHAR2);

Parameters

Table 108-18 MOVEXDB_TABLESPACE Procedure Parameters

Parameter	Description
new_tablespace	Name of the tablespace where the XDB will be moved.

Usage Notes

This operation waits for all concurrent XDB sessions to exit.

---

REBUILDHIERARCHICALINDEX Procedure

This procedure rebuilds the hierarchical index after import or export operations. This is necessary because data cannot be exported from index tables.

Syntax

DBMS_XDB.REBUILDHIERARCHICALINDEX;

---

RENAMERESOURCE Procedure

This procedure renames the XDB resource.

Syntax

DBMS_XDB.RENAMERESOURCE(
   srcpath    IN  VARCHAR2,
   destfolder IN  CARCHAR2,
   newname    IN  VARCHAR2);

Parameters

Table 108-19  RENAMERESOURCE Procedure Parameters

Parameter	Description
srcpath	Absolute path in the Hierarchy for the source resource destination folder.
destfolder	Absolute path in the Hierarchy for the destination folder.
newname	Name of the child in the destination folder.

---

SETACL Procedure

Sets the ACL on the given resource to be the ACL specified by path.

Syntax

DBMS_XDB.SETACL(
   res_path   IN  VARCHAR2,
   acl_path   IN  VARCHAR2);

Parameters

Table 108-20 SETACL Procedure Parameters

Parameter	Description
res_path	Absolute path in the Hierarchy for resource.
acl_path	Absolute path in the Hierarchy for ACL.

Usage Notes

The user must have <write-acl> privileges on the resource.

---

UNLOCKRESOURCE Function

This function unlocks the resource given a lock token and a path to the resource.

Syntax

DBMS_XDB.UNLOCKRESOURCE(
   path     IN  VARCHAR2,
   deltoken IN  VARCHAR2)
 RETURN BOOLEAN;

Parameters

Table 108-21 UNLOCKRESOURCE Function Parameters

Parameter	Description
path	Path name to the resource.
deltoken	Lock token to be removed.

Return Values

Returns TRUE if operation successful.

Usage Notes

The user must have UPDATE privileges on the resource.