1 Introduction to Oracle XML Developer's Kit

This chapter contains the following topics:

Overview of Oracle XML Developer's Kit (XDK)
XDK Components
XML Document Generation with the XDK Components
Development Tools and Frameworks for the XDK
Installing the XDK

Overview of Oracle XML Developer's Kit (XDK)

Oracle Oracle XML Developer's Kit (XDK) is a versatile set of components that enables you to build and deploy C, C++, and Java software programs that process XML. You can assemble these components into an XML application that serves your business needs.

Note:

Customers using Oracle XDK with PL/SQL and migrating from Oracle Database Release 8.1 or 9.2 are strongly encouraged to use AL32UTF8 as the database character set. Otherwise, issues can arise during PL/SQL processing of XML data that contains escaped entities.

Oracle XDK provides the foundation for the Oracle XML solution. The XDK supports Oracle XML DB, which is a set of technologies used for storage and processing of XML in the database. You can use the XDK in conjunction with Oracle XML DB to build applications that run in Oracle Database. You can also use the XDK independently of XML DB.

XML Date Formatting

Dates and timestamps in generated XML are now in the formats specified by XML Schema. See Oracle Oracle XML DB Developer's Guide, Chapter "Generating XML Data from the Database", section "XMLELEMENT and XMLATTRIBUTES SQL Functions", subsection "Formatting of XML Dates and Timestamps".

The Oracle XDK is fully supported by Oracle and comes with a commercial redistribution license. The standard installation of Oracle Database includes the XDK.

Table 1-1 describes the XDK components, specifies which programming languages are supported, and directs you to sections that describe how to use the components.

Table 1-1 Overview of XDK Components

Component	Description	Lang.	Refer To
XML Parser	Creates and parses XML with industry standard DOM and SAX interfaces.	Java, C, C++	Chapter 4, "XML Parsing for Java" Chapter 18, "Using the XML Parser for C" Chapter 25, "Using the XML Parser for C++"
XML Compressor	Enables binary compression and decompression of XML documents. The compressor is built into the XML parser for Java.	Java	"Compressing XML"
Java API for XML Processing (JAXP)	Enables you to use SAX, DOM, XML Schema processor, XSLT processors, or alternative processors, from your Java program.	Java	"Parsing XML with JAXP"
XSLT Processor	Transforms XML into other text-based formats such as HTML.	Java, C, C++	Chapter 6, "Using the XSLT Processor for Java" Chapter 17, "Using the XSLT and XVM Processors for C" Chapter 26, "Using the XSLT Processor for C++"
XML Schema Processor	Validates schemas, allowing use of simple and complex XML datatypes.	Java, C, C++	Chapter 7, "Using the Schema Processor for Java" Chapter 20, "Using the XML Schema Processor for C" Chapter 27, "Using the XML Schema Processor for C++"
XML Class Generator	Generates Java or C++ classes from DTDs or XML schemas so that you can send XML data from Web forms or applications. The Java implementation supports Java Architecture for XML Binding (JAXB).	Java, C++	Chapter 8, "Using the JAXB Class Generator" and Chapter 29, "Using the XML Class Generator for C++"
XML Pipeline Processor	Applies XML processes specified in a declarative XML Pipeline document.	Java	Chapter 9, "Using the XML Pipeline Processor for Java"
XML JavaBeans	Provides a set of bean encapsulations of XDK components for ease of use of Integrated Development Environment (IDE), Java Server Pages (JSP), and applets.	Java	Chapter 10, "Using XDK JavaBeans"
XML SQL Utility (XSU)	Generates XML documents, DTDs, and Schemas from SQL queries. Maps any SQL query result to XML and vice versa. The XSU Java classes are mirrored by PL/SQL packages.	Java, PL/SQL	Chapter 11, "Using the XML SQL Utility (XSU)"
TransX Utility	Loads translated seed data and messages into the database using XML.	Java	Chapter 12, "Using the TransX Utility"
XSQL servlet	Combines XML, SQL, and XSLT in the server to deliver dynamic Web content.	Java	Chapter 14, "Using the XSQL Pages Publishing Framework"
Oracle SOAP Server	Provides a lightweight SOAP messaging protocol for sending and receiving requests and responses across the Internet.	C	Chapter 22, "Using SOAP with the C XDK"
XSLT Virtual Machine (XVM)	Provides a high-performance XSLT transformation engine that supports compiled stylesheets.	C, C++	"XVM Processor"

