183 DBMS_XDB_CONFIG

The DBMS_XDB_CONFIG package provides an interface for configuring Oracle XML DB and its repository.

This chapter contains the following topics:

Using DBMS_XDB_CONFIG

Overview

PL/SQL package DBMS_XDB_CONFIG is the Oracle XML DB resource application program interface (API) for PL/SQL for DBAs to configure their system. This API provides functions and procedures to access and manage Oracle XML DB Repository resources using PL/SQL. It includes methods for managing resource security and Oracle XML DB configuration.

Oracle XML DB Repository is modeled on XML, and provides a database file system for any data. The repository maps path names (or URLs) onto database objects of XMLType and provides management facilities for these objects.

PL/SQL package DBMS_XDB_CONFIG is an API that you can use to manage all of the following:

  • Oracle XML DB resources

  • Oracle XML DB security based on access control lists (ACLs). An ACL is a list of access control entries (ACEs) that determines which principals (users and roles) have access to which resources.

  • Oracle XML DB configuration

Security Model

Owned by XDB, the DBMS_XDB_CONFIG package must be created by SYS or XDB. The EXECUTE privilege is granted to PUBLIC. Subprograms in this package are executed using the privileges of the current user.

Constants

The DBMS_XDB_CONFIG package uses the constants shown in Table 183-1, "DBMS_XDB_CONFIG Constants".

Table 183-1 DBMS_XDB_CONFIG Constants

Constant Type Value Description

XDB_ENDPOINT_HTTP

NUMBER

1

Defining listener for first HTTP port

XDB_ENDPOINT_HTTP2

NUMBER

2

Defining listener for second HTTP port

XDB_PROTOCOL_TCP

NUMBER

1

Defining listener for HTTP protocol

XDB_PROTOCOL_TCPS

NUMBER

2

Defining listener for HTTPS protocol


Summary of DBMS_XDB_CONFIG Subprograms

Table 183-2 DBMS_XDB_CONFIG Package Subprograms

Subprogram Description

ADDHTTPEXPIREMAPPING Procedure

Adds to XDB$CONFIG a mapping of the URL pattern to an expiration date. This will control the Expire headers for URLs matching the pattern.

ADDMIMEMAPPING Procedure

Adds a mime mapping to XDB configuration

ADDSCHEMALOCMAPPING Procedure

Adds a schema location mapping to the XDB configuration

ADDSERVLET Procedure

Adds a servlet to XDB configuration

ADDSERVLETMAPPING Procedure

Adds a servlet mapping to XDB configuration

ADDSERVLETSECROLE Procedure

Adds a security role REF to a specified servlet in XDB configuration

ADDXMLEXTENSION Procedure

Adds adds the following XML extension to the XDB configuration under <xml-extensions>: <extension>extension</extension>

CFG_GET Function

Retrieves the session's configuration information as an XMLType instance

CFG_REFRESH Procedure

Refreshes the session's configuration information to the latest configuration

CFG_UPDATE Procedure

Updates the configuration information and commits the change.

DELETEHTTPEXPIREMAPPING Procedure

Deletes from XDB$CONFIG all mappings of the URL pattern to an expiration date

DELETEMIMEMAPPING Procedure

Deletes the mime mapping for a specified extension from the XDB configuration

DELETESCHEMALOCMAPPING Procedure

Deletes the schema location mapping for a specified schema URL from the XDB configuration

DELETESERVLET Procedure

Deletes a servlet from the XDB configuration

DELETESERVLETMAPPING Procedure

Deletes the servlet mapping for a specified servlet name from the XDB configuration

DELETESERVLETSECROLE Procedure

Deletes the specified role from a servlet in the XDB configuration

DELETEXMLEXTENSION Procedure

Deletes the specified XML extension from the XDB configuration

ENABLEDIGESTAUTHENTICATION Procedure

Enables enables digest authentication

GETFTPPORT Function

Gets the value of the current FTP port

GETHTTPPORT Function

Gets the value of the current HTTP port

GETHTTPCONFIGREALM Function

Gets the realm name

GETHTTPSPORT Function

Gets the value of the current HTTPS port

GETLISTENERENDPOINT Procedure

Gets the parameters of a listener end point corresponding to the XML DB HTTP server

SETFTPPORT Procedure

Sets the FTP port to a new value

SETHTTPPORT Procedure

Sets the HTTP port to a new value

SETHTTPCONFIGREALM Procedure

Sets the realm to a new value

SETHTTPSPORT Procedure

Sets the HTTPS port to a new value

SETLISTENERENDPOINT Procedure

Sets the parameters of a listener end point corresponding to the XML DB HTTP server

SETLISTENERLOCALACCESS Procedure

