Oracle® Database PL/SQL Packages and Types Reference 10g Release 2 (10.2) Part Number B14258-01 |
|
|
View PDF |
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
This chapter contains the following topics:
Overview
Constants
This section contains topics which relate to using the DBMS_XDB
package.
The DBMS_XDB
package supports the following features:
The Resource Management functionality providesLINK Procedure, EXISTSRESOURCE Function, LOCKRESOURCE Function, GETLOCKTOKEN Procedure, UNLOCKRESOURCE Function, CREATERESOURCE Functions, RENAMERESOURCE Procedure, DELETERESOURCE Procedure, GETRESOID Function, CREATEOIDPATH Function, REBUILDHIERARCHICALINDEX Procedure and CREATEFOLDER Function subprograms 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 Function, CHANGEPRIVILEGES Function and GETPRIVILEGES Function, LINK Procedure, LINK Procedure, LINK Procedure, LINK Procedure, LINK Procedure, LINK Procedure 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
Table 120-1 Defined Constants for DBMS_XDB
Constant | Type | Value | Description |
---|---|---|---|
DELETE_RESOURCE |
NUMBER |
1 | Deletes a resource; fails if the resource has children. |
DELETE_RECURSIVE |
NUMBER |
2 | Deletes a resource and its children, if any. |
DELETE_FORCE |
NUMBER |
3 | Deletes the resource, even if the object it contains is invalid. |
DELETE_RECURSIVE_FORCE |
NUMBER |
4 | Deletes a resource and its children, if any, even if the object it contains is invalid. |
Table 120-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. |
APPENDRESOURCEMETADATA Procedure |
Takes in user-defined metadata either as a REF to XMLTYPE or an XMLTYPE and adds it to the desired resource |
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 |
DELETERESOURCEMETADATA Procedures |
Deletes metadata from a resource (can be used for schema-based or nonschema-based metadata) |
EXISTSRESOURCE Function |
Determines if a resource is the hierarchy, based on its absolute path |
GETACLDOCUMENT Function |
Retrieves ACL document that protects resource given its path name |
GETFTPPORT Function |
Gets the value of the current FTP port |
GETHTTPPORT Function |
Gets the value of the current HTTP port |
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 |
PURGERESOURCEMETADATA Procedure |
Deletes all user metadata from a resource. |
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 |
SETFTPPORT Procedure |
Sets the FTP port to a new value |
SETHTTPPORT Procedure |
Sets the HTTP port to a new value |
UPDATERESOURCEMETADATA Procedures |
Updates metadata for a resource |
UNLOCKRESOURCE Function |
Unlocks the resource given a lock token and resource path |
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 120-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. |
This procedure takes in user-defined metadata either as a REF
to XMLTYPE
or an XMLTYPE
and adds it to the desired resource.
Syntax
DBMS_XDB.APPENDRESOURCEMETADATA ( abspath IN VARCHAR2, metadata IN XMLTYPE); DBMS_XDB.APPENDRESOURCEMETADATA ( abspath IN VARCHAR2, metadata IN REF SYS.XMLTYPE);
Parameters
Table 120-4 APPENDRESOURCEMETADATA Procedure
Parameter | Description |
---|---|
abspath |
Absolute path of the resource |
metadata |
Metadata can be schema based or nonschema-based. Schema-based metadata will be stored in its own table. |
Usage Notes
In the case in which a REF
is passed in, the procedure stores the REF
in the resource, and the metadata is stored in a separate table. In this case you are responsible for populating the RESID
column for the metadata table. Note that theREF
passed in must be unique. In other words, there must not be aREF
with the same value in the resource metadata, as this would violate uniqueness of properties. An error will be thrown if users attempt to add a REF
that already exists.
In the case where the XMLTYPE is passed in, the data is parsed to determine if it is schema-based or not and stored accordingly.
This function retrieves the session's configuration information as an XMLType
instance.
Syntax
DBMS_XDB.CFG_GET RETURN SYS.XMLType;
This procedure refreshes the session's configuration information to the latest configuration.
Syntax
DBMS_XDB.CFG_REFRESH;
This procedure updates the configuration information and commits the change.
Syntax
DBMS_XDB.CFG_UPDATE( xdbconfig IN SYS.XMLTYPE);
Parameters
Table 120-5 CFG_UPDATE Procedure Parameters
Parameter | Description |
---|---|
xdbconfig |
The new configuration data |
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 120-6 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
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.
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 120-7 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
A positive integer if all requested privileges granted.
This function creates a new folder resource in the hierarchy.
Syntax
DBMS_XDB.CREATEFOLDER( path IN VARCHAR2) RETURN BOOLEAN;
Parameters
Table 120-8 CREATEFOLDER Function Parameters
Parameter | Description |
---|---|
path |
Path name for the new folder |
Return Values
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.
This function creates a virtual path to the resource based on object ID.
Syntax
DBMS_XDB.CREATEOIDPATH( oid IN RAW) RETURN VARCHAR2;
Parameters
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 120-10 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:
|
Return Values
TRUE
if operation successful; FALSE
, otherwise.
This procedure deletes a resource from the hierarchy.
Syntax
DBMS_XDB.DELETERESOURCE( path IN VARCHAR2, delete_option IN PLS_INTEGER);
Parameters
Table 120-11 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 120-1:
|
This procedure takes in a resource by absolute path and removes either the schema-based metadata identified by the REF, or the metadata identified by the namespace and name combination, which can be either schema-based or non-schema based. It will also take an additional (optional) parameter that specifies how to delete it. This parameter is only relevant for schema-based resource metadata that needs to be deleted. For non-schema based metadata, this parameter is ignored.
Syntax
Can be used only or schema-based metadata:
DBMS_XDB.DELETERESOURCEMETADATA ( abspath IN VARCHAR2, metadata IN REF SYS.XMLTYPE, delete_option IN pls_integer := dbms_xdb.DELETE_RESOURCE_METADATA_CASCADE);
Can be used for schema-based or nonschema-based metadata:
DBMS_XDB.DELETERESOURCEMETADATA ( abspath IN VARCHAR2, metadatans IN VARCHAR2, metadataname IN VARCHAR2, delete_option IN pls_integer := dbms_xdb.DELETE_RESOURCE_METADATA_CASCADE);
Parameters
Table 120-12 DELETERESOURCEMETADATA Procedure Parameters
Parameter | Description |
---|---|
abspath |
Absolute path of the resource |
metadata |
REF to the piece of metadata (schema based) to be deleted |
mettadatans |
Namespace of the metadata fragment to be removed |
mettadataname |
Local name of the metadata fragment to be removed |
delete_option |
Only applicable for schema-based metadata, this can be one of the following:
|
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 120-13 EXISTSRESOURCE Function Parameters
Parameter | Description |
---|---|
abspath |
Path name of the resource whose ACL document is required |
Return Values
TRUE
if the resource is found.
This function retrieves ACL document that protects resource given its path name.
Syntax
DBMS_XDB.GETACLDOCUMENT( abspath IN VARCHAR2) RETURN sys.xmltype;
Parameters
Table 120-14 GETACLDOCUMENT Function Parameters
Parameter | Description |
---|---|
abspath |
Path name of the resource whose ACL document is required |
Return Values
The XMLType
for ACL document.
This procedure gets the value of the current FTP port.
Syntax
DBMS_XDB.GETFTPPORT RETURN NUMBER;
This procedure gets the value of the current HTTP port.
Syntax
DBMS_XDB.GETHTTPPORT RETURN NUMBER;
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 120-15 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.
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 120-16 GETPRIVILEGES Function Parameters
Parameter | Description |
---|---|
res_path |
Absolute path in the hierarchy of the resource |
Return Values
An XMLType
instance of <privilege>
element, which contains the list of all leaf privileges granted on this resource to the current user.
Returns the object ID of the resource from its absolute path.
Syntax
DBMS_XDB.GETRESOID( abspath IN VARCHAR2) RETURN RAW;
Parameters
Table 120-17 GETRESOID Function Parameters
Parameter | Description |
---|---|
abspath_path |
Absolute path of the resource |
Return Values
NULL
if the resource is not present.
This function returns the current tablespace of the XDB (user).
Syntax
DBMS_XDB.GETXDB_TABLESPACE RETURN VARCHAR2;
This procedure creates a link to an existing resource.
Syntax
DBMS_XDB.LINK( srcpath IN VARCHAR2, linkfolder IN VARCHAR2, linkname IN VARCHAR2);
Parameters
Table 120-18 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 |
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 120-19 LOCKRESOURCE Function Parameters
Parameter | Description |
---|---|
path |
Path name of the resource to lock. |
depthzero |
Currently not supported |
shared |
Passing TRUE will obtain a shared write lock |
Return Values
TRUE
if successful.
Usage Notes
The user must have UPDATE
privileges on the resource.
This procedure moves the XDB (user) to the specified tablespace.
Syntax
DBMS_XDB.MOVEXDB_TABLESPACE( new_tablespace IN VARCHAR2);
Parameters
Table 120-20 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.
This procedure deletes all user metadata from a resource. Schema-based metadata is removed in cascade mode, rows being deleted from the corresponding metadata tables.
Syntax
DBMS_XDB.PURGERESOURCEMETADATA( abspath IN VARCHAR2);
Parameters
Table 120-21 PURGERESOURCEMETADATA Procedure Parameters
Parameter | Description |
---|---|
abspath |
Absolute path of the resource |
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;
This procedure renames the XDB resource.
Syntax
DBMS_XDB.RENAMERESOURCE( srcpath IN VARCHAR2, destfolder IN CARCHAR2, newname IN VARCHAR2);
Parameters
Table 120-22 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 |
This 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 120-23 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.
This procedure sets the FTP port to a new value.
Syntax
DBMS_XDB.SETFTPPORT( new_port IN NUMBER);
Parameters
Table 120-24 SETFTPPORT Procedure Parameters
Parameter | Description |
---|---|
new_port | Value to which the FTP port will be set |
This procedure sets the HTTP port to a new value.
Syntax
DBMS_XDB.SETHTTPPORT( new_port IN NUMBER);
Parameters
Table 120-25 SETHTTPPORT Procedure Parameters
Parameter | Description |
---|---|
new_port | Value to which the HTTP port will be set |
This procedure updates metadata for a resource. The procedure takes in a resource identified by absolute path and the metadata in it to replace identified by its REF
. It replaces that piece of metadata with user-defined metadata which is either in the form of a REF
to XMLTYPE
or an XMLTYPE
.
Syntax
Can be used to update schema-based metadata only. The new metadata must be schema-based:
DBMS_XDB.UPDATERESOURCEMETADATA( abspath IN VARCHAR2, oldmetadata IN REF SYS.XMLTYPE, newmetadata IN REF SYS.XMLTYPE)
Can be used to update schema-based metadata only. The new metadata must be schema-based or nonschema-based:
DBMS_XDB.UPDATERESOURCEMETADATA( abspath IN VARCHAR2, oldmetadata IN REF SYS.XMLTYPE, newmetadata IN XMLTYPE);
Can be used for both schema-based and nonschema-based metadata:
DBMS_XDB.UPDATERESOURCEMETADATA( abspath IN VARCHAR2, oldns IN VARCHAR2, oldname IN VARCHAR, newmetadata IN XMLTYPE);
Can be used for both schema-based or nonschema-based metadata. New metadata must be schema-based:
DBMS_XDB.UPDATERESOURCEMETADATA( abspath IN VARCHAR2, oldns IN VARCHAR2, oldname IN VARCHAR, newmetadata IN REF SYS.XMLTYPE);
Parameters
Table 120-26 UPDATERESOURCEMETADATA Procedure Parameters
Parameter | Description |
---|---|
abspath |
Absolute path of the resource |
oldmetadata |
REF to the old of metadata |
newmetadata |
REF to the new, replacement metadata (can be either schema-based or nonschema-based depending on the overload) |
oldns |
Namespace identifying old metadata |
oldname |
Local name identifying old metadata |
Usage Notes
In the case of REF
, it stores the REF
in the resource and the metadata is stored in a separate table. Uniqueness of REFs
is enforced. In the case where the XMLTYPE
is passed in, data is parsed to determine if it is schema-based or not and is stored accordingly.
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 120-27 UNLOCKRESOURCE Function Parameters
Parameter | Description |
---|---|
path |
Path name to the resource |
deltoken |
Lock token to be removed |
Return Values
TRUE
if operation successful.
Usage Notes
The user must have UPDATE
privileges on the resource.