Skip Headers

Oracle® XML Developer's Kit Programmer's Guide 10g Release 2 (10.1.2) Part No. B14033-01 |
| Contents | Index

Previous | Next |

# 10 XDK JavaBeans

This chapter contains these topics:

- Accessing Oracle XDK JavaBeans

- DOMBuilder JavaBean

- XSLTransformer JavaBean

- DBAccess JavaBean

- XMLDiff JavaBean

- XMLCompress JavaBean

- XMLDBAccess JavaBean

- XSDValidator JavaBean

- JavaBean Examples

## Accessing Oracle XDK JavaBeans

The Oracle XDK JavaBeans are provided as part of XDK with the Enterprise and Standard Editions.

The following new JavaBeans were added in release 10.1:

- `XSDValidator` - encapsulates `oracle.xml.parser.schema.XSDValidator` class and adds capabilities for validating a DOM tree.

- `XMLCompress` - encapsulates XML compression functionality.

- `XMLDBAccess` - extension of `DBAccess` JavaBean to support the `XMLType` column in which XML documents are stored in an Oracle database table.

XDK JavaBeans facilitate the addition of graphical interfaces to your XML applications.

Bean encapsulation includes documentation and descriptors that can be accessed directly from Java Integrated Development Environments like JDeveloper.

See Also: Oracle XML API Reference contains listings of the methods in all the JavaBeans.

### Database Connectivity

Database Connectivity is included with the XDK JavaBeans. The beans can now connect directly to a JDBC-enabled database to retrieve and store XML and XSL files.

### XDK JavaBeans Overview

XDK JavaBeans comprises the following beans:

#### DOMBuilder

The `DOMBuilder` JavaBean is a non-visual bean. It builds a DOM Tree from an XML document.

The `DOMBuilder` JavaBean encapsulates the XML Parser for Java's `DOMParser` class with a bean interface and extends its functionality to permit asynchronous parsing. By registering a listener, Java applications can parse large or successive documents and then allow control to return immediately to the caller.

See Also: "DOMBuilder JavaBean"

#### XSLTransformer

The `XSLTransformer` JavaBean is a non-visual bean. It accepts an XML file, applies the transformation specified by an input XSL stylesheet and creates the resulting output file.

`XSLTransformer` JavaBean enables you to transform an XML document to almost any text-based format including XML, HTML, and DDL, by applying the appropriate XSL stylesheet.

- When integrated with other beans, XSLTransformer JavaBean enables an application or user to view the results of transformations immediately.

- This bean can also be used as the basis of a server-side application or servlet to render an XML document, such as an XML representation of a query result, into HTML for display in a browser.

  See Also: "XSLTransformer JavaBean"

#### DBAccess

DBAccess JavaBean maintains `CLOB` tables that contain multiple XML and text documents.

#### XMLDiff

The `XMLDiff` JavaBean performs a tree comparison on two XML DOM trees. It displays the two XML DOM trees and shows the differences between the XML trees. A node can be inserted, deleted, moved, or modified. Each of these operations is shown in a different color or style.

#### XMLCompress

This JavaBean is an encapsulation of the XML compression functionality. The supported functions are compression of the internal DOM tree obtained by means of a DOMParser, compression of the SAX events thrown by the SAX parser, and un-compression of the serialized XML data, returning an `XMLDocument` object.

#### XMLDBAccess

This JavaBean is an extension of the `DBAcess` bean to support the XMLType column, in which XML documents are stored in an Oracle database table. Methods are provided to list, delete, or retrieve `XMLType` instances and their tables.

#### XSDValidator

This JavaBean is a class file that encapsulates the `oracle.xml.parser.schema.XSDValidator` class and adds capabilities for validating a DOM tree.

## DOMBuilder JavaBean

`DOMBuilder` class implements an XML 1.0 parser according to the World Wide Web Consortium (W3C) recommendation. It parses an XML document and builds a DOM tree. The parsing is done in a separate thread and the `DOMBuilderListener` interface must be used for notification when the tree is built.

### Use for Asynchronous Parsing in the Background