See Also:

Chapter 31, "XDK Standards" to learn about XDK support for XML-related standards
"XDK Components" for fuller descriptions of the components listed in Table 1-1

XDK Components

You can use the XDK components to perform various types of XML processing. For example, you can develop programs that do the following:

Parse XML
Validate XML against a DTD or XML schema
Transform an XML document into another XML document by applying an XSLT stylesheet
Generate Java and C++ classes from input XML schemas and DTDs

Figure 1-1 illustrates a hypothetical XML processor that performs the preceding tasks.

Figure 1-1 Sample XML Processor

Description of "Figure 1-1 Sample XML Processor"

The XDK contains components that you can use in your programs. This section describes the following XDK components, some of which are illustrated in Figure 1-1:

XML Parsers
XSLT Processors
XML Schema Processors
XML Class Generators
XSQL Pages Publishing Framework
XML Pipeline Processor
XDK JavaBeans
Oracle XML SQL Utility (XSU)
TransX Utility
Soap Services
XSLT Virtual Machine (XVM)

XML Parsers

An XML parser is a processor that reads an XML document and determines the structure and properties of the data. It breaks the data into parts and provides them to other components.

An XML processor can programmatically access the parsed XML data with the following APIs:

Use a SAX interface to serially access the data element by element. You can register event handlers with a SAX parser and invoke callback methods when certain events are encountered.Use DOM APIs to represent the XML document as an in-memory tree and manipulate or navigate it.

The XDK includes XML parsers for Java, C, and C++. Each parser includes support for both DOM and SAX APIs.

The XML parser for Java supports version 1.2 of JAXP, which is a standard API that enables use of DOM, SAX, XML Schema, and XSLT independently of a processor implementation. Thus, you can change the implementation of XML processors without impacting your programs.

The XML compressor is integrated into the XML parser for Java. It provides element-level XML compression and decompression with DOM and SAX interfaces. The compressor will compress XML documents without losing the structural and hierarchical information of the DOM tree. After parsing an XML document, you can serialize it with DOM or SAX to a binary stream and then reconstruct it later.

You can use the compressor to reduce the size of XML message payloads, thereby increasing throughput. When used within applications as the internal XML document access, it significantly reduces memory usage while maintaining fast access.

Figure 1-2 illustrates the functionality of the XDK parsers for Java, C, and C++.

Figure 1-2 The XML Parsers for Java, C, and C++

Description of "Figure 1-2 The XML Parsers for Java, C, and C++"

See Also:

XSLT Processors

eXtensible Stylesheet Language Transformation (XSLT) is a stylesheet language that enables processors to transform one XML document into another XML document. An XSLT document is a stylesheet that contains template rules that govern the transformation.

The Oracle XSLT processor fully supports the W3C XSL Transformations 1.0 recommendation. The processor also implements also implements the current working drafts of the XSLT and XPath 2.0 standards. It enables standards-based transformation of XML information inside and outside the database on any operating system.

The Oracle XML parsers include an integrated XSLT processor for transforming XML data by means of XSLT stylesheets. By using the XSLT processor, you can transform XML documents from XML to XML, to XHTML, or almost any other text format.

See Also:

"Using the XSLT Processor for Java: Overview".
Specifications and other information are found on the W3C site at http://www.w3.org/Style/XSL

XML Schema Processors

The XML Schema language was created by the W3C to describe the content and structure of XML documents in XML, thus improving on DTDs. An XML schema contains rules that define validity for an XML application. Unlike a DTD, an XML schema is itself written in XML. One of the principal advantages of an XML schema over a DTD is that a schema can specify rules for the content of elements and attributes. An XML schema specifies a set of built-in datatypes, for example, string, float, and date. Users can derive their own datatypes from the built-in datatypes. For example, the schema can restrict dates to those after the year 2000 or specify a list of legal values.