Restricts all listener end points of the XML DB HTTP server to listen either only on the localhost interface (when l_access is set to TRUE) or to listen on both localhost and non-localhost interfaces (when l_access is set to FALSE)

USEDPORT Procedure

Obtains the port numbers used by other pluggable databases in the same consolidation database


ADDHTTPEXPIREMAPPING Procedure

This procedure adds to XDB$CONFIG a mapping of the URL pattern to an expiration date. This will control the Expire headers for URLs matching the pattern.

Syntax

DBMS_XDB_REPOS.ADDHTTPEXPIREMAPPING (
     pattern    IN    VARCHAR2,
     expire     IN    VARCHAR2);

Parameters

Table 183-3 ADDHTTPEXPIREMAPPING Procedure Parameters

Parameter Description

pattern

URL pattern (only * accepted as wildcards)

expire

Expiration directive, follows the ExpireDefault in Apache's mod_expires:

base [plus] (num type)*
-- base: now | modification
-- type: year|years|month|months|week|weeks|day|days|
minute|minutess|second|seconds

Examples

DBMS_XDB_REPOS.ADDHTTPEXPIREMAPPING ('/public/test1/*', 'now plus 4 weeks');
DBMS_XDB_REPOS.ADDHTTPEXPIREMAPPING (
             '/public/test2/*', 'modification plus 1 day 30 seconds');

ADDMIMEMAPPING Procedure

This procedure adds the following mime mapping to XDB configuration:

<mime-mapping>
<extension>extension</extension>
<mime-type>mimetype</mime-type>
</mime-mapping>

Syntax

DBMS_XDB_CONFIG.ADDMIMEMAPPING(
     extension    IN   VARCHAR2,
     mimetype     IN   VARCHAR2);

Parameters

Table 183-4 ADDMIMEMAPPING Procedure Parameters

Parameter Description

extension

Extension for which a mime type is being added

mimetype

Mime type


ADDSCHEMALOCMAPPING Procedure

This procedure adds the following schema location mapping to the XDB configuration:

<schemaLocation-mapping>
     <namespace>namespace</namespace>
     <element>element</element>
      <schemaURL>schemaURL</schemaURL>
</schemaLocation-mapping>

Syntax

DBMS_XDB_CONFIG.ADDSCHEMALOCMAPPING(
     namespace    IN   VARCHAR2,
     element      IN   VARCHAR2,
     schemaURL    IN   VARCHAR2);

Parameters

Table 183-5 ADDSCHEMALOCMAPPING Procedure Parameters

Parameter Description

namespace

Namespace

element

Element

schemaURL

Schema URL


ADDSERVLET Procedure

This procedure adds the following servlet to XDB configuration:

<servlet>
     <servlet-name>name</servlet-name>     <servlet-language>language</servlet-language>
     <display-name>dispname</display-name>
     <description>descript</description>
     <servlet-class>class</servlet-class>
     <servlet-schema>schema</servlet-schema>
</servlet>

Syntax

DBMS_XDB_CONFIG.ADDSERVLET(
     name       IN   VARCHAR2,
    language    IN   VARCHAR2,
    dispname    IN   VARCHAR2,
    icon        IN   VARCHAR2 := NULL,
    descript    IN   VARCHAR2 := NULL,
    class       IN   VARCHAR2 := NULL,
    jspfile     IN   VARCHAR2 := NULL,
    plsql       IN   VARCHAR2 := NULL);

Parameters

Table 183-6 ADDSERVLET Procedure Parameters

Parameter Description

name

Servlet name

language

Must be one of "C", "Java", "PL/SQL"

dispname

Display name

icon

Icon

descript

Description

class

The class / jspfile / plsql function corresponding to this servlet. The first non-NULL argument amongst these three is chosen, and the others are treated as NULL.

jspfile

The class / jspfile / plsql function corresponding to this servlet. The first non-NULL argument amongst these three is chosen, and the others are treated as NULL.

plsql

The class / jspfile / plsql function corresponding to this servlet. The first non-NULL argument amongst these three is chosen, and the others are treated as NULL.

schema

Schema


ADDSERVLETMAPPING Procedure

This procedure adds the following servlet mapping to XDB configuration:

<servlet-mapping>     <servlet-pattern>pattern</servlet-pattern>     <servlet-name>name</servlet-name></servlet-mapping>

Syntax

DBMS_XDB_CONFIG.ADDSERVLETMAPPING(
     pattern   IN   VARCHAR2,     name      IN   VARCHAR2);

Parameters

Table 183-7 ADDSERVLETMAPPING Procedure Parameters

Parameter Description

pattern

Sservlet pattern

name

Servlet name


ADDSERVLETSECROLE Procedure

This procedure adds the following security role REF to a specified servlet in XDB configuration:

<security-role-ref>
     <role-name>rolename</role-name>
     <role-link>rolelink</role-link>
     <description>descript</description>
</security-role-ref>

Syntax

DBMS_XDB_CONFIG.ADDSERVLETSECROLE(
     servname    IN   VARCHAR2,     rolename    IN   VARCHAR2,     rolelink    IN   VARCHAR2,     descript    IN   VARCHAR2 := NULL);

Parameters

Table 183-8 ADDSERVLETSECROLE Procedure Parameters

Parameter Description

servname

Sservlet name

rolename

Role name

rolelink

Role link

descript

Description


ADDXMLEXTENSION Procedure

This procedure adds the following XML extension to the XDB configuration under <xml-extensions>:

<extension>extension</extension>

Syntax

DBMS_XDB_CONFIG.ADDXMLEXTENSION(
     extension    IN   VARCHAR2);

Parameters

Table 183-9 ADDXMLEXTENSION Procedure Parameters

Parameter Description

extension

XML extension to be added


CFG_GET Function

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

Syntax

DBMS_XDB_CONFIG.CFG_GET 
 RETURN SYS.XMLType;

CFG_REFRESH Procedure

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

Syntax

DBMS_XDB_CONFIG.CFG_REFRESH;

CFG_UPDATE Procedure

This procedure updates the configuration information and commits the change.

Syntax

DBMS_XDB_CONFIG.CFG_UPDATE(
   xdbconfig   IN  SYS.XMLTYPE);

Parameters

Table 183-10 CFG_UPDATE Procedure Parameters

Parameter Description

xdbconfig

The new configuration data


DELETEHTTPEXPIREMAPPING Procedure

This procedure deletes from XDB$CONFIG all mappings of the URL pattern to an expiration date.

Syntax

DBMS_XDB_REPOS.DELETEHTTPEXPIREMAPPING(
     pattern  IN   VARCHAR2);

Parameters

Table 183-11 DELETEHTTPEXPIREMAPPING Procedure Parameters

Parameter Description

pattern

URL pattern (only * accepted as wildcards)


DELETEMIMEMAPPING Procedure

This procedure deletes the mime mapping for a specified extension from the XDB configuration.

Syntax

DBMS_XDB_CONFIG.DELETEMIMEMAPPING(
     extension    IN   VARCHAR2);

Parameters

Table 183-12 DELETEMIMEMAPPING Procedure Parameters

Parameter Description

extension

Extension for which a mime type is to be deleted


DELETESCHEMALOCMAPPING Procedure

This procedure deletes the schema location mapping for a specified schema URL from the XDB configuration.

Syntax

DBMS_XDB_CONFIG.DELETESCHEMALOCMAPPING(
     schemaURL    IN   VARCHAR2);

Parameters

Table 183-13 DELETESCHEMALOCMAPPING Procedure Parameters

Parameter Description

schemaURL

Schema URL


DELETESERVLET Procedure

This procedure deletes a servlet from the XDB configuration.

Syntax

DBMS_XDB_CONFIG.DELETESERVLET(
     name        IN   VARCHAR2);

Parameters

Table 183-14 DELETESERVLET Procedure Parameters

Parameter Description

name

Servlet name


DELETESERVLETMAPPING Procedure

This procedure deletes the servlet mapping for a specified servlet name from the XDB configuration.

Syntax

DBMS_XDB_CONFIG.DELETESERVLETMAPPING(
     name      IN   VARCHAR2);

Parameters

Table 183-15 DELETESERVLETMAPPING Procedure Parameters

Parameter Description

name

Servlet name


DELETESERVLETSECROLE Procedure

This procedure deletes the specified role from a servlet in the XDB configuration.

Syntax

DBMS_XDB_CONFIG.DELETESERVLETSECROLE(
     servname    IN   VARCHAR2,     rolename    IN   VARCHAR2);

Parameters

Table 183-16 DELETESERVLETSECROLE Procedure Parameters

Parameter Description

servname

Servlet name

rolename

Name of the role to be deleted


DELETEXMLEXTENSION Procedure

This procedure deletes the specified XML extension from the XDB configuration.

Syntax

DBMS_XDB_CONFIG.DELETEXMLEXTENSION(
     extension    IN   VARCHAR2);

Parameters

Table 183-17 DELETEXMLEXTENSION Procedure Parameters

Parameter Description

extension

XML extension to be deleted


ENABLEDIGESTAUTHENTICATION Procedure

This procedure enables digest authentication. It will list digest as the first authentication mechanism to be used by the XML DB HTTP server.

Syntax

DBMS_XDB_CONFIG.ENABLEDIGESTAUTHENTICATION;

GETFTPPORT Function

This procedure gets the value of the current FTP port.

Syntax

DBMS_XDB_CONFIG.GETFTPPORT
 RETURN NUMBER;