The `DOMBuilder` bean encapsulates the XML Parser for Java with a bean interface. It extends its functionality to permit asynchronous parsing. By registering a listener, a Java application can parse documents and return control return to the caller.

Asynchronous parsing in a background thread can be used interactively in visual applications. For example, when parsing a large file with the normal parser, the user interface freezes until the parsing has completed. This can be avoided with the `DOMBuilder` bean. After calling the `DOMBuilder` bean parse method, the application can immediately regain control and display "Parsing, please wait". If a "Cancel" button is included you can also cancel the operation. The application can continue when domBuilderOver() method is called by `DOMBuilder` bean when background parsing task has completed.

When parsing a large number of files, `DOMBuilder` JavaBean can save time. Response times that are up to 40% faster have been recorded when compared to parsing the files one by one.

### DOMBuilder JavaBean Usage

Figure 10-1 illustrates `DOMBuilder` JavaBean usage.

1. The XML document to be parsed is input as a file, string buffer, or URL.

2. This inputs the method `DOMBuilder.addDOMBuilderListener(DOMBuilderListener)` and adds DOMBuilderListener.

3. The `DOMBuilder.parser()` method parses the XML document.

4. Optionally, the parsed result undergoes further processing.

5. `DOMBuilder`Listener API is called using `DOMBuilderOver()` method. This is called when it receives an asynchronous call from an application. This interface must be implemented to receive notifications about events during asynchronous parsing. The class implementing this interface must be added to the `DOMBuilder` using `addDOMBuilderListener` method.

   Available `DOMBuilderListener` methods are:

   - `domBuilderError(DOMBuilderEvent)`. This method is called when parse errors occur.

   - `domBuilderOver(DOMBuilderEvent)`. This method is called when the parse completes.

   - `domBuilderStarted(DOMBuilderEvent)`. This method is called when parsing begins.

6. `DOMBuilder.getDocument()` fetches the resulting DOM document and outputs the DOM document.

Figure 10-1 DOMBuilder JavaBean Usage

Description of the illustration adxdk080.gif

## XSLTransformer JavaBean

The `XSLTransformer` JavaBean accepts an XML file and applies the transformation specified by an input XSL stylesheet to create and output file. It enables you to transform an XML document to almost any text-based format, including XML, HTML, and DDL, by applying an XSL stylesheet.

When integrated with other beans, `XSLTransformer` JavaBean enables an application or user to immediately view the results of transformations.

This bean can also be used as the basis of a server-side application or servlet to render an XML document, such as an XML representation of a query result, into HTML for display in a browser.

The `XSLTransformer` bean encapsulates the Java XML Parser XSLT processing engine with a bean interface and extends its functionality to permit asynchronous transformation. By registering a listener, your Java application can transform large and successive documents by having the control returned immediately to the caller.

XSL transformations can be time consuming. Use `XSLTransformer` bean in applications that transform large numbers of files and it can concurrently transform multiple files.

`XSLTransformer` bean can be used for visual applications for a responsive user interface. There are similar issues here as with `DOMBuilder`.

By implementing `XSLTransformerListener()` method, the caller application can be notified when the transformation is complete. The application is free to perform other tasks in between requesting and receiving the transformation.

### XSLTransformer JavaBean: Regenerating HTML Only When Data Changes

This scenario illustrates one way of applying `XSLTransformer` JavaBean.

1. Create a SQL query. Store the selected XML data in a CLOB table.

2. Using the `XSLTransfomer` JavaBean, create an XSL stylesheet and interactively apply this to the XML data until you are satisfied with the data presentation. The output can be HTML produced by the XSL transformation.

3. Now that you have the desired SQL (data selection) and XSL (data presentation), create a trigger on the table or view used by your SQL query. The trigger can execute a stored procedure. The stored procedure, do the following:

   - Run the query

   - Apply the stylesheet

   - Store the resulting HTML in a `CLOB` table

4. This process can repeat whenever the source data table is updated.

   The HTML stored in the `CLOB` table always mirrors the last data stored in the tables being queried. A JSP (JavaServer Page) can display the HTML.

   In this scenario, multiple end users do not produce multiple data queries that contribute to increased use of the database. The HTML is regenerated only when the underlying data changes.