The Oracle XDK includes an XML Schema processor for Java, C, and C++.

See Also:

XML Class Generators

An XML class generator is a software program that accepts a parsed XML schema or DTD as input and generates Java or C++ source class files as output. The XDK includes both the JAXB class generator and the C++ class generator.JAXB is a Java API and set of tools that map to and from XML data and Java objects. Because JAXB presents an XML document to a Java program in a Java format, you can write programs that process XML data without having to use a SAX parser or write callback methods. Each object derives from an instance of the schema component in the input document. JAXB does not directly support DTDs, but you can convert a DTD to an XML schema that is usable by JAXB. The XML class generator for C++ supports both DTDs and XML Schemas.

As an example of how to use JAXB, you can write a Java program that uses generated Java classes to build XML documents gradually. Suppose that you write an XML schema for use by a human resources department and a Java program that responds to users who change their personal data. The program can use JAXB to construct an XML confirmation document in a piecemeal fashion, which an XSLT processor can transform into XHTML and deliver to a browser.

Figure 1-3 Oracle JAXB Class Generator

Description of "Figure 1-3 Oracle JAXB Class Generator"

See Also:

XML Pipeline Processor

The XML Pipeline Definition Language is an XML vocabulary for describing the processing relationships between XML resources. A document that is an instance of the pipeline language, that is, that defines the relationship between processes, is a pipeline document. For example, the document can specify that the program should first validate an input XML document and then, if it is valid, transform it.

Oracle XML Pipeline processor conforms to the XML Pipeline Definition Language 1.0 standard. The processor can take an input XML pipeline document and execute the pipeline processes according to the derived dependencies. The pipeline processor helps Java developers by replacing custom Java code with a simple declarative XML syntax for building XML processing applications.

XDK JavaBeans

JavaBeans is a Java API for developing reusable software components that can be manipulated visually in a builder tool. A JavaBean is a Java object that conforms to this API. The Oracle XDK JavaBeans are a collection of visual and non-visual beans that are useful in a variety of XML-enabled Java programs or applets. Table 1-2 summarizes the XDK JavaBeans.

Table 1-2 Summary of XDK JavaBeans

JavaBean	Description
DOMBuilder	Builds a DOM Tree from an XML document. This bean is nonvisual.
XSLTransformer	Accepts an XML file, applies the transformation specified by an input XSLT stylesheet and creates the resulting output file. This bean is nonvisual.
DBAccess	Maintains CLOB tables that contain multiple XML and text documents.
XMLDBAccess	Extends the DBAccess bean to support the XMLType column, in which XML documents are stored in an Oracle Database table.
XMLDiff	Compares two XML DOM trees.
XMLCompress	Encapsulates the XML compression functionality.
XSDValidator	Encapsulates the `oracle.xml.parser.schema.XSDValidator` class and adds capabilities for validating a DOM tree.

See Also:

Chapter 10, "Using XDK JavaBeans"

Oracle XML SQL Utility (XSU)

XSU is a set of Java class libraries that you can use to perform the following tasks:

Automatically and dynamically render the results of arbitrary SQL queries into canonical XML. XSU supports queries over richly-structured, user-defined object types and object views, including XMLType. When XSU transforms relational data into XML, the resulting XML document has the following structure:
- Columns are mapped to top-level elements.
- Scalar values are mapped to elements with text-only content.
- Object types are mapped to elements with attributes appearing as sub-elements.
- Collections are mapped to lists of elements.
Load data from an XML document into an existing database schema or view.

Note:

XSU also has a PL/SQL implementation. The DBMS_XMLQuery and DBMS_XMLSave PL/SQL packages reflect the functions in the OracleXMLQuery and OracleXMLSave Java classes.

Figure 1-4 illustrates how XSU processes SQL queries and returns the results as an XML document.

Figure 1-4 XSU Processes SQL Queries and Returns the Result as XML

Description of "Figure 1-4 XSU Processes SQL Queries and Returns the Result as XML"

Handling or Representing an XML Document

XSU can generate an XML document in any of the following ways:

A string representation of the XML document. Use this representation if you are returning the XML document to a requester. An in-memory DOM tree. Use this representation if you are operating on the XML programmatically, for example, transforming it with the XSLT processor by using DOM methods to search or modify the XML. A series of SAX events. You can use this functionality when retrieving XML, especially large documents or result sets.

Using XSU with an XML Class Generator

You can use XSU to generate an XML schema based on the relational schema of the underlying table or view that you are querying. You can use the generated XML schema as input to the JAXB class generator the C++ class generator. You can then write code that uses the generated classes to create the infrastructure behind a Web-based form. Based on this infrastructure, the form can capture user data and create an XML document compatible with the database schema. A program can write the XML directly to the corresponding table or object view without further processing.

TransX Utility

The Oracle TransX utility is a data transfer utility that enables you to populate a database with multilingual XML data. It uses a simple data format that is intuitive for both developers and translators and uses a validation capability that is less error-prone than previous techniques.How is the TransX utility different from XSU? TransX utility is an application of XSU that loads translated seed data and messages into a database schema. If you have data to be populated into a database in multiple languages, then the utility provides the functionality that you would otherwise need to develop with XSU.

See Also:

Chapter 12, "Using the TransX Utility"

XSQL Pages Publishing Framework

The XSQL pages publishing framework (XSQL servlet) is a server component that processes an XSQL file, which is an XML file with a specific structure and grammar, and produces dynamic XML documents from one or more SQL queries of data objects. Figure 1-5 shows you can invoke the XSQL servlet.

Figure 1-5 XSQL Pages Publishing Framework

This graphic is described in the surrounding text.

Description of "Figure 1-5 XSQL Pages Publishing Framework"

The XSQL servlet uses the Oracle XML parser to process the XSQL file, passing XSLT processing statements to its internal processor while passing parameters and SQL statements between the tags to XSU. Results from those queries are received as XML-formatted text or a JDBC ResultSet object. If necessary, you can further transform the query results by using the built-in XSLT processor.

One example of an XSQL servlet is a page that contains a query of flight schedules for an airline with a bind variable for the airport name. The user can pass an airport name as a parameter in a web form. The servlet binds the parameter value in its database query and transforms the output XML into HTML for display in a browser.

Soap Services

Simple Object Access Protocol (SOAP) is a platform-independent messaging protocol that enables programs to access services, objects, and servers. Oracle SOAP Services is published and executed through the Web and provides the standard XML message format for all programs. With SOAP Services, you can use the XDK to develop messaging, RPC, and Web service programs with XML standards.

See Also:

Chapter 22, "Using SOAP with the C XDK"

XSLT Virtual Machine (XVM)

The XVM for C/C++ is the software implementation of a CPU designed to run compiled XSLT code. To run this code, you need to compile XSLT stylesheets into byte code that the XVM engine understands. Figure 1-6 illustrates how the XVM processes XML and XSL.

Figure 1-6 XSLT Virtual Machine

Description of "Figure 1-6 XSLT Virtual Machine"

The XDK includes an XSLT compiler that is compliant with the XSLT 1.0 standard. The compilation can occur at runtime or be stored for runtime retrieval. Applications perform transformations more quickly with higher throughput because the stylesheet does not need to be parsed and the templates are applied based on an index lookup instead of an XML operation.

See Also:

"XVM Processor"

XML Document Generation with the XDK Components

The XDK enables you to map the structure of an XML document to a relational schema. You can use the XDK to establish a two-way path to an Oracle database in which your program creates XML documents from tables and inserts XML-tagged data into tables. Each XDK programming language supports the development of programs that generate XML documents from relational data.

This section contains the following topics:

XML Document Generation with Java
XML Document Generation with C
XML Document Generation with C++

XML Document Generation with Java

As shown in Figure 1-7, you can execute a SQL query against the database in three different ways. Table 1-3 describes the alternatives.

Table 1-3 Generating XML in Java

Technology	Label in Figure 1-7	Description
XSQL Servlet	A	Includes XSU and the XML parser
XSU	B	Includes XML parser
JDBC	C	Sends output data to the XML parser

Figure 1-7 Sample XML Processor Built with Java XDK Components

