|Oracle® XML DB Developer's Guide
10g Release 1 (10.1)
Part Number B10790-01
This chapter describes how to use Oracle Enterprise Manager for managing Oracle XML DB, including configuring, creating, and managing repository resources. The repository source include database objects such as XML schemas and
This chapter contains these topics:
This chapter describes how to use Oracle Enterprise Manager (Enterprise Manager) to administer and manage Oracle XML DB.
Oracle Enterprise Manager is supplied with Oracle Database, both Enterprise and Standard Editions. To run the Enterprise Manager version that supports Oracle XML DB functionality, use Oracle9i release 2 (9.2) or higher.
Oracle XML DB is installed by default when the Database Configuration Assistant (DBCA) is used to create a new database. The following actions take place during Oracle XML DB installation:
Oracle registers the configuration XML schema:
Oracle inserts a default configuration document. It creates resource
/xdbconfig.xml conforming to the configuration XML schema. This resource contains default values for all Oracle XML DB parameters.
Oracle XML DB is typically used for its faster retrieval and search capabilities, access control, and versioning of XML documents. XML instance documents saved in the database can conform to an XML Schema. XML Schema is a schema definition language, also written in XML, that can be used to describe the structure and various other semantics of a conforming XML instance document.
Oracle XML DB provides a mechanism to register XML Schemas with the database.
Assuming that your XML schema document(s) already exists, registering the XML schema is your first task. Before you register the XML schema, you must know the following:
Whether the data for the XML instance documents already exists in relational tables. This would be the case for legacy applications. If so, then Object Views for XML must be created.
What is the storage model? Are you using LOB storage, object-relational storage, or both? The answer to this question depends on which parts of the document are queried the most often, and hence would need faster retrieval.
Is the XML Schema document annotated with comments to generate object datatypes and object tables? If not, then these objects will have to be created and mapped manually to the database schema.
For most cases, it is assumed that you have XML schema annotated with information to automatically generate object types and object tables. Hence Oracle Database, as part of XML schema registration, automatically generates these objects.
Oracle XML DB is now ready for you to insert conforming XML documents.
With Oracle Enterprise Manager you can perform the following main Oracle XML DB administrative tasks:
Figure 26-1 Managing Oracle XML DB with Enterprise Manager: Main Tasks
Oracle XML DB is managed through the configuration file,
xdbconfig.xml. Through Enterprise Manager, you can view or configure parameters for this file. To access the Oracle XML DB configuration options, from the Enterprise Manager right hand window, select Configure XML Database. See "Configuring Oracle XML DB with Enterprise Manager" .
To access the XML resource management options, select the XML Database object in the Navigator and click Create a Resource in the detail view. See "Creating and Managing Oracle XML DB Resources with Enterprise Manager" .
To access the XML schema management options, select the XML Database object in the Navigator and click Create Table and Views Based on XML Schema in the detail view. See "Managing XML Schema and Related Database Objects".
You can register, delete, view, generate (that is, reverse engineer) an XML schema and see its dependencies. You can also view an XML schema contents and perform actions on its constituent elements.
Views. Create or alter an object view of
XMLType, and look at the corresponding indexes.
Tables. Create XML schema-based and non-XML schema-based
XMLType tables and columns, and look at the corresponding indexes. You can also specify LOB storage attributes on these columns.
You can create
XMLType tables in CLOB or object-relational form, and specify constraints and LOB storage attributes on hidden
Indexes. Create index on the hidden columns of
DML operations. You can also perform other DML operations such as inserting and updating rows using XML instance documents.
XML Schema Elements. You can view elements in their XML form and the XML instance data stored in the database corresponding to that element. You can also view the XML schema-dependent objects, such as tables, views, indexes, object types, array types, and table types.
Figure 26-2 Enterprise Manager Console: XML Database Management Window
See Figure 26-2. From the Enterprise Manager console, you can quickly browse and manage Oracle XML DB objects.
From the XML Database Management detail view, you can access the XML DB management functionality. From there you can select which task you must perform.
Oracle XML DB configuration is an integral part of Oracle XML DB. It is used by protocols such as HTTP/WebDAV or FTP, and any other components of Oracle XML DB that can be customized, such as in the ACL-based security. ACL is a list of access control entries that determines which principals have access to a given resource or resources.
Oracle XML DB configuration is stored as an XML schema based XML resource,
xdbconfig.xml in the Oracle XML DB repository. It conforms to the Oracle XML DB configuration XML schema stored at:
This configuration XML schema is registered when Oracle XML DB is installed. The configuration property sheet has two tabs:
For System Configurations. General parameters and FTP and HTTP protocol specific parameters can be displayed on the System Configurations tab.
For User Configurations. Custom parameters can be displayed on the User Configurations tab.
The XML Database Parameters page displays a list of configuration parameters for the current XML database. You can also access this page from the XML Database Management main window Configure XML Database.
When you click the Configuration node for the XML database in the Enterprise Manager Navigator, the XML DB Parameters page appears in the main panel to the right. The XML DB Parameters window lists the following information:
Parameter Name -- Lists the name of the parameter.
Value -- Displays the current value of the parameter. This is an editable field.
Default -- Indicates whether the value is a default value. A check mark indicates a default value.
Dynamic -- Indicates whether or not the value is dynamic. A check mark indicates dynamic.
Category -- Displays the category of the parameter. Category can be HTTP, FTP, or Generic.
You can change the value of a parameter by clicking the Value field for the parameter and making the change. Click Apply to apply any changes you make. You can access a description of a parameter by clicking on the parameter in the list and then clicking Description at the bottom of the page. A text Description text box appears that describes in greater detail the parameter you selected. You can close the Description box by clicking Description again.
Figure 26-3 Enterprise Manager Console: Configuring Oracle XML DB
Because Oracle XML DB provides support for standard Internet protocols (FTP and WebDAV/HTTP) as a means of accessing the repository, Enterprise Manager provides you with related information:
Oracle XML DB FTP Port: displays the port number the FTP protocol will be listening to. FTP by default listens on a non-standard, non-protected port.
Oracle XML DB HTTP Port: displays the port number the HTTP protocol will be listening to. HTTP will be managed as a Shared Server presentation, and can be configured through the TNS listener to listen on arbitrary ports. HTTP listens on a non-standard, non-protected port.
Figure 26-4 Enterprise Manager Console: Edit XML Database Parameters Dialog
With Enterprise Manager you can view and edit partial Oracle XML DB configuration parameters, in the following categories:
ftp-port: Enterprise Manager manages FTP as a Shared Server presentation. It can be configured using TNS listeners to listen on arbitrary ports.
ftp-logfile-path: The file path of the FTP Server log file.
ftp-log-level: The level of logging for FTP error and warning conditions.
http-port: Enterprise Manager manages HTTP as a Shared Server presentation. It can be configured using TNS listeners to listen on arbitrary ports.
session-timeout: The maximum time the server will wait for client responses before it breaks a connection.
server-name: Hostname to use by default in HTTP redirects and servlet application program interface (API).
http-logfile-path: The file path of the HTTP server log file.
http-log-level: The level of logging for HTTP error and warning conditions.
welcome-file-list: The list of welcome files used by the server.
The Resources folder in the Enterprise Manager navigation tree is under the XML Database folder. It contains all the resources in the database regardless of the owner. Figure 26-5 shows a typical Resources tree.
When the Resources folder is selected in the Navigator, the right-hand side of the screen displays all the top level Oracle XML DB resources under root, their names, and their creation and modification dates. See Figure 26-6.
Figure 26-5 Enterprise Manager: Oracle XML DB Resources Tree Showing Resources Folder Selected
Figure 26-6 Enterprise Manager: Top Level Resources Under Root
Once you select a resource sub-folder under the main Resources folder in the Navigator, you can see the resources General Page in the detail view, as shown in Figure 26-7.
Figure 26-7 Enterprise Manager: Individual Oracle XML DB Resources - General Page
The Oracle XML DB Resources General page (also called the XML Resources Page) displays overview information about the resource container or resource file. When you select one of the Oracle XML DB resource containers or files in the Navigator, Enterprise Manager displays the Oracle XML DB Resources General page. This is a read-only page. It displays the following information:
Name - name of the resource file or container
Creator - the user or role that created the resource
Last Modifier - the name of the user who last modified the resource
Created - the date and time the resource was created
Modified - the date and time that the resource was last changed
Language - the resource language, such as US English
Type - File or Container
Oracle XML DB Resources Security page changes the ACL associated with the XML DB resource container or file. Use the ACL files to restrict access to all XML DB resources. When you change the ACL file for the resource, you change the access privileges for the resource file. See Figure 26-8.
To specify a new ACL file:
Click Specify a new ACL File and then choose a new ACL file from the drop down list in the File Name field.
Click Apply to apply the change.
Click Revert to abandon any changes you have made to the File Name field.
Figure 26-8 Enterprise Manager: Individual Oracle XML DB Resource - Security Page
Figure 26-9 shows the context-sensitive menu displayed when you select and right-click an individual Oracle XML DB resource object in the Navigator.
Figure 26-9 Enterprise Manager: When You Right-Click an Individual Resource...
You can perform the following Oracle XML DB tasks from the Enterprise Manager Content Menu:
Figure 26-10 shows how you can use the Create XML DB Resource dialog box to create an XML DB resource container or file. From the XML DB Resource dialog you can name the resource and then either create a new resource container or create a new resource file, designating the location of the file as either a local file, a file at a specified URL, or specifying the contents of the file.
Access the Create XML DB Resource dialog box by right clicking on the Resources folder or any individual resource node and selecting Create from the context menu. When you name the resource in the Name field, you can change the location by clicking on the Change Location button to the right of the Location field.
Specify whether the resource you are creating is a container or a file. If you create a file by choosing Create a new resource file, you can select from one of three file type location options:
Local File -- Select Use a file in the local file system to browse for a file location on your network.
File at URL -- Select Use a file at the URL to enter the location of the file on the Internet or intranet.
File Contents -- Select Specify the resource contents here to enter the contents of a file in the edit box located at the bottom of the Create XML DB Resource dialog box.
Figure 26-10 Enterprise Manager: Create Oracle XML DB Resource Dialog Box
Figure 26-11 shows the Grant Privileges On dialog box which assigns privileges on an Oracle XML DB resource to users or roles. You can grant multiple privileges to multiple users or roles. Grant Privileges On dialog box lists the available Oracle XML DB resource privileges in the Grant section at the top of the panel.
To grant privileges, select the privileges you want to grant by clicking on a privilege. You can select multiple privileges by holding down the Ctrl key while selecting more than one privilege. You can select consecutive privileges by clicking the first privilege in a sequence and holding down the Shift key while clicking the last privilege in the sequence.
Select the user or group in the To: box at the bottom of the dialog page. Use the same procedure to select multiple users or roles to which to grant privileges.
Figure 26-11 Enterprise Manager: Granting Privileges to Oracle XML DB Resources
Figure 26-12 is an example of a Show Contents dialog box. It displays the contents of the selected resource file.
Figure 26-12 Enterprise Manager: Show Contents Menus of Individual Oracle XML DB Resource
Figure 26-11 shows the Show Grantee of XML DB Resource dialog box. It displays a list of all granted privileges on a specified XML DB resource for the connected Enterprise Manager user. Show Grantee dialog box lists the connected Enterprise Manager user, privilege, and granted status of the privilege in tabular format.
Figure 26-13 Enterprise Manager: Show Grantee of Oracle XML DB Resources
From Enterprise Manager you can restrict access to all XML DB resources by means of ACLs. You can grant XML DB resource privileges to database user and database role separately using the existing Security/Users/user and Security/Roles/role interface, respectively.
You can access the Enterprise Manager security options in two main ways:
To view or modify user (or role) security: In the Navigator, under the Oracle XML DB database in question Security >Users >user (or > Security > Roles > role). In the detail view, select the XML tag. See Figure 26-14. This user security option is described in more detail in "Granting and Revoking User Privileges with User > XML Tab ".
To view or modify a resource security: Select the individual resource node under the Resources folder in the left navigation panel. Select the Security tag in the detail view. See Figure 26-15.
This section describes how to grant and revoke privileges for a user. The same procedure applies when granting and revoking privileges for a role. To grant privileges to a user follow these steps:
Select a particular user from the Enterprise Manager Navigator. The detail view displays an additional tab, XML, in the existing property sheet.
To view and select resources on which you want to grant privileges to users or roles, select the XML tab. Once you select a resource, all available privileges for that resource are displayed in the Available Privileges list to the right of the Resources list.
Select the privileges required from the Available Privileges list and move them down to the Granted list that appears at the bottom of the window by clicking on the down arrow.
Conversely, you can revoke privileges by selecting them in the Granted list and clicking on the up arrow.
After setting the appropriate privileges, click the Apply button to save your changes. Before you save your changes, you can click the Revert button to abandon your changes.
Figure 26-14 Adding or Revoking Privileges with Users > user> XML
The Resources list is a tree listing of resources located in Oracle XML DB repository. You can navigate through the folder hierarchy to locate the resource on which you want to set privileges for the user or role you selected in Navigator. When you select a resource in the tree listing, its privileges appear in the Available Privileges list to the right.
The Available Privileges list displays all privileges available for a resource. Click a privilege and then press the down arrow to add the privilege to the Granted list. You can select consecutive privileges by clicking on the first privilege and then holding the Shift key down to select the last in the list. Also, you can select non-consecutive privileges by holding the Ctrl-key down while making selections.
Privileges can be either of the following:
aggregate privileges. They contain other privileges.
atomic privileges. They cannot be subdivided.
Privilege can be aggregate (contain other privileges) or atomic (cannot be subdivided). The following system privileges are supported:
link (applies only to containers)
unlink (applies only to containers)
dav:read (read-properties, read-contents, resolve)
dav:write (update, link, unlink, unlink-from)
dav:write-acl (write-acl-ref, update-acl)
dav:all (dav:read, dav:write, dav:read-acl, dav:write-acl, dav:look, dav:unlock)
Figure 26-15 Granting Privileges on a Resource
See Also:Chapter 23, " Oracle XML DB Resource Security" for a list of supported system privileges.
From the XML Database Management detail view, when you select Create tables and views based on XML Schema the XML Schema Based Objects page appears as shown in Figure 26–16 and Figure 26–17. With this page you can:
Register an XML schema
Create a structured storage based on an XML schema
Create a table with
Create a view based on XML schema
Create a function-based index based on XPath expressions
Under the XML Schema folder, the tree lists all the XML schema owners. The example here is owner XDB. See Figure 26-16:
Schema Owners. Under the individual XML schema owners, the tree lists the XML schemas owned by the owner(s). Here you can see:
http://xmlns.oracle.com/xdb/XDBResource.xsd http://xmlns.oracle.com/xdb/XDBSchema.xsd http://xmlns.oracle.com/xdb/XDBStandard.xsd
Top level elements. Under each XML schema, the tree lists the top level elements. These elements are used to create the
XMLType tables, tables with
XMLType columns, and views. For example, Figure 26-16 shows top level elements servlet and LINK. The number and names of these elements are dictated by the relevant XML schema definition, which in this case is:
Dependent objects. Under each element, the tree lists the created dependent objects, Tables, Views, and User Types respectively. In this example, you can see that top level element servlet has dependent
XMLType Tables, Views, and User types.
Dependent object owners. Under each dependent object type, the tree lists the owner.
Tables. For example, under Tables,
XDB is an owner, and
XDB owns a table called SERVLET.
Table characteristics. Under each table name the tree lists any created Indexes, Materialized View Logs (Snapshots), Partitions, and Triggers.
Views. Not shown here but under Views you would see any view owners and the name of views owned by these owners:
View characteristics. These are not listed here.
User Types. The tree lists any user types associated with the top level element servlet. These are listed according to the type:
Object types. Under Object types the tree lists the object type owners.
Array types. Under Array types the tree lists the array type owners.
Table types. Under table types the tree lists the table type owners.
Figure 26-16 Enterprise Manager Console: Navigating XML Schema
Figure 26-17 Enterprise Manager: Creating XML Schema-Based Objects
Registering an XML schema is one of the central, and often first, tasks before you use Oracle XML DB. XML schema are registered using
Figure 26-18 shows you how to register an XML schema.
From the GENERAL page, enter the XML schema URL and select the Owner of the XML schema from the drop-down list.
Global, that is XML schema is visible to public
Local, that is XML schema is visible only to the user creating it
You can obtain the XML schema in one of four ways:
By specifying the location of the file in the local file system
By specifying the XML Database (repository) resource where the XML schema is located
By specifying the URL location
By cutting and pasting the text form another screen
From the Options page you can select the following options:
Generate the object types based on this XML schema
Generate tables based on this XML schema
Generate Java beans based on this XML schema
Register this XML schema regardless of any errors
See Figure 26-19. Press Create from either the General Tab or Options Tab to register this XML schema.
Figure 26-18 Enterprise Manager: Registering an XML Schema - General Page
Figure 26-19 Enterprise Manager: Creating XML Schema - Options Page
This section describes how to use Oracle Enterprise Manager to create
XMLType tables, views, and indexes.
You have two main options when creating tables:
To create an
XMLType view, see "Creating a View Based on XML Schema".
To create function-based indexes see "Creating a Function-Based Index Based on XPath Expressions".
From the Create Table property sheet, enter the desired name of the table you are creating on the General page. Select the table owner from the drop-down list Schema. Leave Tablespace at the default setting. Select
Under the lower Schema option, select the XML schema owner, from the drop-down list.
Under XML Schema, select the actual XML schema from the drop-down list.
Under Element, select the required element to from the
XMLType table, from the drop-down list.
Specify the storage:
Store as defined by the XML schema. When you select this option, hidden columns are created based on the XML schema definition annotations. Any SELECTs or UPDATEs on these columns are optimized.
Store as CLOB. When you select CLOB the LOB Storage tab dialog appears. Here you can customize the CLOB storage. See Figure 26-21.
Figure 26-20 Enterprise Manager: Creating XMLType Tables-General Page
Figure 26-21 Enterprise Manager: Creating XMLType Tables - Specifying LOB Storage
See Figure 26-22 shows the Create Table General page. To create a table with
XMLType columns follow these steps:
From the Create Table property sheet, enter the desired name of the table you are creating on the General page.
Select the table owner from the drop-down list Schema. Leave Tablespace at the default setting.
Select Define Columns.
Enter the Name. Enter the Datatype; select
XMLType from the drop-down list. The
XMLType Options dialog window appears. See Figure 26-23.
Figure 26-22 Enterprise Manager: Creating Tables With XMLType Column - General Page
From this screen you can specify for a particular
XMLType column, whether it is XML schema-based or non-schema-based.
If it is XML schema-based:
Under the "Schema" option, select the XML schema owner, from the drop-down list.
Under "XML Schema", select the actual XML schema from the drop-down list.
Under "Element", select the required element to form the
XMLType column, from the drop-down list.
Specify the storage:
Store as defined by the XML schema.
Store as CLOB. When you select CLOB the LOB Storage tab dialog appears. Here you can customize the CLOB storage.
If it is non-schema-based then you are not required to change the default settings.
Figure 26-23 Enterprise Manager: Creating Tables With XMLType Column - XMLType Options
Figure 26-24 shows the Create View General page. To create a view based on an XML schema, follow these steps:
Enter the desired view name. Under Schema, select the view owner from the drop-down list.
Enter the SQL statement text in the Query Text window to create the view. Select the Advanced tab. See Figure 26-25.
From here you can select Force mode
Select the As Object option. The view can be set to Read Only or With Check Option.
Because this is an
XMLType view, select the As Object option. Select XMLType not Object Type.
Under the Schema option, select the XML schema owner, from the drop-down list.
Under XML Schema, select the actual XML schema from the drop-down list.
Under Element, select the required element to form the
XMLType column, from the drop-down list.
Specify the Object Identifier (OID):
If your SQL statement to create the view is based on an object type table, then select the Use default if your query is based on...
Otherwise, select Specify based on XPath expression on the structure of the element. Enter your XPath expression. See Chapter 16, " XMLType Views".
Figure 26-24 Enterprise Manager: Creating an XMLType View - General Page
Figure 26-25 Enterprise Manager: Creating XMLType Views - Advanced Page
See Figure 26-26 shows the Create Index General page. To create a function-based index based on an XPath expression follow these steps:
Provide the owner and name of the index. Under Name enter the name of the required index. Under Schema select the owner of the index from the drop-down list.
Under Index On, select Table.
Under the lower Schema select the table owner from the drop-down list.
Under Table, select either the
XMLType table or table with
XMLType column from the drop-down list.
You can also enter an alias for a column expression. You can specify this alias inside your function-based index statement.
For tables with XMLTypecolumns, first click the lower left-hand + icon. This creates a new row for you to enter your extract XPath expression under Table Columns.
For XMLType tables, a new empty row is automatically created for you to create your extract XPath expression under Table Columns.
Datatype defaults to Column Expression. You are not required to change this.
Figure 26-26 Enterprise Manager: Creating a Function-Based Index Based on XPath Expressions