### How to Use XSLTransformer JavaBean

Figure 10-2 illustrates `XSLTransformer` bean usage.

Figure 10-2 XSLTransformer JavaBean Usage

Description of the illustration adxdk079.gif

1. An XSL stylesheet and XML document are input to the `XSLTransformer` using the `XSLTransfomer.addXSLTransformerListener (XSLTransformerListener)method`. This adds a listener.

2. The `XSLTransfomer.processXSL()` method initiates the XSL transformation in the background.

3. Optionally, other work can be assigned to the `XSLTransformer` bean.

4. When the transformation is complete, an asynchronous call is made and the `XSLTransformerListener.xslTransformerOver()` method is called. This interface must be implemented to receive notifications about events during the asynchronous transformation. The class implementing this interface must be added to the `XSLTransformer` event queue using the method `addXSLTransformerListener`.

5. The `XSLTransformer.getResult()` method returns the XML document fragment for the resulting document.

6. It outputs the XML document fragment.

## DBAccess JavaBean

`DBAccess` JavaBean maintains `CLOB` tables that can hold multiple XML and text documents. Each table is created using the following statement:

    CREATE TABLE tablename FILENAME CHAR(16) UNIQUE, FILEDATA CLOB) LOB(FILEDATA)
       STORE AS (DISABLE STORAGE IN ROW)

Each XML (or text) document is stored as a row in the table. The FILENAME field holds a unique string used as a key to retrieve, update, or delete the row. Document text is stored in the FILEDATA field. This is a `CLOB` object. `DBAccess` bean does the following tasks:

- Creates and deletes `CLOB` tables

- Lists a `CLOB` table's contents

- Adds, replaces, or deletes text documents in the `CLOB` tables

### DBAcess JavaBean Usage

Figure 10-3 illustrates the `DBAccess` bean usage. It shows how `DBAccess` bean maintains, and manipulates XML documents stored in `CLOB`s.

Figure 10-3 DBAccess JavaBean Usage Diagram

Description of the illustration adxdk104.gif

## XMLDiff JavaBean

The `XMLDiff` JavaBean performs a tree comparison on two XML DOM trees. It displays the two XML trees and shows the differences between the XML trees. A node can be inserted, deleted, moved, or modified. Each of these operations is shown in a different color or style as in the following list:

- Red—Used to show a modified Node or Attribute

- Blue—Used to show a new Node or Attribute

- Black—Used to show a deleted Node or Attribute

Moves will be displayed visually as a delete or insert operation.

You can generate the differences between the two XML trees in the form of XSL code. The first XML file can be transformed into the second XML file by using the XSL code generated.

Note: Currently you cannot customize the GUI display.

## XMLCompress JavaBean

This bean class is a simple encapsulation of the XML Compression functionality. The capabilities that are supported in this class are essentially compression of the internal DOM tree obtained via a DOMParser,

Compression of the SAX events thrown by the SAX Parser, decompression of the serialized XML data, returning an `XMLDocument` object. The input for compression can be from an InputStream, a Java string, a database `CLOB` object, or an `XMLType` object. In all cases the `outputStream` has to be set beforehand so that the compressed data is written to it. If the input data is unparsed, the parsing for it is done with no validation.

To use different parsing options, parse the document before input and then pass the `XMLDocument` object to the compressor bean. The compression factor is a rough value based on the file size of the input XML file and the compressed file. The limitation of the compression factor method is that it can only be used when the compression is done using the `java.io.File` objects as parameters.

## XMLDBAccess JavaBean

This bean is an extension of the `DBAcess` bean to support the `XMLType` column, in which XML documents are stored in an Oracle database table. Methods are provided to list, delete, or retrieve `XMLType` instances and their tables.

## XSDValidator JavaBean

This class file encapsulates the `oracle.xml.parser.schema.XSDValidator` class and adds capabilities for validating a DOM tree. The schema document is a constant and the validation is done for XML Documents that can be passed as InputStreams, URLs, and so on.