Description of "Figure 1-7 Sample XML Processor Built with Java XDK Components"

Regardless of how your software program generates the XML from the database, Figure 1-7 illustrates possible further processing that your program can perform on the XML document. Table 1-4 describes some of the components that you can use to perform this additional processing.

Table 1-4 Additional Document Processing with the Java XDK

Technology	Label in Figure 1-7	Description
JAXB	D	Generates Java class files that correspond to an input XML Schema
JavaBeans	E	Can compare an XML document with another XML document
XSLT	F	Transforms the XML document into XHTML with an XSLT stylesheet

XML Document Generation with C

Figure 1-8 illustrates the Oracle XDK C language components that you can use to generate XML documents from relational data. The XDK C components are listed in Table 1-1.

Figure 1-8 Generating XML Documents with XDK C Components

Description of "Figure 1-8 Generating XML Documents with XDK C Components"

As illustrated in Figure 1-8, you can use the XDK to develop a C program that processes an XML document as follows:

Send SQL queries to the database by the Oracle Call Interface (OCI) or the Pro*C/C++ Precompiler. The program must leverage the XML DB XML view functionality.
Process the resulting XML data with the XML parser or from the CLOB as an XML document.
Transform the document with the XSLT processor, send it to an XML-enabled browser, or send it for further processing to a software program.

XML Document Generation with C++

Figure 1-9 shows the Oracle XDK C++ components that you can use to generate XML documents. The XDK C++ components are listed in Table 1-1.

Figure 1-9 Generating XML Documents Using XDK C++ Components

Description of "Figure 1-9 Generating XML Documents Using XDK C++ Components"

As illustrated in Figure 1-9, you can use the XDK to develop a C++ program that processes an XML document as follows:

Send SQL queries to the database by the Oracle C++ Call Interface (OCCI) or the Pro*C/C++ Precompiler.
Process the resulting XML data with the XML parser or from the CLOB as an XML document.
Transform the document with the XSLT processor, send it to an XML-enabled browser, or send it for further processing to a software program.

Development Tools and Frameworks for the XDK

Figure 1-10 illustrates some of the tools and frameworks that you can use to develop software programs that use XDK components. For example, you can use Oracle JDeveloper to write a Java client that can query the database, generate XML, and perform additional processing. An employee can then use this program to send a query to an Oracle database. The program can transfer XML documents to XML-based business solutions for data exchange with other users, content and data management, and so forth.

Figure 1-10 XDK Tools and Frameworks

Description of "Figure 1-10 XDK Tools and Frameworks"

This section describes some of the tools and frameworks that you can use in e-business development:

Oracle JDeveloper
User Interface XML (UIX)
Oracle Reports
Oracle XML Gateway
Oracle Data Provider for .NET

Oracle JDeveloper

Oracle JDeveloper is a J2EE development environment with end-to-end support for developing, debugging, and deploying e-business applications. JDeveloper provides a comprehensive set of integrated tools that support the complete development life cycle, from source code control, modeling, and coding through debugging, testing, profiling, and deployment. JDeveloper simplifies development by providing deployment tools to create J2EE components such as the following:

Applets
JavaBeans
Java Server Pages (JSP)
Servlets
Enterprise JavaBeans (EJB)

JDeveloper also provides a public API to extend and customize the development environment and integrate it with external products.

The Oracle XDK is integrated into JDeveloper, offering many ways to manage XML. For example, you can use the XSQL Servlet to perform the following tasks:

Query and manipulate database information
Generate XML documents
Transform XML with XSLT stylesheets
Deliver XML on the Web

JDeveloper has an integrated XML schema-driven code editor for working on XML Schema-based documents such as XML schemas and XSLT stylesheets. By specifying the schema for a certain language, the editor can assist you in creating a document in that markup language. You can use the Code Insight feature to provide a list of valid alternatives for XML elements or attributes in the document.

Oracle JDeveloper simplifies the task of working with Java application code and XML data and documents at the same time. It features drag-and-drop XML development modules such as the following:

Color-coded syntax highlighting for XML
Built-in syntax checking for XML and XSL
Editing support for XML schema documents
XSQL Pages and Servlet support
Oracle's XML parser for Java
XSLT processor
XDK for JavaBeans components
XSQL Page Wizard
XSQL Action Handlers
Schema-driven XML editor

