Oracle9 i XML Database Developer’s Guide - Oracle XML DB Release 2 (9.2) October 2002 Part No. A96620-02 Oracle9i XML Database Developer’s Guide - Oracle XML DB, Release 2 (9.2) Part No. A96620-02 Copyright © 2002 Oracle Corporation. All rights reserved. Primary Author: Shelley Higgins Graphics: Valarie Moore Contributing Authors: Nipun Agarwal, Abhay Agrawal, Omar Alonso, Sandeepan Banerjee, Mark Bauer, Ravinder Booreddy, Yuen Chan, Sivasankaran Chandrasekar, Vincent Chao, Mark Drake, Fei Ge, Wenyun He, Thuvan Hoang, Sam Idicula, Neema Jalali, Bhushan Khaladkar, Viswanathan Krishnamurthy, Muralidhar Krishnaprasad, Wesley Lin, Annie Liu, Anand Manikutty, Jack Melnick, Nicolas Montoya, Steve Muench, Ravi Murthy, Eric Paapanen, Syam Pannala, John Russell, Eric Sedlar, Vipul Shah, Cathy Shea, Tarvinder Singh, Simon Slack, Muralidhar Subramanian, Asha Tarachandani, Randy Urbano, Priya Vennapusa, James Warner Contributors: Harish Akali, Deanna Bradshaw, Paul Brandenstein, Lisa Eldridge, Geoff Lee, Susan Kotsovolos, Sonia Kumar, Roza Leyderman, Diana Lorentz, Yasuhiro Matsuda, Bhagat Nainani, Visar Nimani, Sunitha Patel, Denis Raphaely, Rebecca Reitmeyer, Ronen Wolf The Programs (which include both the software and documentation) contain proprietary information of Oracle Corporation; they are provided under a license agreement containing restrictions on use and disclosure and are also protected by copyright, patent and other intellectual and industrial property laws. Reverse engineering, disassembly or decompilation of the Programs, except to the extent required to obtain interoperability with other independently created software or as specified by law, is prohibited. The information contained in this document is subject to change without notice. If you find any problems in the documentation, please report them to us in writing. Oracle Corporation does not warrant that this document is error-free. Except as may be expressly permitted in your license agreement for these Programs, no part of these Programs may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without the express written permission of Oracle Corporation. If the Programs are delivered to the U.S. Government or anyone licensing or using the programs on behalf of the U.S. Government, the following notice is applicable: Restricted Rights Notice Programs delivered subject to the DOD FAR Supplement are "commercial computer software" and use, duplication, and disclosure of the Programs, including documentation, shall be subject to the licensing restrictions set forth in the applicable Oracle license agreement. Otherwise, Programs delivered subject to the Federal Acquisition Regulations are "restricted computer software" and use, duplication, and disclosure of the Programs shall be subject to the restrictions in FAR 52.227-19, Commercial Computer Software - Restricted Rights (June, 1987). Oracle Corporation, 500 Oracle Parkway, Redwood City, CA 94065. The Programs are not intended for use in any nuclear, aviation, mass transit, medical, or other inherently dangerous applications. It shall be the licensee's responsibility to take all appropriate fail-safe, backup, redundancy, and other measures to ensure the safe use of such applications if the Programs are used for such purposes, and Oracle Corporation disclaims liability for any damages caused by such use of the Programs. Oracle is a registered trademark, and Oracle9i, Oracle8i, Oracle8, SQL*Plus, SQL*Net, Pro*C, On Oracle, Oracle Store, ConText, and PL/SQL are trademarks or registered trademarks of Oracle Corporation. Other names may be trademarks of their respective owners. iii Contents Send Us Your Comments xxix Preface xxxi Audience xxxii Organization xxxii Related Documentation xxxvii Conventions xxxviii Documentation Accessibility xli What’s New In Oracle XML DB? xliii Oracle XML DB: Oracle9i Release 2 (9.2.0.2): Enhancements xliii Oracle XML DB, Oracle9i Release 2 (9.2.0.1): XMLType Enhancements xlv Oracle XML DB, Oracle9i Release 2 (9.2.0.1): Repository xlvii Oracle Tools Enhancements for Oracle XML DB xlix Oracle Text Enhancements xlix Oracle Advanced Queuing (AQ) Support xlix Oracle XDK Support for XMLType l Part I Introducing Oracle XML DB 1 Introducing Oracle XML DB Introducing Oracle XML DB 1-2 Not a Separate Database Server 1-2 Benefits of Oracle XML DB 1-3 iv Key Features of Oracle XML DB 1-4 Oracle XML DB and XML Schema 1-7 Oracle XML DB Architecture 1-7 XMLType Tables and Views Storage 1-9 Oracle XML DB Repository 1-10 XMLType Storage Architecture 1-11 Cached XML Object Management Architecture 1-14 XML Repository Architecture 1-15 Why Use Oracle XML DB? 1-16 Unifying Data and Content with Oracle XML DB 1-17 Oracle XML DB Offers Faster Storage and Retrieval of Complex XML Documents 1-20 Oracle XML DB Helps You Integrate Applications 1-21 When Your Data Is Not XML You Can Use XMLType Views 1-21 Searching XML Data Stored in CLOBs Using Oracle Text 1-23 Building Oracle XML DB XML Messaging Applications with Advanced Queueing 1-23 Managing Oracle XML DB Applications with Oracle Enterprise Manager 1-24 Requirements for Running Oracle XML DB 1-25 Standards Supported by Oracle XML DB 1-25 Oracle XML DB Technical Support 1-26 Terminology Used in This Manual 1-26 Oracle XML DB Examples Used in This Manual 1-29 2 Getting Started with Oracle XML DB Getting Started with Oracle XML DB 2-2 Installing Oracle XML DB 2-2 When to Use the Oracle XML DB 2-2 Designing Your XML Application 2-3 Oracle XML DB Design Issues: Introduction 2-3 a. Data 2-3 b. Access 2-3 c. Application Language 2-4 d. Processing 2-4 Storage 2-4 Oracle XML DB Application Design: a. How Structured Is Your Data? 2-5 Oracle XML DB Application Design: b. Access Models 2-7 v Oracle XML DB Application Design: c. Application Language 2-8 Oracle XML DB Application Design: d. Processing Models 2-9 Oracle XML DB Design: Storage Models 2-10 Using XMLType Tables 2-11 Using XMLType Views 2-12 3 Using Oracle XML DB Storing Data in an XMLType Column or XMLType Table 3-3 Accessing Data in XMLType Columns or XMLType Tables 3-5 Using XPath with Oracle XML DB 3-5 Using existsNode() 3-7 Using extractValue() 3-8 Using extract() 3-10 Using XMLSequence() 3-11 Updating XML Documents with updateXML() 3-13 Introducing the W3C XSLT Recommendation 3-15 Using XSL/XSLT with Oracle XML DB 3-16 Other XMLType Methods 3-17 Introducing the W3C XML Schema Recommendation 3-18 Using XML Schema with Oracle XML DB 3-19 XMLSchema-Instance Namespace 3-21 Validating an XML Document Using an XML Schema 3-22 Storing XML: Structured or Unstructured Storage 3-24 Data Manipulation Language (DML) Independence 3-27 DOM Fidelity in Structured and Unstructured Storage 3-27 Structured Storage: XML Schema-Based Storage of XMLType 3-28 Structured Storage: Storing complexType Collections 3-32 Structured Storage: Data Integrity and Constraint Checking 3-33 Oracle XML DB Repository 3-35 Query-Based Access to Oracle XML DB Repository 3-37 Using RESOURCE_VIEW 3-37 Using PATH_VIEW 3-37 Creating New Folders and Documents 3-38 Querying Resource Documents 3-38 Updating Resources 3-38 vi Deleting Resources 3-39 Storage Options for Resources 3-40 Defining Your Own Default Table Storage for XML Schema-Based Documents 3-40 Accessing XML Schema-Based Content 3-44 Accessing Non-Schema-Based Content With XDBUriType 3-44 Oracle XML DB Protocol Servers 3-44 Using FTP Protocol Server 3-45 Using HTTP/WebDAV Protocol Server 3-49 Part II Storing and Retrieving XML Data in Oracle XML DB 4 Using XMLType What Is XMLType? 4-2 Benefits of the XMLType Data Type and API 4-3 When to Use XMLType 4-4 Storing XMLType Data in Oracle XML DB 4-4 Pros and Cons of XML Storage Options in Oracle XML DB 4-5 When to Use CLOB Storage for XMLType 4-6 XMLType Member Functions 4-7 How to Use the XMLType API 4-7 Creating, Adding, and Dropping XMLType Columns 4-8 Inserting Values into an XMLType Column 4-9 Using XMLType in an SQL Statement 4-9 Updating an XMLType Column 4-10 Deleting a Row Containing an XMLType Column 4-10 Guidelines for Using XMLType Tables and Columns 4-11 Specifying Storage Characteristics on XMLType Columns 4-12 Changing Storage Options on an XMLType Column Using XMLData 4-13 Specifying Constraints on XMLType Columns 4-14 Manipulating XML Data in XMLType Columns/Tables 4-14 Inserting XML Data into XMLType Columns/Tables 4-15 Using INSERT Statements 4-15 Selecting and Querying XML Data 4-17 Selecting XML Data 4-17 Querying XML Data 4-18 vii Using XPath Expressions for Searching XML Documents 4-18 Querying XML Data Using XMLType Member Functions 4-19 existsNode Function 4-20 extract () Function 4-21 extractValue() Function 4-24 More SQL Examples That Query XML 4-26 Updating XML Instances and Data in Tables and Columns 4-31 updateXML() SQL Function 4-31 Creating Views of XML Data with updateXML() 4-35 Optimization of updateXML() 4-35 updateXML() and NULL Values 4-36 Updating the Same XML Node More Than Once 4-37 XMLTransform() Function 4-37 Deleting XML Data 4-38 Using XMLType In Triggers 4-38 Indexing XMLType Columns 4-39 Creating Function-Based Indexes on XMLType Columns 4-39 Creating Oracle Text Indexes on XMLType Columns 4-40 5 Structured Mapping of XMLType Introducing XML Schema 5-3 XML Schema and Oracle XML DB 5-3 Using Oracle XML DB and XML Schema 5-5 Why Do We Need XML Schema? 5-6 DTD Support in Oracle XML DB 5-7 Introducing DBMS_XMLSCHEMA 5-8 Registering Your XML Schema Before Using Oracle XML DB 5-8 Registering Your XML Schema Using DBMS_XMLSCHEMA 5-9 Local and Global XML Schemas 5-11 Registering Your XML Schema: Oracle XML DB Sets Up the Storage and Access Infrastructure 5-13 Deleting Your XML Schema Using DBMS_XMLSCHEMA 5-13 Guidelines for Using Registered XML Schemas 5-14 Objects That Depend on Registered XML Schemas 5-14 viii Creating XMLType Tables, Views, or Columns 5-15 Validating XML Instances Against the XML Schema: schemaValidate() 5-15 Fully Qualified XML Schema URLs 5-16 Transactional Behavior of XML Schema Registration 5-17 Generating XML Schema Using DBMS_XMLSCHEMA.generateSchema() 5-17 XML Schema-Related Methods of XMLType 5-19 Managing and Storing XML Schema 5-19 Root XML Schema, XDBSchema.xsd 5-19 How Are XML Schema-Based XMLType Structures Stored? 5-20 DOM Fidelity 5-21 How Oracle XML DB Ensures DOM Fidelity with XML Schema 5-21 DOM Fidelity and SYS_XDBPD$ 5-21 Creating XMLType Tables and Columns Based on XML Schema 5-22 SQL Object-Relational Types Store XML Schema-Based XMLType Tables 5-23 Specifying SQL Object Type Names with SQLName, SQLType Attributes 5-24 SQL Mapping Is Specified in the XML Schema During Registration 5-28 Mapping of Types Using DBMS_XMLSCHEMA 5-31 Setting Attribute Mapping Type Information 5-31 Setting Element Mapping Type Information 5-31 XML Schema: Mapping SimpleTypes to SQL 5-33 simpleType: Mapping XML Strings to SQL VARCHAR2 Versus CLOBs 5-36 XML Schema: Mapping complexTypes to SQL 5-37 Setting the SQLInLine Attribute to FALSE for Out-of-Line Storage 5-37 Mapping XML Fragments to Large Objects (LOBs) 5-39 Oracle XML DB complexType Extensions and Restrictions 5-41 complexType Declarations in XML Schema: Handling Inheritance 5-41 Mapping complexType: simpleContent to Object Types 5-44 Mapping complexType: Any and AnyAttributes 5-45 Handling Cycling Between complexTypes in XML Schema 5-46 Further Guidelines for Creating XML Schema-Based XML Tables 5-49 Specifying Storage Clauses in XMLType CREATE TABLE Statements 5-50 Inserting New Instances into XMLType Columns 5-51 Query Rewrite with XML Schema-Based Structured Storage 5-51 What Is Query Rewrite? 5-51 When Does Query Rewrite Occur? 5-52 ix What XPath Expressions Are Rewritten? 5-53 How are the XPaths Rewritten? 5-55 Rewriting XPath Expressions: Mapping Types and Issues 5-57 XPath Expression Rewrites for existsNode() 5-62 Rewrite for extractValue() 5-65 Rewrite for extract() 5-67 Optimizing Updates Using updateXML() 5-69 Creating Default Tables During XML Schema Registration 5-70 Ordered Collections in Tables (OCTs) 5-71 Using OCT for VARRAY Storage 5-71 Cyclical References Between XML Schemas 5-71 Frequently Asked Questions (FAQs): XML DB, XML Schema-Based Issues 5-74 Why Do I Appear to get Memory Leaks When Using Bind Variables for XPath Expressions? 5-74 How Do I Check that Query Rewrite is Working Correctly? 5-77 Why Does the XML DB Query Not Use My Index? 5-78 How Do I Specify Attributes in a complexType XML Schema Declaration? 5-79 Why Do the XML Schema and Element Not Match? 5-81 How Do I Pull a Stylesheet From RESOURCE_VIEW [S/MIME]? 5-82 Why for Our XML Parser Does selectSingleNode return NULL When the xmlns Attribute is Added? 5-82 Why Do I Get Error ORA-19007: Schema and Element Do Not Match? 5-84 Is it Possible to Register XML Schema for Schemas? 5-86 6 Transforming and Validating XMLType Data Transforming XMLType Instances 6-2 XMLTransform() and XMLType.transform() 6-2 XMLTransform() Examples 6-3 Validating XMLType Instances 6-8 Validating XML Data Stored as XMLType: Examples 6-10 7 Searching XML Data with Oracle Text Searching XML Data with Oracle Text 7-3 Introducing Oracle Text 7-3 Assumptions Made in This Chapter’s Examples 7-4 x Oracle Text Users and Roles 7-5 Querying with the CONTAINS Operator 7-6 Using the WITHIN Operator to Narrow Query Down to Document Sections 7-8 Introducing SECTION_GROUPS 7-8 XML_SECTION_GROUP 7-8 AUTO_ SECTION_GROUP/ PATH_SECTION_GROUP for INPATH and HASPATH 7-10 Dynamically Adding Sections or Stop Section Using ALTER INDEX 7-10 WITHIN Syntax for Section Querying 7-11 WITHIN Operator Limitations 7-11 INPATH or HASPATH Operators Search Using XPath-Like Expressions 7-12 Using INPATH Operator for Path Searching in XML Documents 7-13 Using HASPATH Operator for Path Searching in XML Documents 7-19 Building a Query Application with Oracle Text 7-21 What Role Do You Need? 7-21 Step 1. Create a Section Group Preference 7-21 Deciding Which Section Group to Use 7-23 Creating a Section Preference with XML_SECTION_GROUP 7-23 Creating a Section Preference with AUTO_SECTION_GROUP 7-23 Creating a Section Preference with PATH_SECTION_GROUP 7-24 Step 2. Set the Preference’s Attributes 7-24 2.1 XML_SECTION_GROUP: Using CTX_DDL.add_zone_section 7-25 2.2 XML_SECTION_GROUP: Using CTX_DDL.Add_Attr_Section 7-25 2.3 XML_SECTION_GROUP: Using CTX_DDL.Add_Field_Section 7-26 2.5 AUTO_SECTION_GROUP: Using CtX_DDL.Add_Stop_Section 7-28 Step 3. Create an Index Using the Section Preference Created in Step 2 7-28 Step 4. Create Your Query Syntax 7-30 Querying Within Attribute Sections 7-30 Presenting the Results of Your Query 7-34 XMLType Indexing 7-35 You Need Query Rewrite Privileges 7-35 System Parameter is Set to the Default, CTXSYS.PATH_SECTION_GROUP 7-36 XMLType Indexes Work Like Other Oracle Text Indexes 7-36 Using Oracle Text with Oracle XML DB 7-37 Creating an Oracle Text Index on an UriType Column 7-37 Querying XML Data: Use CONTAINS or existsNode()? 7-38 [...]... other Oracle XML DB Resource APIs xxxiv Chapter 16, "Oracle XML DB Resource API for PL/SQL (DBMS_XDB)" Describes DBMS _Oracle XML DB and the Oracle XML DB Resource API for PL/SQL Chapter 17, "Oracle XML DB Resource API for Java" Describes Oracle XML DB Resource API for Java/JNDI and how to use it to access Oracle XMl DB Repository data Chapter 18, "Oracle XML DB Resource Security" Describes how to use Oracle. .. Oracle XML DB Example Servlet Testing the Example Servlet Part VI 21 20-2 20-2 20-3 20-3 20-3 20-3 20-4 20-4 20-8 20-9 20-9 20-10 20-10 20-11 20-12 20-12 Oracle Tools that Support Oracle XML DB Managing Oracle XML DB Using Oracle Enterprise Manager Introducing Oracle XML DB and Oracle Enterprise Manager Getting Started with Oracle Enterprise Manager and Oracle XML DB Oracle. .. manual describes Oracle XML DB, the Oracle9 i XML database It describes how XML data can be stored, generated, manipulated, managed, and queried in the database using Oracle XML DB After introducing you to the heart of Oracle XML DB , namely the XMLType framework and Oracle XML DB Repository, the manual provides a brief introduction to design criteria to consider when planning your Oracle XML DB application... Write Out Data Quickly as XML Writing Oracle XML DB HTTP Servlets in Java Configuring Oracle XML DB Servlets HTTP Request Processing for Oracle XML DB Servlets The Session Pool and XML DB Servlets Native XML Stream Support Oracle XML DB Servlet APIs Oracle XML DB Servlet Example Installing the Oracle XML DB Example Servlet... how you can use Oracle XML DB Chapter 1, "Introducing Oracle XML DB" Introduces you to the Oracle XML DB components and architecture It includes a description of the benefits of using Oracle XML DB, the key features, standards supported, and requirements for running Oracle XML DB It lists Oracle XML DB-related terms used throughout the manual Chapter 2, "Getting Started with Oracle XML DB" Describes... using Oracle9 i database native XMLType API xxxii Chapter 4, "Using XMLType" Describes how to create XMLType tables and manipulate and query XML data for non-schema-based XMLType tables and columns Chapter 5, "Structured Mapping of XMLType" Describes how to use Oracle XML DB mapping from SQL to XML and back, provides an overview of how you must register your XML schema, how you can either use Oracle XML. .. 16-11 16-11 Oracle XML DB Resource API for Java Introducing Oracle XML DB Resource API for Java Using Oracle XML DB Resource API for Java Parameters for Oracle XML DB Resource API for Java Oracle XML DB Resource API for Java: Examples 18 15-11 15-11 15-11 15-12 15-13 15-14 15-15 15-16 15-16 17-2 17-2 17-2 17-3 Oracle XML DB Resource Security Introducing Oracle XML DB Resource... 19-7 Using FTP and Oracle XML DB Protocol Server 19-7 Oracle XML DB Protocol Server: FTP Features 19-7 Using HTTP and Oracle XML DB Protocol Server 19-9 Oracle XML DB Protocol Server: HTTP Features 19-9 Using WebDAV and Oracle XML DB 19-11 Oracle XML DB WebDav Features 19-11 Using Oracle XML DB and WebDAV: Creating a WebFolder... Loading XML Data into Oracle XML DB Loading XMLType Data into Oracle9 i Database 22-2 Restoration 22-2 Using SQL*Loader to Load XMLType Columns 22-2 23 Importing and Exporting XMLType Tables Overview of IMPORT/EXPORT Support in Oracle XML DB Resource s and Foldering Do Not Fully Support IMPORT/EXPORT Non -XML Schema-Based XMLType Tables and Columns XML. .. generating XML SQLX functions include XMLElement()and XMLForest() xxxiii Oracle SQLX extension functions include XMLColAttValue() SQL functions include SYS_XMLGEN(), XMLSEQUENCE(), and SYS_XMLAGG() It also describes how to use DBMS_XMLGEN, XSQL Pages Publishing Framework, and XML SQL Utility (XSU) to generate XML data from data stored in the database Chapter 11, "XMLType Views" Describes how to create XMLType . New In Oracle XML DB? xliii Oracle XML DB: Oracle9 i Release 2 (9.2.0.2): Enhancements xliii Oracle XML DB, Oracle9 i Release 2 (9.2.0.1): XMLType Enhancements xlv Oracle XML DB, Oracle9 i Release. Introducing Oracle XML DB Introducing Oracle XML DB 1-2 Not a Separate Database Server 1-2 Benefits of Oracle XML DB 1-3 iv Key Features of Oracle XML DB 1-4 Oracle XML DB and XML Schema 1-7 Oracle XML. Oracle Text Indexes on XMLType Columns 4-40 5 Structured Mapping of XMLType Introducing XML Schema 5-3 XML Schema and Oracle XML DB 5-3 Using Oracle XML DB and XML Schema 5-5 Why Do We Need XML