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 [...]... API for XMLType (DBMS_XSLPROCESSOR): Calling Sequence PL/SQL XSLT Processor for XMLType Example 9 8-2 8-2 8-3 8-4 8-5 8-5 8-7 8-8 8-9 8-1 0 8-1 1 8-1 1 8-2 0 8-2 0 8-2 2 8-2 2 8-2 3 8-2 4 8-2 6 8-2 6 8-2 8 8-2 9 8-3 0 8-3 0 8-3 0 8-3 1 8-3 2 8-3 3 Java API for XMLType Introducing Java DOM API for XMLType 9-2 xii Java DOM API for XMLType Accessing XML Documents Stored in Oracle9 i Database. .. VI 21 2 0-2 2 0-2 2 0-3 2 0-3 2 0-3 2 0-3 2 0-4 2 0-4 2 0-8 2 0-9 2 0-9 2 0-1 0 2 0-1 0 2 0-1 1 2 0-1 2 2 0-1 2 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 Enterprise Manager Oracle XML DB Features Configure Oracle XML DB ... CLOBs Using Oracle Text 7-4 0 7-4 0 7-4 0 7-4 1 7-4 2 7-4 5 7-4 5 7-4 6 7-4 6 7-4 7 7-4 7 7-4 9 7-4 9 7-5 1 7-5 1 7-5 2 7-5 2 7-5 4 7-5 5 7-5 5 7-5 5 7-5 6 7-5 7 7-5 7 7-5 8 7-6 2 7-6 5 7-6 5 7-7 1 7-7 1 xi Part III 8 Using XMLType APIs to Manipulate XML Data PL/SQL API for XMLType Introducing PL/SQL APIs for XMLType Backward Compatibility with XDK for PL/SQL, Oracle9 i Release 1 (9.0.1) PL/SQL APIs For XMLType Features... Part V 13 1 2-1 7 1 2-1 8 1 2-1 8 1 2-1 8 1 2-1 9 1 2-2 0 1 2-2 1 1 2-2 3 1 2-2 3 1 2-2 3 1 2-2 5 1 2-2 6 1 2-2 6 1 2-2 9 1 2-2 9 1 2-3 0 1 2-3 1 1 2-3 4 1 2-3 4 1 2-3 6 1 2-3 7 1 2-3 8 Oracle XML DB Repository: Foldering, Security, and Protocols Oracle XML DB Foldering Introducing Oracle XML DB Foldering Oracle XML DB Repository Repository Terminology Oracle XML DB Resources Where Exactly... Oracle- Provided SQL Functions SYS_XMLGEN() Function Using XMLFormat Object Type SYS_XMLAGG() Function Generating XML Using XSQL Pages Publishing Framework Generating XML Using XML SQL Utility (XSU) 1 0-2 1 0-2 1 0-2 1 0-2 1 0-2 1 0-3 1 0-3 1 0-5 1 0-5 1 0-9 1 0-1 1 1 0-1 5 1 0-1 7 1 0-2 0 1 0-2 0 1 0-2 1 1 0-2 1 1 0-2 2 1 0-4 2 1 0-4 2 1 0-4 4 1 0-5 1 1 0-5 2 1 0-5 4 xiii 11 XMLType... 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 1 5-1 1 1 5-1 1 1 5-1 1 1 5-1 2 1 5-1 3 1 5-1 4 1 5-1 5 1 5-1 6 1 5-1 6 1 7-2 1 7-2 1 7-2 1 7-3 Oracle XML DB Resource Security Introducing Oracle XML DB Resource Security and ACLs How the ACL-Based... (FAQs): XML DB Repository Why Does XML Repository Hierarchical Index Not Work? 14 1 3-1 0 1 3-1 2 1 3-1 3 1 3-1 4 1 3-1 6 1 3-1 7 1 3-1 8 1 3-1 8 Oracle XML DB Versioning Introducing Oracle XML DB Versioning 1 4-2 Oracle XML DB Versioning Features 1 4-2 Oracle XML DB Versioning Terms Used in This Chapter 1 4-3 Oracle XML DB Resource ID and Path Name 1 4-3 Creating a Version-Controlled... the XML Document Is Processed? How Can I Use HTTPS with AQ? What Are the Options for Storing XML in AQ Message Payloads? Can We Compare IDAP and SOAP? Part VIII 2 4-2 2 4-2 2 4-5 2 4-6 2 4-6 2 4-7 2 4-7 2 4-8 2 4-1 0 2 4-1 3 2 4-1 4 2 4-1 4 2 4-1 4 2 4-1 5 2 4-1 5 2 4-1 5 2 4-1 6 2 4-1 7 2 4-1 7 2 4-1 7 2 4-1 8 Oracle XML DB Case Studies 25 Oracle XML DB Case Study: Web Services Retrieve and Display XML Documents... Oracle XML DB Resources XDBResource.xsd acl.xsd: XML Schema for Representing Oracle XML DB ACLs ACL Representation XML Schema, acl.xsd acl.xsd xdbconfig.xsd: XML Schema for Configuring Oracle XML DB xdbconfig.xsd G-9 G-10 G-11 G-12 G-12 G-12 G-12 G-12 G-15 G-15 G-15 G-18 G-18 Glossary Index xxvii xxviii Send Us Your Comments Oracle9 i XML. .. E-2 Oracle XML DB Resource API for Java E-6 F Oracle XML DB XMLType API, PL/SQL and Resource PL/SQL APIs: Quick Reference XMLType API F-2 PL/SQL DOM API for XMLType (DBMS_XMLDOM) F-6 PL/SQL Parser for XMLType (DBMS_XMLPARSER) F-14 PL/SQL XSLT Processor for XMLType (DBMS_XSLPROCESSOR) F-15 DBMS_XMLSCHEMA F-16 Oracle XML DB XML Schema . 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. Oracle9 i XML Database Developer’s Guide - Oracle XML DB Release 2 (9.2) October 2002 Part No. A9662 0-0 2 Oracle9 i XML Database Developer’s Guide - Oracle