Skip Headers
Oracle® XML Developer's Kit Programmer's Guide
10g Release 2 (10.1.2)
Part No. B14033-01
  Go To Table Of Contents
Contents
Go To Index
Index

Previous
Previous
Next
Next
 

10 XDK JavaBeans

This chapter contains these topics:

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:

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.

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.

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. DOMBuilderListener 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 adxdk080.gif follows
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 adxdk079.gif follows
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:

DBAcess JavaBean Usage

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

Figure 10-3 DBAccess JavaBean Usage Diagram

Description of adxdk104.gif follows
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:

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.