The validation is done only after the DOM tree is built in all the cases. Nodes with errors are returned in a vector of stack trees where the top element of the stack represents the root node and child nodes are obtained by popping the elements of the stack.

## JavaBean Examples

The XDK JavaBean sample directory, `/xdk/demo/java/transviewer/`, contains sample applications that illustrate how to use JavaBeans.

Table 10-1 lists the example files. The subsequent sections show how to install these samples.

Table 10-1 JavaBean Example Files

File Name | Description
--- | ---
`AsyncTransformSample.java.` | Sample nonvisual application using `XSLTransformer` bean and `DOMBuilder` bean. It applies the XSLT stylesheet specified in `doc.xsl` on all `.xml` files from the current directory. The results are in the files with extension `.log`.
`XMLDBAccessSample.java` | A non-GUI sample for the `XMLDBAccess` bean which demonstrates the way that the `XMLDBAccess` bean APIs can be used to store and retrieve the XML documents inside the database, using XMLType tables. To use `XMLType`, an Oracle9i, or later, installation is necessary along with the `xdb.jar`. `Sample5` will run `XMLDBAccessSample` using the values for `HOSTNAME`, `PORT`, `SID`, `USERID`, and `PASSWORD` as defined in the `Makefile`. These must be modified if required. The file `booklist.xml` is used to insert data into the database. The output is copied to `xmldbaccess.log`.
`XMLDiffSample.java` | Sample visual application that uses `XMLDiff` bean to find differences between two XML files and generate an XSL stylesheet. This stylesheet can be used to transform the first input XML into the second input XML file. See "XMLDiffSample.java".
`compviewer.java` | Sample visual application that uses `XMLCompress` bean to compress an XML file or XML data from the database obtained through SQL query or from a CLOB or an XMLType Table. The application also lets you decompress the compressed stream and view the resulting DOM tree.
`XSDValidatorSample.java` | Sample application for `XSDValidator` bean. It takes two arguments as input, an XML file and a schema file. The error occurring during validation, including line numbers, are displayed. See "XSDValidatorSample.java".

### Installing the JavaBean Examples

The JavaBeans require, as a minimum, JDK 1.2.2.

Here are the steps you take to generate the sample executables:

1. Download and install the following components used by the XDK JavaBeans:

   - Oracle JDBC Driver for thin client (file `classes12.zip`)

   - Oracle XML SQL Utility `(xsu12.jar`)

   - `JAR` file containing the `XMLType` definitions (`file xdb.jar`)

   After installing these components, include the files in your `CLASSPATH`.

2. Change `JDKPATH` in `Makefile` to point to your JDK path. If you do not have an `ORACLE_HOME` set, then set it to the root directory of your XDK JavaBeans installation.

3. Generate `.class` files. Run the sample programs using the following commands, which use labels in the file `Makefile`:

       gmake sample3
       gmake sample5
       gmake sample6
       gmake sample7
       gmake sample10

See Also: README contains details of the various programs labelled sample3 through sample10.

### XMLDiffSample.java

`Sample6` is a demo for `XMLDiff` JavaBean. It invokes a GUI which allows you to choose the input data files from the `File` menu using '`Compare XML Files`' item. The XSLT generated can be applied on input XML `file1` using `Transform` menu. The resulting XML file (which is the same as input `file2`) can be saved using '`Save`' `As` item under `File` menu. By default, the two XML files `XMLDiffData1.txt` and `XMLDiffData2.txt` are compared and the output XSLT is stored as `XMLDiffSample.xsl`.

If the input XML files have a DTD which accesses a URL outside the firewall, then modify `XMLDiffSample.java` to include the proxy server settings before the `setFiles()` call:

     /* Set proxy to access dtd through firewall */
        Properties p = System.getProperties();
        p.put("proxyHost", "www.proxyservername.com");
        p.put("proxyPort", "80");
        p.put("proxySet", "true");

You also have to import`java.util.*;`

### XSDValidatorSample.java

`Sample10` is a demonstration for the `XSDValidator` JavaBean. It takes as default the data file `purchaseorder.xml` and the `purchaseorder.xsd` schema file. The output displays the validation errors.