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 121-1 Defined Constants for DBMS_XDB
Constant | Type | Value | Description |
---|---|---|---|
|
|
1 |
Deletes a resource; fails if the resource has children. |
|
|
2 |
Deletes a resource and its children, if any. |
|
|
3 |
Deletes the resource, even if the object it contains is invalid. |
|
|
4 |
Deletes a resource and its children, if any, even if the object it contains is invalid. |
Table 121-2 DBMS_XDB Package Subprograms
Subprogram | Description |
---|---|
Checks access privileges granted to the current user by specified ACL document on a resource whose owner is specified by the 'owner' parameter. |
|
Takes in user-defined metadata either as a |
|
Retrieves the session's configuration information |
|
Refreshes the session's configuration information to the latest configuration |
|
Updates the configuration information |
|
Adds the given ACE to the given resource's ACL |
|
Checks access privileges granted to the current user on the specified resource |
|
Creates a new folder resource in the hierarchy |
|
Creates a virtual path to the resource based on object ID |
|
Creates a new resource |
|
Deletes a resource from the hierarchy |
|
Deletes metadata from a resource (can be used for schema-based or nonschema-based metadata) |
|
Determines if a resource is the hierarchy, based on its absolute path |
|
Retrieves ACL document that protects resource given its path name |
|
Gets the value of the current FTP port |
|
Gets the value of the current HTTP port |
|
Returns that resource's lock token for the current user given a path to a resource |
|
Gets all privileges granted to the current user on the given resource |
|
Returns the object ID of the resource from its absolute path |
|
Returns the current tablespace of the XDB (user) |
|
Creates a link to an existing resource |
|
Gets a WebDAV-style lock on that resource given a path to that resource |
|
Moves the XDB (user) to the specified tablespace |
|
Deletes all user metadata from a resource. |
|
Rebuilds the hierarchical index after import or export operations |
|
Renames the XDB resource |
|
Sets the ACL on the given resource |
|
Sets the FTP port to a new value |
|
Sets the HTTP port to a new value |
|
Updates metadata for a resource |
|
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.
DBMS_XDB.ACLCHECKPRIVILEGES( acl_path IN VARCHAR2, owner IN VARCHAR2, privs IN xmltype) RETURN PLS_INTEGER;
Table 121-3 ACLCHECKPRIVILEGES Function Parameters
Parameter | Description |
---|---|
|
Absolute path in the Hierarchy for ACL document |
|
Resource owner name; the pseudo user "DAV:owner" is replaced by this user during ACL privilege resolution |
|
An |
This procedure takes in user-defined metadata either as a REF
to XMLTYPE
or an XMLTYPE
and adds it to the desired resource.
DBMS_XDB.APPENDRESOURCEMETADATA ( abspath IN VARCHAR2, metadata IN XMLTYPE); DBMS_XDB.APPENDRESOURCEMETADATA ( abspath IN VARCHAR2, metadata IN REF SYS.XMLTYPE);
Table 121-4 APPENDRESOURCEMETADATA Procedure
Parameter | Description |
---|---|
|
Absolute path of the resource |
|
Metadata can be schema based or nonschema-based. Schema-based metadata will be stored in its own table. |
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.
DBMS_XDB.CFG_GET RETURN SYS.XMLType;
This procedure refreshes the session's configuration information to the latest configuration.
DBMS_XDB.CFG_REFRESH;
This procedure updates the configuration information and commits the change.
DBMS_XDB.CFG_UPDATE( xdbconfig IN SYS.XMLTYPE);
Table 121-5 CFG_UPDATE Procedure Parameters
Parameter | Description |
---|---|
|
The new configuration data |
This function adds the given ACE to the given resource's ACL.
DBMS_XDB.CHANGEPRIVILEGES( res_path IN VARCHAR2, ace IN xmltype) RETURN PLS_INTEGER;
Table 121-6 CHANGEPRIVILEGES Function Parameters
Parameter | Description |
---|---|
|
Path name of the resource for which privileges need to be changed |
|
An |
A positive integer if the ACL was successfully modified.
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.
DBMS_XDB.CHECKPRIVILEGES( res_path IN VARCHAR2, privs IN xmltype) RETURN PLS_INTEGER;
Table 121-7 CHECKPRIVILEGES Function Parameters
Parameter | Description |
---|---|
|
Absolute path in the Hierarchy for resource |
|
An |
A positive integer if all requested privileges granted.
This function creates a new folder resource in the hierarchy.
DBMS_XDB.CREATEFOLDER( path IN VARCHAR2) RETURN BOOLEAN;
Table 121-8 CREATEFOLDER Function Parameters
Parameter | Description |
---|---|
|
Path name for the new folder |
TRUE
if operation successful; FALSE
, otherwise.
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.
DBMS_XDB.CREATEOIDPATH( oid IN RAW) RETURN VARCHAR2;
The functions create a new resource. The description of the overload options precede each version of the 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;
Table 121-10 CREATERESOURCE Function Parameters
Parameter | Description |
---|---|
|
Path name of the resource to create. The path name's parent folder must already exist in the hierarchy. In other words, if |
|
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. |
|
|
|
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:
|
TRUE
if operation successful; FALSE
, otherwise.
This procedure deletes a resource from the hierarchy.
DBMS_XDB.DELETERESOURCE( path IN VARCHAR2, delete_option IN PLS_INTEGER);
Table 121-11 DELETERESOURCE Procedure Parameters
Parameter | Description |
---|---|
|
Path name of the resource to delete |
|
The option that controls how a a resource is deleted; defined in Table 121-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.
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);
Table 121-12 DELETERESOURCEMETADATA Procedure Parameters
Parameter | Description |
---|---|
|
Absolute path of the resource |
|
|
|
Namespace of the metadata fragment to be removed |
|
Local name of the metadata fragment to be removed |
|
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.
DBMS_XDB.EXISTSRESOURCE( abspath IN VARCHAR2) RETURN BOOLEAN;
Table 121-13 EXISTSRESOURCE Function Parameters
Parameter | Description |
---|---|
|
Path name of the resource whose ACL document is required |
TRUE
if the resource is found.
This function retrieves ACL document that protects resource given its path name.
DBMS_XDB.GETACLDOCUMENT( abspath IN VARCHAR2) RETURN sys.xmltype;
Table 121-14 GETACLDOCUMENT Function Parameters
Parameter | Description |
---|---|
|
Path name of the resource whose ACL document is required |
The XMLType
for ACL document.
This procedure gets the value of the current FTP port.
DBMS_XDB.GETFTPPORT RETURN NUMBER;
This procedure gets the value of the current HTTP port.
DBMS_XDB.GETHTTPPORT RETURN NUMBER;
Given a path to a resource, this procedure returns that resource's lock token for the current user.
DBMS_XDB.GETLOCKTOKEN( path IN VARCHAR2, locktoken OUT VARCHAR2);
Table 121-15 GETLOCKTOKEN Procedure Parameters
Parameter | Description |
---|---|
|
Path name to the resource |
|
Logged-in user's lock token for the resource |
The user must have READPROPERTIES
privilege on the resource.
This function gets all privileges granted to the current user on the given resource.
DBMS_XDB.GETPRIVILEGES( res_path IN VARCHAR2) RETURN sys.xmltype;
Table 121-16 GETPRIVILEGES Function Parameters
Parameter | Description |
---|---|
|
Absolute path in the hierarchy of the resource |
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.
DBMS_XDB.GETRESOID( abspath IN VARCHAR2) RETURN RAW;
Table 121-17 GETRESOID Function Parameters
Parameter | Description |
---|---|
|
Absolute path of the resource |
NULL
if the resource is not present.
This function returns the current tablespace of the XDB (user).
DBMS_XDB.GETXDB_TABLESPACE RETURN VARCHAR2;
This procedure creates a link to an existing resource.
DBMS_XDB.LINK( srcpath IN VARCHAR2, linkfolder IN VARCHAR2, linkname IN VARCHAR2);
Table 121-18 LINK Procedure Parameters
Parameter | Description |
---|---|
|
Path name of the resource to which a link is made |
|
Folder in which the new link is placed |
|
Name of the new link |
Given a path to a resource, this function gets a WebDAV-style lock on that resource.
DBMS_XDB.LOCKRESOURCE( path IN VARCHAR2, depthzero IN BOOLEAN, shared IN boolean) RETURN BOOLEAN;
Table 121-19 LOCKRESOURCE Function Parameters
Parameter | Description |
---|---|
|
Path name of the resource to lock. |
|
Currently not supported |
|
Passing |
TRUE
if successful.
The user must have UPDATE
privileges on the resource.
This procedure moves the XDB (user) to the specified tablespace.
DBMS_XDB.MOVEXDB_TABLESPACE( new_tablespace IN VARCHAR2);
Table 121-20 MOVEXDB_TABLESPACE Procedure Parameters
Parameter | Description |
---|---|
|
Name of the tablespace where the XDB will be moved |
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.
DBMS_XDB.PURGERESOURCEMETADATA( abspath IN VARCHAR2);
Table 121-21 PURGERESOURCEMETADATA Procedure Parameters
Parameter | Description |
---|---|
|
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.
DBMS_XDB.REBUILDHIERARCHICALINDEX;
This procedure renames the XDB resource.
DBMS_XDB.RENAMERESOURCE( srcpath IN VARCHAR2, destfolder IN CARCHAR2, newname IN VARCHAR2);
Table 121-22 RENAMERESOURCE Procedure Parameters
Parameter | Description |
---|---|
|
Absolute path in the Hierarchy for the source resource destination folder |
|
Absolute path in the Hierarchy for the destination folder |
|
Name of the child in the destination folder |
This procedure sets the ACL on the given resource to be the ACL specified by path.
DBMS_XDB.SETACL( res_path IN VARCHAR2, acl_path IN VARCHAR2);
Table 121-23 SETACL Procedure Parameters
Parameter | Description |
---|---|
|
Absolute path in the Hierarchy for resource |
|
Absolute path in the Hierarchy for ACL |
The user must have <write-acl>
privileges on the resource.
This procedure sets the FTP port to a new value.
DBMS_XDB.SETFTPPORT( new_port IN NUMBER);
Table 121-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.
DBMS_XDB.SETHTTPPORT( new_port IN NUMBER);
Table 121-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
.
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);
Table 121-26 UPDATERESOURCEMETADATA Procedure Parameters
Parameter | Description |
---|---|
|
Absolute path of the resource |
|
|
|
|
|
Namespace identifying old metadata |
|
Local name identifying old metadata |
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.
DBMS_XDB.UNLOCKRESOURCE( path IN VARCHAR2, deltoken IN VARCHAR2) RETURN BOOLEAN;
Table 121-27 UNLOCKRESOURCE Function Parameters
Parameter | Description |
---|---|
|
Path name to the resource |
|
Lock token to be removed |
TRUE
if operation successful.
The user must have UPDATE
privileges on the resource.