Oracle® XML Developer's Kit Programmer's Guide 10g Release 1 (10.1) Part No. B10794-01 December 2003 Oracle XML Developer's Kit Programmer's Guide, 10g Release 1 (10.1) Part No. B10794-01 Copyright © 2001, 2003 Oracle Corporation. All rights reserved. Primary Author: Jack Melnick Contributing Authors: Mark Bauer, Shelley Higgins, Steve Muench, Mark Scardina, Jinyu Wang Contributors: Sandeepan Banerjee, Sivasankaran Chandrasekar, Dan Chiba, Steve Ding, Stanley Guan, Bill Han, K. Karun, Murali Krishnaprasad, Dmitry Lenkov, Roza Leyderman, Bruce Lowenthal, Ian Macky, Anjana Manian, Meghna Mehta, Valarie Moore, Ravi Murthy, Anguel Novoselsky, Tomas Saulys, Helen Slattery, Asha Tarachandani, Tim Yu, Jim Warner, Simon Wong, Kongyi Zhou 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 Express, Oracle Discoverer, Oracle Store, Oracle8, Oracle8i, Oracle9i, PL/SQL, Pro*C/C++, and SQL*Plus are trademarks or registered trademarks of Oracle Corporation. Other names may be trademarks of their respective owners. iii Contents Send Us Your Comments xxiii Preface xxv Audience xxv Organization xxvi Related Documentation xxviii Conventions xxix Documentation Accessibility xxxiv What's New in XDK? xxxvii Features Introduced in Oracle XML Developer's Kit 10g Release 1 (10.1) xxxvii 1 Overview of XML Developer's Kit Components Introducing Oracle XML Developer's Kit 1-1 Overview of Oracle XDK Components 1-3 XDK Functionality Applied to XML Documents 1-4 XML Parsers 1-5 XSL Transformation (XSLT) Processors 1-6 JAXB and C++ Class Generators 1-6 XML Schema Processor 1-7 XDK JavaBeans 1-7 DOMBuilder 1-7 XSLTransformer 1-7 DBAccess 1-8 iv XMLDiff 1-8 XMLCompress 1-8 XMLDBAccess 1-8 XSDValidator 1-8 Oracle XML SQL Utility (XSU) for Java 1-8 XSQL Pages Publishing Framework 1-9 TransX Utility 1-9 Soap Services 1-9 Using XDK-supported Languages to Generate XML Documents 1-10 Using XSU for Java to Generate XML Documents 1-10 Generating XML from Query Results 1-10 XML Document Structure: Columns Are Mapped to Elements 1-10 XSU Generates the XML Document as a String or DOM Element Tree 1-11 XSU Generates a DTD Based on Queried Table's Schema 1-11 Using Oracle XDK Java Components to Generate XML Documents 1-12 Using Oracle XDK C Components to Generate XML Documents 1-14 Using Oracle XDK C++ Components to Generate XML Documents 1-16 XDK and Application Development Tools 1-18 Browsers That Support XML 1-20 Oracle XML Gateway 1-20 Oracle Data Provider for .NET 1-20 JDeveloper 1-21 Business Components for Java (BC4J) 1-23 User Interface XML (UIX) 1-23 Oracle Reports 1-24 Recommended Books and Web Sites About XML 1-24 Using Oracle XML-Enabled Technology 1-25 Information for Using the XDK 1-25 Using Apache Web Server Instead of the Oracle9i Application Server 1-26 Need for an XML Parser If all the XML Was Created By Programs 1-26 SQL*Loader and Nesting in XML Documents 1-26 Information About Previous Oracle Releases 1-27 Using Oracle Database Version 7 and XML 1-27 Doing Data Transfers to Other Vendors Using XML from Oracle Release 7.3.4 1-28 Using Versions Prior to Oracle8i and Oracle XML Tools? 1-28 v XML Standards That Oracle Supports 1-28 B2B Standards and Development Tools that Oracle Supports 1-28 Oracle Corporation's Direction Regarding XML 1-29 Oracle Corporation's Plans for XML Query 1-29 Maximum XML File Sizes 1-30 Limitations on the Size of an XML File 1-30 Size Limit for XML Documents Generated from the Database 1-30 Maximum Size for an XML Document for PL/SQL 1-30 2 Getting Started with XDK Java Components XDK Java Components Specifications 2-1 DOM Specifications 2-2 XSL Transformations Specifications 2-3 Installing XDK Java Components 2-4 XDK Java Components Directory Structure 2-5 XDK Java Components Environment Settings 2-6 UNIX Environment Settings for XDK Java Components 2-6 Windows Environment Settings for XDK Java Components 2-7 Setting Up XSQL Servlet 2-8 Servlet Engines 2-8 Java Server Pages Implementations 2-9 JDBC Drivers and Databases 2-9 Setting Up the Database Connection Definitions for Your Environment 2-10 Setting Up Your Servlet Engine to Run XSQL Pages 2-10 Oracle Application Server (OracleAS) 2-11 OracleAS Oracle Containers for Java (OC4J) Servlet Container 2-11 Apache/JServ 1.0 or 1.1 2-13 Jakarta Tomcat 3.1 or 3.2 2-14 XDK Java Components Globalization Support 2-18 XDK Java Components Dependencies 2-18 Verifying the XDK Java Components Version 2-19 3 XML Parser for Java XML Parser for Java Overview 3-1 Namespace Support 3-3 vi XML Parser for Java Validation Modes 3-4 Using DTDs with the XML Parser for Java 3-6 Enabling DTD Caching 3-6 Recognizing External DTDs 3-7 Loading External DTDs from a JAR File 3-8 Checking the Correctness of Constructed XML Documents 3-8 Parsing a DTD Object Separately from an XML Document 3-8 XML Parsers Case-Sensitivity 3-9 Allowed File Extensions in External Entities 3-9 Creating a DOCUMENT_TYPE_NODE 3-9 Standard DTDs That Can be Used for Orders, Shipments, and So On 3-9 About DOM and SAX APIs 3-9 DOM: Tree-Based API 3-10 SAX: Event-Based API 3-10 Guidelines for Using DOM and SAX APIs 3-11 DOM 3-11 SAX 3-12 About XML Compressor 3-12 XML Serialization and Compression 3-13 Running the Sample Applications for XML Parser for Java 3-14 Using XML Parser for Java: DOMParser Class 3-16 Without DTD Input 3-16 With a DTD Input 3-17 Comments on Example 1: DOMSample.java 3-18 XML Parser for Java Example 1: DOMSample.java 3-19 Using XML Parser for Java: DOMNamespace Class 3-22 XML Parser for Java Example 2: Parsing a URL — DOMNamespace.java 3-22 Using XML Parser for Java: SAXParser Class 3-23 XML Parser for Java Example 3: Using the Parser and SAX API (SAXSample.java) 3-26 XML Parser for Java Example 4: (SAXNamespace.java) 3-30 Using the XML Parser for Java 3-34 Using DOM and SAX APIs for Java 3-35 Using the DOM API to Count Tagged Elements 3-35 Creating a Node with a Value to Be Set Later 3-35 Traversing the XML Tree Using XPATH 3-35 vii Finding the First Child Node Element Value 3-35 Using the XMLNode.selectNodes() Method 3-35 Generating an XML Document from Data in Variables 3-36 Using the DOM API to Print Data in the Element Tags 3-37 Building XML Files from Hash Table Value Pairs 3-37 DOM Exception WRONG_DOCUMENT_ERR on Node.appendChild() 3-37 Getting DOMException when Setting Node Value 3-38 Extracting Embedded XML from a CDATA Section 3-38 Using Character Sets with the XML Parser for Java 3-39 Reading a Unicode XML File 3-39 Writing an XML File in UTF-8 3-39 Writing Parsing XML Stored in NCLOB with UTF-8 Encoding 3-40 Parsing a Document Containing Accented Characters 3-41 Storing Accented Characters in an XML Document 3-41 You Cannot Dynamically Set the Encoding for an Input XML File 3-42 Using System.out.println() and Special Characters 3-42 General Questions About XML Parser for Java 3-42 Including Binary Data in an XML Document 3-43 Displaying an XML Document 3-43 Including an External XML File in Another XML File 3-43 You Do Not Need Oracle9i or Higher to Run XML Parser for Java 3-44 Inserting Characters <, >, ', ", and & into XML Documents 3-44 Invalid Special Characters in Tags 3-44 Parsing XML from Data of Type String 3-44 Extracting Data from an XML Document into a String 3-45 Illegal Characters in XML Documents 3-45 Using Entity References with the XML Parser for Java 3-45 Merging XML Documents 3-45 The XML Parser for Java Does Not Need a Utility to View the Parsed Output 3-45 Support for Hierarchical Mapping 3-47 Support for Ambiguous Content Mode 3-47 Generating an XML Document Based on Two Tables 3-47 Using JAXP 3-49 oraxml: XML Parser for Java Command-line 3-50 viii 4 XSLT Processor for Java XSLT Processor for Java Overview 4-1 Using XSLT Processor for Java 4-2 XSLT Processor for Java Example 4-4 XSLT Command-Line Interface: oraxsl 4-6 XML Extension Functions for XSLT Processing 4-7 XSLT Processor for Java Extension Functions and Namespaces 4-8 Static Versus Non-Static Methods 4-8 XML Parser for Java - XSL Example 1: Static function 4-8 Constructor Extension Function 4-9 XML Parser for Java - XSL Example 2: Constructor Extension Function 4-9 Return Value Extension Function 4-9 XML Parser for Java XSL- XSL Example 3: Return Value Extension Function 4-10 Datatypes Extension Function 4-10 XML Parser for Java - XSL Example 4: Datatype Extension Function 4-10 XSLT Processor for Java Built-In Extensions: ora:node-set and ora:output 4-11 ora:output 4-11 ora:node-set 4-11 Example of Use of Oracle XSL Extensions 4-11 Hints for Using the XSLT Processor for Java and XSL 4-14 Merging Two XML Documents 4-14 Example: Using importNode() from DOM Level 2 4-14 Example: Using adoptNode from DOM Level 3 4-15 Example: demo1.xml 4-15 Example: demo2.xml 4-15 Example: demomerge.xsl 4-16 Extracting Embedded XML Using Only XSLT 4-17 Support of Output Method "html" in the XSL Parser 4-17 Creating an HTML Input Form 4-18 Correct XSL Namespace URI 4-18 XSL Processor Produces Multiple Outputs 4-18 Keeping White Spaces in Your Output 4-18 XDK Utilities That Translate Data from Other Formats to XML 4-19 Multiple Threads Using a Single XSLProcessor and Stylesheet 4-19 Using Document Clones in Multiple Threads 4-19 ix Disabling Output Escaping Is Supported 4-19 5 XML Schema Processor for Java What Is XML Schema? 5-1 What Are DTDs? 5-1 DTD Limitations 5-2 Comparison of XML Schema Features to DTD Features 5-2 XML Schema Processor for Java Features 5-4 Supported Character Sets 5-5 Requirements to Run XML Schema Processor for Java 5-5 XML Schema Processor for Java Usage 5-6 Using the XML Schema API 5-7 XML Schema Processor for Java Sample Programs 5-8 6 Using JAXB Class Generator What Is JAXB? 6-1 Replacing the XML Class Generator with JAXB Class Generator 6-2 Unmarshalling, Marshalling, and Validating Using JAXB 6-2 Using JAXB Class Generator 6-3 Features Not Supported in JAXB 6-3 JAXB Class Generator Command-Line Interface 6-3 JAXB Compared with JAXP 6-4 7 XML SQL Utility (XSU) What Is XML SQL Utility (XSU)? 7-2 Generating XML from the Database 7-2 Storing XML in the Database 7-2 Accessing XSU Functionality 7-2 XSU Features 7-2 XSU Dependencies and Installation 7-3 Dependencies of XSU 7-4 Installing XSU 7-4 Where XSU can be Installed 7-5 XML SQL Utility in the Database 7-5 x XML SQL Utility in the Middle Tier 7-6 XML SQL Utility in a Web Server 7-7 SQL-to-XML and XML-to-SQL Mapping Primer 7-8 Default SQL-to-XML Mapping 7-8 SQL-to-XML Mapping Against Object-Relational Schema 7-9 Customizing the Generated XML: Mapping SQL to XML 7-11 Source Customizations 7-12 Mapping Customizations 7-12 Post-Generation Customizations 7-13 Default XML-to-SQL Mapping 7-13 How XML SQL Utility Works 7-14 Selecting with XSU 7-14 Queries That XSU Cannot Handle 7-14 Inserting with XSU 7-14 Updating with XSU 7-15 Deleting with XSU 7-16 Using the XSU Command-Line Front End OracleXML 7-16 Generating XML Using the XSU Command Line 7-17 XSU's OracleXML getXML Options 7-17 Inserting XML Using XSU's Command Line (putXML) 7-19 XSU OracleXML putXML Options 7-20 XSU Java API 7-21 Generating XML with XSU's OracleXMLQuery 7-21 Generating XML from SQL Queries Using XSU 7-22 XSU Generating XML Example 1: Generating a String from Table employees (Java) 7-22 How to Run This Program 7-25 XSU Generating XML Example 2: Generating DOM from Table employees (Java) 7-25 Paginating Results: skipRows and maxRows 7-27 Keeping the Object Open for the Duration of the User's Session 7-27 When the Number of Rows or Columns in a Row Is Too Large 7-27 keepObjectOpen Function 7-28 XSU Generating XML Example 3: Paginating Results: (Java) 7-28 Generating XML from ResultSet Objects 7-29 XSU Generating XML Example 4: Generating XML from JDBC ResultSets (Java) 7-29 XSU Generating XML Example 5: Generating XML from Procedure Return Values 7-31 [...]... the XML Developer's Kit (XDK) and how the various language components of the XDK can work together to generate and store XML data in a database or in a document outside the database Examples and sample applications are introduced where possible Other Documentation on XML For more information about building XML- enabled database applications: See Also: s Oracle XML DB Developer's Guide s Oracle XML API... XSU Generating XML Example 6: No Rows Exception (Java) Storing XML Back in the Database Using XSU OracleXMLSave Insert Processing Using XSU (Java API) XSU Inserting XML Example 7: Inserting XML Values into All Columns (Java) XSU Inserting XML Example 8: Inserting XML Values into Columns (Java) Update Processing Using XSU (Java API) XSU Updating XML Example 9: Updating... Reference s Oracle Streams Advanced Queuing User’s Guide and Reference xxv Examples and Sample Code Many of the XDK examples in this documentation are provided with your software in the following directories: s $ORACLE_ HOME/xdk/demo/java/ s $ORACLE_ HOME/xdk/demo/c/ s $ORACLE_ HOME/xdk/java/sample/ s $ORACLE_ HOME/rdbms/demo XML Forum Post any questions, comments, or bug reports to the XML Forum on the Oracle. .. ORACLE_ BASE \ORACLE_ HOME\rdbms\admin directory This release complies with Optimal Flexible Architecture (OFA) guidelines All subdirectories are not under a top level ORACLE_ HOME directory There is a top level directory called ORACLE_ BASE that by default is C: \oracle If you install the latest Oracle release on a computer with no other Oracle software installed, then the default setting for the first Oracle. .. Sample Files Included with the Software 21 XML Schema Processor for C++ Oracle XML Schema Processor for C++ Oracle XML Schema for C++ Features Online Documentation Standards Conformance XML Schema Processor API Invoking XML Schema Processor for C++ Running the Provided XML Schema for C++ Sample Programs 22 20-1 20-2... 23 XML Class Generator for C++ Accessing XML C++ Class Generator Using XML C++ Class Generator External DTD Parsing Error Message Files XML C++ Class Generator Usage Input to the XML C++ Class Generator xx 23-1 23-1 23-2 23-2 23-2 23-3 Using the XML C++ Class Generator Examples XML C++ Class Generator Example 1: XML. .. File to Class Generator, CG .xml XML C++ Class Generator Example 2: DTD — Input File to Class Generator, CG.dtd XML C++ Class Generator Example 3: CG Sample Program 24 23-3 23-4 23-4 23-5 XSU for PL/SQL XSU PL/SQL API Generating XML with DBMS_XMLQuery() XSU Generating XML Example 1: Generating XML from Simple Queries (PL/SQL) XSU Generating XML Example 2: Printing CLOB... C: \oracle\ orann, where nn is the latest release number The Oracle home directory is located directly under ORACLE_ BASE All directory path examples in this guide follow OFA conventions Refer to Oracle Database Platform Guide for Windows for additional information about OFA compliances and for information about installing Oracle products in non-OFA compliant directories xxxiii Special Conventions This guide. .. dept) HOME_NAME Represents the Oracle home name The C:\> net start OracleHOME_NAMETNSListener home name can be up to 16 alphanumeric characters The only special character allowed in the home name is the underscore ORACLE_ HOME and ORACLE_ BASE In releases prior to Oracle8 i release 8.1.3, when you installed Oracle components, all subdirectories were located under a top level ORACLE_ HOME directory For Windows... Processor Accessing Oracle XSL Processor for C Using the Demo Files Included with the Software Building the C Demo Programs for XSLT 16 15-1 15-2 15-3 15-4 15-4 15-4 15-5 15-6 15-7 15-7 15-8 XML Schema Processor for C Oracle XML Schema Processor for C Oracle XML Schema for C Features Standards Conformance XML Schema Processor for . Oracle XML Developer's Kit 10g Release 1 (10.1) xxxvii 1 Overview of XML Developer's Kit Components Introducing Oracle XML Developer's Kit. Command Line (putXML) 7-19 XSU OracleXML putXML Options 7-20 XSU Java API 7-21 Generating XML with XSU's OracleXMLQuery 7-21 Generating XML from SQL Queries