See Also:

http://www.oracle.com/technetwork/developer-tools/jdev/overview/index.html for more information about JDeveloper

User Interface XML (UIX)

UIX (User Interface XML) is a framework for developing XML-enabled Web applications. The main focus of UIX is the user presentation layer of a program, with additional functionality for managing events and application flow. You can use UIX to create programs with page-based navigation, such as an online human resources program, rather than full-featured programs requiring advanced interaction, such as an integrated development environment (IDE).

See Also:

http://www.oracle.com/technetwork/developer-tools/jdev/viewlet-097827.html for sample JDeveloper Demonstration code
JDeveloper online help for the complete UIX Developer's Guide

Oracle Reports

Oracle Reports Developer and Reports Server is a development tool that enables you to build and publish dynamically generated Web reports. A wizard expedites the use of each major task. Report templates and live data previews allow you to customize the report structure. You can publish reports throughout the enterprise through a standard Web browser in formats such as the following:

XML
HTML with or without CSS
PDF
Text
RTF
PostScript
PCL

See Also:

http://www.oracle.com/technetwork/middleware/reports/overview/index.html for information about Oracle Reports

Oracle XML Gateway

Oracle XML Gateway is a set of services that enables integration with the Oracle E-Business Suite to create and consume XML messages triggered by business events. It integrates with Oracle Streams Advanced Queuing to enqueue and dequeue a message, which it can then transmit to or from the business partner through any message transport agent.

See Also:

Oracle Data Provider for .NET

Oracle Data Provider for .NET (ODP.NET) is an implementation of a data provider for the Oracle Database. ODP.NET uses Oracle native APIs to offer fast and reliable access to Oracle data and features from any .NET application and also uses and inherits classes and interfaces available in the Microsoft .NET Framework Class Library.

You can use ODP.NET and the XDK to extract data from relational and object-relational tables and views as XML documents. The use of XML documents for insert, update, and delete operations to the database server is also allowed. ODP.NET supports XML natively in the database through XML DB.

ODP.NET supports XML with features that:

Store XML data natively in the database server as the Oracle native type XMLType.
Access relational and object-relational data as XML data from an Oracle Database instance into Microsoft .NET environment and process the XML with the Microsoft .NET framework.
Save changes to the database server with XML data.

For the .NET application developer, features include the following:

Enhancements to the OracleCommand, OracleConnection, and OracleDataReader classes
XML-specific classes:
- OracleXmlType
- OracleXmlStream
- OracleXmlQueryProperties
- OracleXmlSaveProperties

Installing the XDK

This section assumes that you installed Oracle Database from either CD-ROM or from an archive downloaded from Oracle Technology Network (OTN). The Oracle Database CD installs the Oracle XDK by default. Note that you must install the demo programs from the Oracle Database Examples media to obtain the XDK demos. This manual presumes that you have access to the XDK demos programs.

After installing Oracle Database and the demos from the Oracle database Examples media, your Oracle Database home should be set up as follows:

- Oracle_home_directory
   | - bin: includes XDK executables
   | - lib: includes XDK libraries
   | - jlib: includes Globalization Support libraries for the XDK
   | - nls: includes binary files used as part of globalization support
   | - xdk: XDK scripts, message files, documentation, and demos
        readme.html
        | - admin: SQL scripts and XSL Servlet Configuration
                    file (XSQLConfig.xml)
        | - demo: sample programs (installed from Oracle Database Examples media)
             | - c
             | - cpp
             | - java
             | - jsp
        | - doc: release notes and readme
             content.html
             index.html
             license.html
             title.html
              | - cpp
              | - images
              | - java
        | - include: header files
        | - mesg: error message files

The directory that contains the XDK is called the XDK home. Set the $XDK_HOME environment variable (UNIX) or the %XDK_HOME% variable (Windows) to the XDK directory in your Oracle home. For example, you can set use csh on UNIX to set the XDK home as follows:

setenv XDK_HOME $ORACLE_HOME/xdk

See Also: