Skip Headers

Oracle® Application Developer's Guide - XML 10g (9.0.4) Part Number B12099-01 |
Home | Contents | Index

#
Preface

The Preface has the following sections:

- About this Guide

- Audience

- Feature Coverage and Availability

- How this Manual is Organized

- Related Documentation

- How to Order this Manual

- Downloading Release Notes, Installation Guides, White Papers,...

- How to Access this Manual On-Line

- Conventions

- Documentation Accessibility

## About this Guide

This manual describes Oracle XML-enabled database technology. It describes how XML data can be stored, managed, and queried in the database using Oracle XML-enabled technology and the appropriate Oracle development tools.

After introducing you to the main criteria to consider when designing your Oracle XML application, this manual describes an overview of several scenarios that are based on real-life existing business applications. You are then introduced to the XML Developer's Kits (XDKs) and how the XDK componoents can work together to generate and store XML data in a database. Examples and sample applications are introduced where possible.

#### Examples and Sample Code

Many of the XDK examples in the manual are provided with your software in the following directories:

- `$ORACLE_HOME/xdk/java/demo/`

- `$ORACLE_HOME/xdk/C/demo/, and so on`

- `$ORACLE_HOME/xdk/java/sample/`

- `$ORACLE_HOME/rdbms/demo directory`

#### Composed or Decomposed (Generated) XML

In general, XML documents are processed in one of two ways:

- As composed XML documents, stored in LOBs

- As decomposed XML document fragments, stored in relational tables, with the XML tags mapped to their respective columns in the database tables. The decomposed or fragmented XML documents can then be regenerated into composed XML documents

#### Oracle XML-Enabled Technology

The main Oracle XML-enabled technology components are the XML Developer's Kits (XDKs). These are available in four language implementations:

- Java. XDK for Java, XDK for Javabeans, and XML SQL Utility for Java

- PL/SQL. XDK for PL/SQL and XML SQL Utility for PL/SQL

- C. XDK for C

- C++. XDK for C++

## Audience

This guide is intended for developers building XML applications on Oracle Database or Oracle Application Server (OracleAS).

#### Prerequisite Knowledge

An understanding of XML and XSL is helpful but not essential for using this manual. References to good sources for more information are included in Appendix A and in the FAQ section of Chapter 3. An XML primer is included in Appendix A.

Many examples provided here are in either SQL, Java, PL/SQL, C, or C++, hence a working knowledge of one or more of these languages is presumed.

##### If you understand XML but know nothing about databases...

The best place for you to start is:

1. Read Oracle9i Concepts.. First plan, model, and design your database.

2. Read the chapters in Part I, "Introducing Oracle XML-Enabled Technology" and Part II, "Storing and Retrieving XML From the Database".

3. Visit Oracle Technology Network (OTN) sites at:

   - http://otn.oracle.com for general information about database features

   - http://otn.oracle.com/tech/xml for information about the XML Developer's Kits (XDKs) available as well as white papers and demos.

4. Check the Frequently Asked Questions (FAQ) sections in this manual, starting with those at the end of:

   - Chapter 3 -- "Frequently Asked Questions (FAQs): Oracle XML-Enabled Technology"

   - Chapter 7 -- "Frequently Asked Questions (FAQs): XML SQL Utility (XSU)"

   - Chapter 8 -- "Frequently Asked Questions (FAQs): Oracle Text"

   - Chapter 10 -- "Frequently Asked Questions (FAQs) - XSQL Servlet"

   - Chapter 20 -- "Frequently Asked Questions (FAQs): XML Parser for Java"

5. If you still have questions, consult with your Oracle representative or, to help get you started, go to the "Discussions" option on OTN and post your question there.

6. Of course, once you have determined which language you need for your application and which XDK components you need to build your application, for detail on the XML components and how they are used, see:

   - Chapter 7, Chapter 10, and Part IV -- Tools and Frameworks for Building Oracle-Based XML Applications through Part X -- XDK for PL/SQL, of this manual.

   - Oracle9i XML Reference

##### If you understand databases but know nothing about XML...

The best place for you to start is:

1. Read Appendix A, "An XML Primer" and the references at the end of Chapter 3, "Oracle XML Developer Kits (XDKs) and Components: Overview and General FAQs". There are many good books and web sites that introduce you to XML. Some of these are listed in Appendix A.

2. Read Chapter 4, "Using XSL and XSLT".

3. Read the FAQs at the end of the chapters, starting with:

   - Chapter 3 -- "Frequently Asked Questions (FAQs): Oracle XML-Enabled Technology"

   - Chapter 7 -- "Frequently Asked Questions (FAQs): XML SQL Utility (XSU)"

   - Chapter 8 -- "Frequently Asked Questions (FAQs): Oracle Text"

   - Chapter 10 -- "Frequently Asked Questions (FAQs) - XSQL Servlet"

   - Chapter 20 -- "Frequently Asked Questions (FAQs): XML Parser for Java"

4. Of course you need to read about the (new) native XML support in Oracle Databse, so read the chapters in Part I, "Introducing Oracle XML-Enabled Technology" and Part II, "Storing and Retrieving XML From the Database".

5. Visit the Oracle Technology Network (OTN) XML site at http://otn.oracle.com/tech/xml for information about the XML Developer Kits (XDKs) available as well as white papers and demos.

6. Of course, once you have determined which language you need for your application and which XDK components you need to build your application, for detail on the XML components and how they are used, see:

   - Chapter 7, Chapter 10, and Part IV -- Tools and Frameworks for Building Oracle-Based XML Applications through Part X -- XDK for PL/SQL, of this manual.

   - Oracle9i XML Reference

7. If you still have questions, consult with your Oracle representative or, to help get you started, go to the "Discussions" option on OTN and post your question there.

## Feature Coverage and Availability

Information in this manual represents a snapshot of information on Oracle XML-enabled technology components. These change rapidly. To view the latest information, refer to Oracle Technology Network (OTN) at: http://otn.oracle.com/tech/xml

## How this Manual is Organized

This manual is organized into 10 parts, 29 chapters, and 8 appendixes. It includes an index and glossary.

#### Roadmap of this Manual

A detailed version of this diagram is provided in Chapter 1, "Oracle XML-Enabled Technology".

- Introducing XML and the Oracle Database. Introductory and basic information about using Oracle Database XML components (Chapters 1 through 8), XML support in the database, using XMLType and URI-Reference, XML SQL Utility (XSU), and how to apply Oracle Text to search and retrieve information from XML documents.

  - PART 1 "Introducing Oracle XML-Enabled Technology"

    - Chapter 1, "Oracle XML-Enabled Technology", introduces you to Oracle XML Developer Kits (XDKs), the (new) native XML support in the database and XMLType and DBUri-ref, tools used to build XML applications, and Oracle Text (interMedia Text).

    - Chapter 2, "Modeling and Design Issues for Oracle XML Applications", describes some XML design and loading issues, and how Oracle XML components can be used in typical content/document management and business-to-business messaging applications.

    - Chapter 3, "Oracle XML Developer Kits (XDKs) and Components: Overview and General FAQs", introduces you to the Oracle XML components, the XML Development Kits and XML SQL Utility. It summarizes the ways you can generate XML documents for each language, Java, C, C++, and PL/SQL. It provides Frequently Asked Questions (FAQs) about Oracle's XML-enabled technology.

    - Chapter 4, "Using XSL and XSLT", introduces you to XML and XSLT. It also discusses the differences between Cascading Style Sheets (CSS) and XSL. This chapter includes Frequently Asked Questions.

  - PART II "Storing and Retrieving XML From the Database"

    - Chapter 5, "Database Support for XML", introduces the (new) datatype `XMLType` and describes how to use `XMLType` when generating and storing XML in the database. This chapter also describes the `extract()` and `existsnode()` functions and member functions, `DBMS_XMLGEN` package, `SYS_XMLGEN` function used to generate XML in SQL queries, `SYS_XMLAGG` function used to aggregate XML data, creating and managing XMLTypes, and using functional indexes and table functions to query XML.

    - Chapter 6, "Database Uri-references", describes Uri-Reference (Uri-ref), and DBUri-ref, how to use`URIType` and subtypes, `DBUriType` and`HttpUriType,` the new`SYS_DBURIGEN()` operator, `URIFactory` Method, HTTP access to objects and the `OraDBUriServlet` mechanism.

    - Chapter 7, "XML SQL Utility (XSU)", describes how to use XML SQL Utility Java and PL/SQL APIs, to generate and 'store' XML documents, how to insert, update, and delete XML documents in the database, use the XSU command line tool, and map elements to columns. Examples in this chapter are also available from `$ORACLE_HOME/rdbms/demo/xsu`. This chapter also provides Frequently Asked Questions (FAQs).

    - Chapter 8, "Searching XML Data with Oracle Text", introduces you to Oracle Text (interMedia Text), using the CONTAINS operator, how to create an Oracle Text section and index, and how to build queries. It includes examples and guidelines on using XML_SECTION_GROUP, AUTO_SECTION_GROUP, the new PATH_SECTION_GROUP, the INPATH and HASPATH operators. This chapter also provides Frequently Asked Questions (FAQs).

- B2B and XML Data Exchange.

  - Part III. "Data Exchange Using XML"

    - Chapter 9, "Exchanging XML Data Using Oracle AQ", introduces you to some Advanced Queueing (AQ) concepts and describes how AQ and XML complement each other. This chapter also describes the (new) Internet-Data-Access-Presentation (IDAP) mechanism, the `AQXMLServlet` and accessing it with HTTP and SMTP. It also describes `XMLType` Queues and XML AQ message transformation. This chapter provides several FAQs.

- Oracle Development Tools. Chapters 10 through 17 describes either introductory information or how to use XSQL Pages Publishing Framework, JDeveloper, Business Components for Java (BC4J), the (new) Metadata API, Oracle Reports, Oracle Portal, Oracle Exchange, and XML Gateway.

  - PART IV "Tools and Frameworks for Building Oracle-Based XML Applications"

    - Chapter 10, "XSQL Pages Publishing Framework", provides some insight on using XSQL Servlet. It includes diagrams that explain how the XSQL Page Processor works.This chapter includes FAQs.

    - Chapter 11, "Using JDeveloper to Build Oracle XML Applications", introduces you using JDeveloper for building XML applications, using XSQL servlet from JDeveloper, and steps to take when about building a Mobile application with JDeveloper. This chapter includes FAQs.

    - Chapter 12, "Building BC4J and XML Applications", introduces you to Business Components for Java (BC4J) and how to use the BC4J framework to build XML applications.

    - Chapter 13, "Using Metadata API", describes the Metadata API and how to use it. It includes a description of the (new) `DBMS_METADATA`'s programmatic and browsing interfaces, as well as a detailed example.

    - Chapter 14, "OracleAS Reports Services and XML", describes how to generate and customize reports Reports as XML and read XML data source from reports. It includes information about using (new) pluggable XML data sources, XML-PDS, and their support for XSQL.

    - Chapter 15, "Using the PDK for Visualizing XML Data in Oracle Portal", briefly describes the Oracle Application Server Portal features, Portal Developer Kit (PDK) and how you can use URL Services to enable you use your XML application as a web or database-based portlet.

    - Chapter 16, "How Oracle Exchange Uses XML" introduces you to Oracle Exchange, its stored and pass through transactions, XML delivery formats, and e-business solution architecture.

    - Chapter 17, "Introducing Oracle XML Gateway" -- introduces you to Oracle XML Gateway. Oracle XML Gateway is a set of services that allows for easy integration with the Oracle e-Business Suite to create and consume XML messages triggered by business events.

- PART V "OracleAS Dynamic Services (DS) and Oracle Syndication Server (OSS)"

  - Chapter 18, "Using OracleAS Dynamic Services and XML", introduces you to OracleAS Dynamic Services, its architecture, Java, PL/SQL, and JMS/HTTP deployment modes, and developing Dynamic Services services.

  - Chapter 19, "Oracle Syndication Server (OSS) and XML", provides an overview of Oracle Syndication Server (OSS), its use of the ICE protocol, OSS architecture, and how OSS interfaces with Oracle Dynamic Services, content providers, and subscribers.

- XML Developer Kits (XDKs). The roadmap shows the various XML Developer Kits (XDKs), in the "XML Application" box. Chapter 7, and 19 through 29 describe how to use the XDKs.

  - Part VI "XDK for Java"

    - Chapter 20, "Using XML Parser for Java", describes ways of using XML Parser for Java and XSLT Processor. It lists the examples provided with the software. This chapter includes FAQs.

    - Chapter 21, "Using XML Schema Processor for Java", introduces you to XML Schema, compares XML Schema to DTDs, and describes Oracle XML Schema Processor Java features, usage, how to use the sample program. It also provides FAQs.

    - Chapter 22, "XML Class Generator for Java", describes ways of using XML Java Class Generator with DTDs and XML Schema. It lists the examples provided with the software. This chapter includes FAQs.

  - Part VII "XDK for Java Beans"

    - Chapter 23, "Using XML Transviewer Beans", discusses the XML Transviewer Beans and how to use them, including the (new) DBViewer bean and (new) DBAccess bean. It lists examples provided with your software.

  - Part VIII "XDK for C"

    - Chapter 24, "Using XML Parser for C", describes ways of using XML Parser for C and XSLT Processor. It lists the examples provided with the software.

    - Chapter 25, "Using XML Schema Processor for C", describes the XML Schema Process for C features, calling sequence, and how to run the supplied sample programs. This chapter also lists the supplied examples.

  - Part IX "XDK for C++"

    - Chapter 26, "Using XML Parser for C++", describes ways of using XML Parser for C++ and XSLT Processor. It lists the examples provided with the software.

    - Chapter 27, "Using XML Schema Processor for C++", describes the XML Schema Process for C++ features, calling sequence, and how to run the supplied sample programs. This chapter also lists the supplied example.

    - Chapter 28, "Using XML C++ Class Generator", describes ways of using XML C++ Class Generator. It lists the examples provided with the software.

  - Part X "XDK for PL/SQL"

    - Chapter 29, "Using XML Parser for PL/SQL", describes ways of using XML Parser for PL/SQL and XSLT Processor. It lists the examples provided with the software. This chapter includes FAQs.

Not shown in the roadmap are the Appendixes which include the XML Primer, and XDK cheat sheets and specifications.

- Appendix A, "An XML Primer", introduces you to some basic and background information about XML.

- Appendix B, "Comparing Oracle XML Parsers and Class Generators by Language", compares the Oracle XML Parsers and Class Generators according to implementation language.

- Appendix C, "XDK for Java: Specifications and Cheat Sheets", describes the XDK for Java component specifications. Includes several top level class and method listings.

- Appendix D, "XDK for Java Beans: Specifications and Cheat Sheets", describes the XDK for Java Beans, specifically the Transviewer Beans cheatsheets.

- Appendix E, "XDK for C: Specifications and Cheat Sheets", describes the XDK for C specifications. Includes top level function listings.

- Appendix F, "XDK for C++: Specifications and Cheat Sheet", describes the XDK for C++ component specifications. Includes several top level class and method listings.

- Appendix G, "XDK for PL/SQL: Specifications and Cheat Sheets", describes the XDK for PL/SQL specifications. Includes several top level function listings.

- Appendix H, "XML SQL Utility (XSU) Specifications and Cheat Sheets", describes the XML SQL Utility (XSU) for Java and PL/SQL specifications. Includes several top level method and function listings.

## Related Documentation

For more information, see these Oracle resources:

- Oracle9i New Features for information about the differences between Oracle9i and the Oracle9i Enterprise Edition and the available features and options. That book also describes all the features that are new in Oracle9i.

- Oracle9i Concepts.

- The JDeveloper Guide

- Oracle9i Application Developer's Guide - Fundamentals

- Oracle8i Application Developer's Guide - Advanced Queuing

- Oracle9i Supplied PL/SQL Packages Reference

- Oracle Integration Server Overview

- Oracle9i XML Reference

- The Oracle XML Handbook, XML Core Development Team, Oracle., Oracle Press

- Building Oracle XML Applications, Steve Muench, O'Reilly

- XML Bible, Elliotte Rusty Harold, IDG Books Worldwide

- XML Unleashed, Morrison et al., SAMS

- Building XML Applications, St.Laurent and Cerami, McGraw-Hill

- Building Web Sites with XML, Michael Floyd, Prentice Hall PTR

- Building Corporate Portals with XML, Finkelstein and Aiken, McGraw-Hill

- XML in a Nutshell, O'Reilly

- Learning XML - (Guide to) Creating Self-Describing Data, Ray, O'Reilly

- http://www.xml.com/pub/rg/46

- http://www.xmlmag.com/

- http://www.webmethods.com/

- http://www.clarient.org/

- http://www.xmlwriter.com/

- http://webdevelopersjournal.com/articles/why_xml.html

- http://www.w3schools.com/xml/

- http://www.w3.org/TR/REC-xml

## How to Order this Manual

Customers in Europe, the Middle East, and Africa (EMEA) can purchase documentation from:

    http://www.oraclebookshop.com/

Other customers can contact their Oracle representative to purchase printed documentation.

To download free release notes, installation documentation, white papers, or other collateral, please visit the Oracle Technology Network (OTN). You must register online before using OTN; registration is free and can be done at

    http://otn.oracle.com/membership/index.htm

If you already have a username and password for OTN, then you can go directly to the documentation section of the OTN Web site at

    http://otn.oracle.com/docs/index.htm

## Downloading Release Notes, Installation Guides, White Papers,...

To download free release notes, installation documentation, white papers, or other collateral, please visit the Oracle Technology Network (OTN). You must register online before using OTN; registration is free and can be done at

    http://otn.oracle.com/membership/index.htm

If you already have a username and password for OTN, then you can go directly to the documentation section of the OTN Web site at

    http://otn.oracle.com/docs/index.htm

## How to Access this Manual On-Line

You can find copies of or download this manual from any of the following locations:

- On the Document CD that accompanies your Oracle Databse software CD

- From Oracle Technology Network (OTN) at http://otn.oracle.com/docs/index.htm, under Data Server (or whatever other product you have). For example, select Oracle9i > General Documentation Release 1 (9.0.1) (or whatever other section you need to specify). Select HTML then select HTML or PDF for your particular of interest, such as, "Oracle Documentation Library". Note that you may only be able to locate the prior release manuals at this site.

## Conventions

This section describes the conventions used in the text and code examples of this documentation set. It describes:

- Conventions in Text

- Conventions in Code Examples

#### Conventions in Text

We use various conventions in text to help you more quickly identify special terms. The following table describes those conventions and provides examples of their use.

Convention | Meaning | Example
--- | --- | ---
Bold | Bold typeface indicates terms that are defined in the text or terms that appear in a glossary, or both. | When you specify this clause, you create an index-organized table.
Italics | Italic typeface indicates book titles or emphasis. | Oracle9i Concepts Ensure that the recovery catalog and target database do not reside on the same disk.
`UPPERCASE monospace (fixed-width font)` | Uppercase monospace typeface indicates elements supplied by the system. Such elements include parameters, privileges, datatypes, RMAN keywords, SQL keywords, SQL*Plus or utility commands, packages and methods, as well as system-supplied column names, database objects and structures, usernames, and roles. | You can specify this clause only for a `NUMBER` column. You can back up the database by using the `BACKUP` command. Query the `TABLE_NAME` column in the `USER_TABLES` data dictionary view. Use the `DBMS_STATS`.`GENERATE_STATS` procedure.
`lowercase monospace (fixed-width font)` | Lowercase monospace typeface indicates executables, filenames, directory names, and sample user-supplied elements. Such elements include computer and database names, net service names, and connect identifiers, as well as user-supplied database objects and structures, column names, packages and classes, usernames and roles, program units, and parameter values. Note: Some programmatic elements use a mixture of UPPERCASE and lowercase. Enter these elements as shown. | Enter `sqlplus` to open SQL*Plus. The password is specified in the `orapwd` file. Back up the datafiles and control files in the `/disk1/oracle/dbs` directory. The `department_id`, `department_name`, and `location_id` columns are in the `hr.departments` table. Set the `QUERY_REWRITE_ENABLED` initialization parameter to `true.` Connect as `oe` user. The `JRepUtil` class implements these methods.
`lowercase monospace (fixed-width font) italic` | Lowercase monospace italic font represents placeholders or variables. | You can specify the `parallel_clause`. Run `U` `old_release``.SQL` where `old_release` refers to the release you installed prior to upgrading.

#### Conventions in Code Examples

Code examples illustrate SQL, PL/SQL, SQL*Plus, or other command-line statements. They are displayed in a monospaced (fixed-width) font and separated from normal text as shown in this example:

    SELECT username FROM dba_users WHERE username = 'MIGRATE';

The following table describes typographic conventions used in code examples and provides examples of their use.

Convention | Meaning | Example
--- | --- | ---
[ ] | Brackets enclose one or more optional items. Do not enter the brackets. | `DECIMAL (``digits``[ ,` `precision``])`
{ } | Braces enclose two or more items, one of which is required. Do not enter the braces. | `{ENABLE | DISABLE}`
| | A vertical bar represents a choice of two or more options within brackets or braces. Enter one of the options. Do not enter the vertical bar. | `{ENABLE | DISABLE}` `[COMPRESS | NOCOMPRESS]`
`...` | Horizontal ellipsis points indicate either: That we have omitted parts of the code that are not directly related to the example That you can repeat a portion of the code | `` `CREATE TABLE ... AS` `subquery``;` `SELECT` `col1``,` `col2``, ... ,` `coln` `FROM employees;`
. . . | Vertical ellipsis points indicate that we have omitted several lines of code not directly related to the example. | ``
Other notation | You must enter symbols other than brackets, braces, vertical bars, and ellipsis points as shown. | `acctbal NUMBER(11,2);` `acct CONSTANT NUMBER(4) := 3;`
`Italics` | Italicized text indicates placeholders or variables for which you must supply particular values. | `CONNECT SYSTEM/``system_password` `DB_NAME =` `database_name`
`UPPERCASE` | Uppercase typeface indicates elements supplied by the system. We show these terms in uppercase in order to distinguish them from terms you define. Unless terms appear in brackets, enter them in the order and with the spelling shown. However, because these terms are not case sensitive, you can enter them in lowercase. | `SELECT last_name, employee_id FROM employees;` `SELECT * FROM USER_TABLES;` `DROP TABLE hr.employees;`
`lowercase` | Lowercase typeface indicates programmatic elements that you supply. For example, lowercase indicates names of tables, columns, or files. Note: Some programmatic elements use a mixture of UPPERCASE and lowercase. Enter these elements as shown. | `SELECT last_name, employee_id FROM employees;` `sqlplus hr/hr` `CREATE USER mjones IDENTIFIED BY ty3MU9;`

## Documentation Accessibility

Our goal is to make Oracle products, services, and supporting documentation accessible, with good usability, to the disabled community. To that end, our documentation includes features that make information available to users of assistive technology. This documentation is available in HTML format, and contains markup to facilitate access by the disabled community. Standards will continue to evolve over time, and Oracle Corporation is actively engaged with other market-leading technology vendors to address technical obstacles so that our documentation can be accessible to all of our customers. For additional information, visit the Oracle Accessibility Program Web site at

    http://www.oracle.com/accessibility/

##### Accessibility of Code Examples in Documentation

JAWS, a Windows screen reader, may not always correctly read the code examples in this document. The conventions for writing code require that closing braces should appear on an otherwise empty line; however, JAWS may not always read a line of text that consists solely of a bracket or brace.

##### Accessibility of Links to External Web Sites in Documentation

This documentation may contain links to Web sites of other companies or organizations that Oracle Corporation does not own or control. Oracle Corporation neither evaluates nor makes any representations regarding the accessibility of these Web sites.

| Copyright © 2001, 2003 Oracle Corporation. All Rights Reserved. |
Home | Contents | Index