GETHTTPPORT Function

This function gets the value of the current HTTP port.

Syntax

DBMS_XDB_CONFIG.GETHTTPPORT
 RETURN NUMBER;

GETHTTPCONFIGREALM Function

This function gets the realm name. Definition of a realm is referenced in IETF's RFC2617.

Syntax

DBMS_XDB_CONFIG.GETHTTPCONFIGREALM
 RETURN VARCHAR2;

GETHTTPSPORT Function

This procedure gets the value of the current HTTPS port.

Syntax

DBMS_XDB_CONFIG.GETHTTPPORT
 RETURN NUMBER;

Usage Notes

Returns NULL if no port has been configured

GETLISTENERENDPOINT Procedure

This procedure retrieves the parameters of a listener end point corresponding to the XML DB HTTP server. The parameters of both HTTP and HTTP2 end points can be retrieved by invoking this procedure.

Syntax

DBMS_XDB_CONFIG.GETLISTENERENDPOINT (
   endpoint  IN   NUMBER, 
   host      OUT  VARCHAR2,    port      OUT  NUMBER, 
   protocol  OUT  NUMBER);

Parameters

Table 183-18 GETLISTENERENDPOINT Procedure Parameters

Parameter Description

endpoint

End point to be retrieved. Its value can be XDB_ENDPOINT_HTTP or XDB_ENDPOINT_HTTP2.

host

Interface on which the listener end point listens

port

Port on which the listener end point listens

protocol

Transport protocol accepted by the listener end point


SETFTPPORT Procedure

This procedure sets the FTP port to a new value.

Syntax

DBMS_XDB_CONFIG.SETFTPPORT(
   new_port  IN  NUMBER);

Parameters

Table 183-19 SETFTPPORT Procedure Parameters

Parameter Description

new_port

Value to which the FTP port is set


SETHTTPPORT Procedure

This procedure sets the HTTP port to a new value.

Syntax

DBMS_XDB_CONFIG.SETHTTPPORT(
   new_port  IN  NUMBER);

Parameters

Table 183-20 SETHTTPPORT Procedure Parameters

Parameter Description

new_port

Value to which the HTTP port is set


SETHTTPCONFIGREALM Procedure

This procedure modifies the realm value.

Syntax

DBMS_XDB_CONFIG.SETHTTPCONFIGREALM(
   realm IN VARCHAR2);

Parameters

Table 183-21 SETHTTPPORT Procedure Parameters

Parameter Description

realm

Realm as defined in IETF's RFC2617


SETHTTPSPORT Procedure

This procedure sets the HTTP port to a new value.

Syntax

DBMS_XDB_CONFIG.SETHTTPSPORT(
   new_port  IN  NUMBER);

Parameters

Table 183-22 SETHTTPSPORT Procedure Parameters

Parameter Description

new_port

Value to which the HTTPS port is set


SETLISTENERENDPOINT Procedure

This procedure sets the parameters of a listener end point corresponding to the XML DB HTTP server. Both HTTP and HTTP2 end points can be set by invoking this procedure.

Syntax

DBMS_XDB_CONFIG.SETLISTENERENDPOINT (
   endpoint  IN  NUMBER, 
   host      IN  VARCHAR2,    port      IN  NUMBER, 
   protocol  IN  NUMBER);

Parameters

Table 183-23 SETLISTENERENDPOINT Procedure Parameters

Parameter Description

endpoint

End point to be set. Its value can be XDB_ENDPOINT_HTTP or XDB_ENDPOINT_HTTP2.

host

Interface on which the listener end point is to listen. Its value can be 'LOCALHOST,' NULL, or a hostname. If its value is 'LOCALHOST' the listener end point is permitted to only listen on the localhost interface. If its value is NULL or hostname, the listener end point is permitted to listen on both localhost and non-localhost interfaces.

port

Port on which the listener end point is to listen

protocol

Transport protocol that the listener end point is to accept. Its value can be XDB_PROTOCOL_TCP or XDB_PROTOCOL_TCPS


SETLISTENERLOCALACCESS Procedure

This procedure restricts all listener end points of the XML DB HTTP server to listen either only on the localhost interface (when l_access is set to TRUE) or to listen on both localhost and non-localhost interfaces (when l_access is set to FALSE).

Syntax

DBMS_XDB_CONFIG.SETLISTENERLOCALACCESS (
   l_access   BOOLEAN);

Parameters

Table 183-24 SETLISTENERLOCALACCESS Procedure Parameters

Parameter Description

l_access.

TRUE or FALSE.


USEDPORT Procedure

This procedure obtains the port numbers used by other pluggable databases in the same consolidation database.

Syntax

DBMS_XDB_CONFIG.USEDPORT;