D Oracle XML Developer's Kit JavaBeans (Deprecated)

The oracle.xml.async.DOMBuilder bean constructs a DOM tree from an XML document. The DOMBuilder JavaBean encapsulates the XML parser for class DOMParser with a bean interface and supports asynchronous parsing. By registering a listener, Java programs can initiate parsing of large or multiple documents and immediately return control to the caller.

A main benefit of this bean is increased efficiency when parsing multiple files, especially if the files are large. DOMBuilder can also provide asynchronous parsing in a background thread in interactive visual applications. Without asynchronous parsing, the GUI is useless until the document to be parsed. With DOMBuilder, the application invokes the parse method and then resumes control. The application can display a progress bar, allow the user to cancel the parse, and so forth.

The oracle.xml.async.XSLTransformer JavaBean supports asynchronous transformation. It accepts an XML document, applies an Extensible Stylesheet Language Transformation (XSLT) stylesheet, and creates an output file. It lets you transform an XML document to almost any text-based format, including XML, HTML, and data definition language (DDL).

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 main benefit of the XSLTransformer bean is that it can transform multiple files in parallel. Like DOMBuilder, you can also use it in visual applications to avoid long periods of time when the GUI is nonresponsive. By implementing the XSLTransformerListener interface, the invoking application receives notification when the transformation completes.

The oracle.xml.dbaccess.DBAccess bean maintains character large object (CLOB) tables that contain multiple XML and text documents.

You can use it to store and retrieve XML documents in the database, but not to process them within the database. Java applications that use the DBAccess bean connect to the database through JDBC. XML documents stored in CLOB tables that are not of type XMLType do not have their entities expanded.

The DBAccess bean enables you to do perform these tasks:

• Create and delete tables of type CLOB.

• Query the contents of CLOB tables.

• Perform INSERT, UPDATE, and DELETE operations on XML documents stored in CLOB tables.

The oracle.xml.xmldbaccess.XMLDBAccess bean extends the DBAccess bean to support XML documents stored in XMLType tables. The class provides methods to list, delete, or retrieve XMLType instances and their tables. For example, the getXMLXPathTextData() method retrieves the value of an XPath expression from an XML document.

DBAccess JavaBean maintains XMLType tables that can hold multiple XML and text documents. Each XML or text document is stored as a row in the table. The table is created with this structured query language (SQL) statement:

CREATE TABLE (FILENAME   CHAR( ) UNIQUE, 
              FILEDATA   SYS.XMLType);

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.

The XMLDBAccess bean performs these tasks:

• Creates and deletes XMLType tables

• Lists the contents of an XMLType column

• Performs INSERT, UPDATE, and DELETE operations on XML documents stored in XMLType tables

When comparing XML documents, it is usually unhelpful to compare them character by character. Most XML comparisons are concerned with differences in structure and significant textual content, not differences in white space.

The oracle.xml.differ.XMLDiff bean performs these tasks:

• Constructs and compares the DOM trees for two input XML documents and indicates whether the documents are different.

• Provides a graphical display of the differences between two XML files. Specifically, you can refer to node insert, delete, modify, or move.

• Generates an XSLT stylesheet that can convert one of the input XML documents into the other document.

The XMLDiff bean is especially useful in pipeline applications. For example, an application could update an XML document, compare it with a previous version of the document, and store the XSLT stylesheet that shows the differences between them.

The Oracle XML parser includes a compressor that can serialize XML document objects as binary streams.

This is explained in Compressing and Decompressing XML. Although a useful tool, compression with XML parser has these disadvantages:

• When XML data is deserialized, it must be reparsed.

• The encapsulation of XML data in tags greatly increase its size.

The oracle.xml.xmlcomp.XMLCompress bean is an encapsulation of the XML compression functionality. It provides these advantages when serializing and deserializing XML:

• It encapsulates the method that serializes the DOM, which produces a stream.

• XML processors can regenerate the DOM from the compressed stream without reparsing the XML.

The bean supports compression and decompression of input XML parsed by DOMParser or SAXParser. DOM compression supports inputs of type XMLType, CLOB, and BLOB.

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 be used only when the compression is performed with java.io.File objects as parameters.

The oracle.xml.schemavalidator.XSDValidator bean encapsulates the XSDValidator class and adds capabilities for validating a DOM tree.

A useful feature of this bean concerns validation errors. If the application throws a validation error, method getStackList() returns a list of DOM tree paths that lead to the invalid node. Nodes with errors are returned in a vector of stack trees in which the top element of the stack represents the root node. You can get child nodes by pulling them from the stack. To use getStackList() you must use instantiate the java.util.Vector and java.util.Stack classes.

Class DOMBuilder 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. Interface DOMBuilderListener must be used for notification when the tree is built.

When developing applications that use this bean, you must import these subpackages:

• oracle.xml.async, which provides asynchronous Java beans for DOM building

• oracle.xml.parser.v2, which provides APIs for SAX, DOM, and XSLT

Subpackage oracle.xml.parser.v2 is described in XML Parsing for Java. The most important DOM-related classes and interfaces in the javax.xml.async package are described in Table D-1.

Table D-1 javax.xml.async DOM-Related Classes and Interfaces

Class/Interface	Description
DOMBuilder class	Encapsulates an XML parser to parse an XML document and build a DOM tree. The parsing is done in a separate thread. The DOMBuilderListener interface must be used for notification when the tree is built.
DOMBuilderEvent class	Instantiates the event object that DOMBuilder uses to notify all registered listeners about parse events.
DOMBuilderListener interface	Must be implemented so that the program can receive notifications about events during the asynchronous parsing. The class implementing this interface must be added to the DOMBuilder with the addDOMBuilderListener() method.
DOMBuildeErrorEvent class	Defines the error event that is sent when parse exception occurs.
DOMBuilderErrorListener interface	Must be implemented so that the program can receive notifications when errors are found during parsing. The class implementing this interface must be added to the DOMBuilder with the addDOMBuilderErrorListener() method.

Figure D-1 depicts the basic process of an application that uses the DOMBuilder JavaBean.

Figure D-1 DOMBuilder JavaBean Usage

Description of "Figure D-1 DOMBuilder JavaBean Usage"

Figure D-1 shows these stages of XML processing:

1. Parse the input XML document. The program can receive the XML document as a file, string buffer, or URL.
2. Add the DOMBuilder listener. The program invokes the method DOMBuilder.addDOMBuilderListener(DOMBuilderListener).
3. Parse the XML document. The program invokes the DOMBuilder.parse() method.
4. Optionally, process the parsed result further.
5. Invoke the listener when the program receives an asynchronous call. The listener, which must implement the DOMBuilderListener interface, is called by invoking the DOMBuilderOver() method.

   The available DOMBuilderListener methods are:

   • domBuilderError(DOMBuilderEvent), which is called when parse errors occur.

   • domBuilderOver(DOMBuilderEvent), which is called when parsing completes.

   • domBuilderStarted(DOMBuilderEvent), which is called when parsing begins.

6. Fetch the DOM. Invoke the DOMBuilder.getDocument() method to fetch the resulting DOM document and output it.

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.

When developing applications that use this bean, you must import these subpackages:

• oracle.xml.async, which provides asynchronous Java beans for XSL transformations

• oracle.xml.parser.v2, which provides APIs for XML parsing SAX, DOM, and XSLT

The oracle.xml.parser.v2 subpackage is described in detail in XML Parsing for Java. The most important XSL-related classes and interfaces in the javax.xml.async package are described in Table D-2.

Table D-2 javax.xml.async XSL-Related Classes and Interfaces

Class/Interface	Description
XSLTransformer class	Applies XSL transformation in a background thread.
XSLTransformerEvent class	Represents the event object used by XSLTransformer to notify XSL transformation events to all of its registered listeners.
XSLTransformerListener interface	Must be implemented so that the program can receive notifications about events during asynchronous transformation. The class implementing this interface must be added to the XSLTransformer with the addXSLTransformerListener() method.
XSLTransformerErrorEvent class	Instantiates the error event object that XSLTransformer uses to notify all registered listeners about transformation error events.
XSLTransformerErrorListener interface	Must be implemented so that the program can receive notifications about error events during the asynchronous transformation. The class implementing this interface must be added to the XSLTransformer using addXSLTransformerListener() method.

Figure D-2 shows XSLTransformer bean usage.

Figure D-2 XSLTransformer JavaBean Usage

Description of "Figure D-2 XSLTransformer JavaBean Usage"

Figure D-2 goes through these stages:

1. Input an XSLT stylesheet and XML instance document.
2. Add an XSLT listener. The program invokes the XSLTransfomer.addXSLTransformerListener()method.
3. Apply the stylesheets. The XSLTransfomer.processXSL() method initiates the XSL transformation in the background.
4. Optionally, perform further processing with the XSLTransformer bean.
5. Invoke the XSLT listener when the program receives an asynchronous call. The listener, which must implement the XSLTransformerListener interface, is called by invoking the xslTransformerOver() method.
6. Fetch the result of the transformation. Invoke the XSLTransformer.getResult() method to return the XML document fragment for the resulting document.
7. Output the XML document fragment.

Basic use of the XMLDBAccess bean is described.

• oracle.xml.xmldbaccess, which includes the XMLDBAccess bean

• oracle.xml.parser.v2, which provides APIs for XML parsing SAX, DOM, and XSLT

The oracle.xml.parser.v2 subpackage is described in detail in XML Parsing for Java. Some of the more important methods in the XMLDBAccess class are described in Table D-3.

Table D-3 XMLDBAccess Methods

Class/Interface	Description
createXMLTypeTable()	Creates an XMLType table.
insertXMLTypeData()	Inserts a text file as a row in an XMLType table.
replaceXMLTypeData()	Replaces a text file as a row in an XMLType table.
getXMLTypeTableNames()	Retrieves all XML tables with names starting with a specified string.
getXMLTypeData()	Retrieves text file from an XMLType table.
getXMLTypeXPathTextData()	Retrieves the text data based on the XPath expression from an XMLType table.

Figure D-3 shows typical XMLDBAccess bean usage. It shows how the DBAccess bean maintains and manipulates XML documents stored in XMLTypes.

Figure D-3 XMLDBAccess JavaBean Usage

Description of "Figure D-3 XMLDBAccess JavaBean Usage"

For example, an XMLDBAaccess program could process XML documents in these stages:

1. Create an XMLType table. Invoke createXMLTypeTable() by passing it database connection information and a table name.
2. List the XMLType tables. Invoke getXMLTypeTableNames() by passing it database connection information and an empty string.
3. Load XML data into the table. Invoke replaceXMLTypeData() by passing it database connection information, the table name, the XML file name, and a string containing the XML.
4. Retrieve the XML data into a String. Invoke getXMLTypeData() by passing it the connection information, the table name, and the XML file name.
5. Retrieve XML data based on an XPath expression. Invoke getXMLXPathTextData() by passing it the connection information, the table name, the XML file name, and the XPath expression.
6. Close the connection.

Basic use of the XMLDiff bean is described.

When developing applications that use the XMLDiff bean, you typically use these subpackages:

• oracle.xml.xmldiff, which includes the XMLDiff bean

• oracle.xml.parser.v2, which provides APIs for XML parsing SAX, DOM, and XSLT

• oracle.xml.async, which provides asynchronous Java beans for DOM building

Subpackage oracle.xml.parser.v2 is described in detail in XML Parsing for Java. Some important methods in class XMLDiff are described in Table D-4.

Table D-4 XMLDiff Methods

Class/Interface	Description
diff()	Determines the differences between two input XML files or two XMLDocument objects.
generateXSL()	Generates an XSL file that represents the differences between the input two XML files. The first XML file can be transformed into the second XML file with the generated stylesheet. If the XML files are the same, then the XSL generated can transform the first XML file into the second XML file, where the first and second files are equivalent. Related methods are generateXSLDoc() and generateXSLFile().
setFiles()	Sets the XML files to be compared.
getDocument1()	Gets the document root as an XMLDocument object of the first XML tree. getDocument2() is the equivalent method for the second tree.
getDiffPane1()	Gets the text panel as JTextPane object that visually shows the diffs in the first XML file. getDiffPane2() is the equivalent method for the second file.

Figure D-4 shows typical XMLDiff bean usage. It shows how XMLDiff bean compares and displays the differences between input XML documents.

Figure D-4 XMLDiff JavaBean Usage

Description of "Figure D-4 XMLDiff JavaBean Usage"

For example, an XMLDiff program could process XML documents in these stages:

1. Create an XMLDiff object.
2. Set the files to be compared. Create File objects for the input files and pass references to the objects to XMLDiff.setFiles().
3. Compare the documents. The diff() method returns false if the XML files are the same and true if they are different.
4. Respond depending on the whether the input XML documents are the same or different. For example, if they are the same, invoke JOptionPane.showMessageDialog() to print a message.
5. Generate an XSLT stylesheet that shows the differences between the input XML documents. For example, generateXSLDoc() generates an XSL stylesheet as an XMLDocument.
6. Display the DOM trees created by XMLDiff.

Sample1 is the program that uses the XMLTransViewer bean.

java XMLTransformPanelSample

Sample2 is a GUI-based demo for the XMLSourceView and XMLTreeView beans, which are deprecated. The ViewSample program displays the booklist.xml file in separate source and tree views.

java ViewSample

Sample3 is a nonvisual demo for the asynchronous DOMBuilder and XSLTransformer beans. The AsyncTransformSample program applies the doc.xsl XSLT stylesheet to all *.xml files in the current directory. The program writes output to files with the extension .log.

java AsyncTransformSample

Sample4 is a visual demo for the DBViewer bean, which is deprecated.

1. It starts SQL*Plus, connects to the database with the USERID and PASSWORD specified in the Makefile, and runs the claim.sql script. This script creates several tables, views, and types for use by the DBViewSample demo program.
2. It runs the DBViewSample program:

   java -classpath "$(MAKE_CLASSPATH)" DBViewSample
   

Sample5 is a nonvisual demo for the XMLDBAccess bean. It uses the XMLType objects to store XML documents inside the database. The following program connects to the database with the Java thin client, creates XMLType tables, and loads the data from booklist.xml.

java XMLDBAccessSample myhost 1521 ORCL hr hr

Demo for createXMLTypeTables():
Table +'testxmltype' successfully created.
 
Demo for listXMLTypeTables():
tablenamename=TESTXMLTYPE
 
Demo for replaceXMLTypeData() (similar to insert):
XML Data from +'booklist.xml' successfully replaced in table 'testxmltype'.
 
Demo for getXMLTypeData():
XMLType data fetched:
<?xml version="1.0"?>
<booklist>  
  <book isbn="1234-123456-1234">    
    <title>C Programming Language</title>    
    <author>Kernighan and Ritchie</author>    
    <publisher>EEE</publisher>    
    <price>7.99</price>  
  </book>
...
  <book isbn="1230-23498-2349879">    
    <title>Emperor's New Mind</title>    
    <author>Roger Penrose</author>    
    <publisher>Oxford Publishing Company</publisher>    
    <price>15.99</price>  
  </book>
</booklist>
 
Demo for getXMLTypeXPathTextData():
Data fetched using XPath exp '/booklist/book[3]':
<book isbn="2137-598354-65978">
  <title>Twelve Red Herrings</title>
  <author>Jeffrey Archer</author>
  <publisher>Harper Collins</publisher>
  <price>12.95</price>
</book>

The sample6 program is a visual demo for the XMLDiff bean.

java -mx50m XMLDiffSample XMLDiffData1.txt XMLDiffData2.txt

/* 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 will also have to import java.util.*; */

The sample7 visual demo shows the use of the XMLCompress bean. Class compviewer invokes a GUI that lets the user compress and uncompress XML files and data obtained from the database. The loading options let the user retrieve the data from a file system or a database.

java compviewer

The sample8 demo uses the XMLTreeViewer bean. The XMLSchemaTreeViewer program lets a user view an XMLDocument in a tree format. The user can input an XML-schema document and validate an instance document against the schema. If the document is invalid, invalid nodes are highlighted with an error message.

java XMLSchemaTreeViewer

The sample9 demo uses the SourceViewer bean. The XMLSrcViewer program lets you view an XML document or a DTD, with syntax highlighting. You can validate the document against an input XML schema or DTD. The DTD can be internal or external.

java XMLSrcViewer

The sample10 demo shows the use of the XSDValidator bean.

java XSDValidatorSample purchaseorder.xml purchaseorder.xsd

Sample purchaseorder.xml purchaseorder.xsd
<Line 2, Column 41>: XML-24523: (Error) Invalid value 'abc' for attribute: 'orderDate'
#document->purchaseOrder
<Line 7, Column 27>: XML-24525: (Error) Invalid text 'CA' in element: 'state'
#document->purchaseOrder->shipTo->state->#text
<Line 8, Column 25>: XML-24525: (Error) Invalid text 'sd' in element: 'zip'
#document->purchaseOrder->shipTo->zip->#text
<Line 14, Column 27>: XML-24525: (Error) Invalid text 'PA' in element: 'state'
#document->purchaseOrder->billTo->state->#text
<Line 17, Column 22>: XML-24534: (Error) Element 'coment' not expected.
#document->purchaseOrder->coment
<Line 29, Column 31>: XML-24534: (Error) Element 'shipDae' not expected.
#document->purchaseOrder->items->item->shipDae

Parsing an XSLT stylesheet is described.

1. Create a new DOMParser() object. The following code fragment from DOMSample.java shows this technique:

   DOMParser parser = new DOMParser();
   

2. Configure the parser. The following code fragment specifies that white space must be preserved:

   parser.setPreserveWhitespace(true);
   

3. Create a URL object from the input stylesheet. The following code fragment invokes the createURL() helper method to accomplish this task:

   xslURL = createURL (xslFile);
   

4. Parse the input XSLT stylesheet. The following statement shows this technique:

   parser.parse (xslURL);
   

5. Get a handle to the root of the in-memory DOM tree. You can use the XMLDocument object to access every part of the parsed XML document. The following statement shows this technique:

   xsldoc = parser.getDocument();
   

Method runDOMBuilders() shows how you can use the DOMBuilder and XSLTransformer beans to perform asynchronous processing. The parsing and transforming of the XML data occurs in the background.

1. Create a resource manager to manage the input XML documents. The program creates a for loop and gets the XML documents. The following code fragment shows this technique:

   rm = new ResourceManager (numXMLDocs);
   for (int i = 0; i < numXMLDocs; i++)
   {
      rm.getResource();
      ...
   }
   

2. Instantiate the DOM builder bean for each input XML document. For example:

   DOMBuilder builder = new DOMBuilder(i);
   

3. Create a URL object from the XML file name. For example:

   DOMBuilder builder = new DOMBuilder(i);
   URL  xmlURL = createURL(basedir + "/" + (String)xmlfiles.elementAt(i));
   if (xmlURL == null)
      exitWithError("File " + (String)xmlfiles.elementAt(i) + " not found");
   

4. Configure the DOM builder. The following code fragment specifies the preservation of white space and sets the base URL for the document:

   builder.setPreserveWhitespace(true);
   builder.setBaseURL (createURL(basedir + "/"));
   

5. Add the listener for the DOM builder. The program adds the listener by invoking addDOMBuilderListener().

   The class instantiated to create the listener must implement the DOMBuilderListener interface. The program provides a do-nothing implementation for domBuilderStarted() and domBuilderError(), but must provide a substantive implementation for domBuilderOver(), which is the method called when the parse of the XML document completes. The method invokes runXSLTransformer(), which is the method that transforms the XML. See Transforming the XML with the XSLTransformer Bean for an explanation of this method.

   The following code fragment shows how to add the listener:

   builder.addDOMBuilderListener
   ( 
      new DOMBuilderListener()
      {
         public void domBuilderStarted(DOMBuilderEvent p0) {}
         public void domBuilderError(DOMBuilderEvent p0) {}
         public synchronized void domBuilderOver(DOMBuilderEvent p0)
         {
            DOMBuilder bld = (DOMBuilder)p0.getSource();
            runXSLTransformer (bld.getDocument(), bld.getId());
         }
      }
   );
   

6. Add the error listener for the DOM builder. The program adds the listener by invoking addDOMBuilderErrorListener().

   The class instantiated to create the listener must implement the DOMBuilderErrorListener interface. The following code fragment show the implementation:

   builder.addDOMBuilderErrorListener
   (
      new DOMBuilderErrorListener() 
      {
         public void domBuilderErrorCalled(DOMBuilderErrorEvent p0)
         {
            int id = ((DOMBuilder)p0.getSource()).getId();
            exitWithError("Error occurred while parsing " +
               xmlfiles.elementAt(id) + ": " +
               p0.getException().getMessage());
         }
      }
   );
   

7. Parse the document. The following statement shows this technique:

   builder.parse (xmlURL);
   System.err.println("Parsing file " + xmlfiles.elementAt(i));
   

Method showDiffs() shows the use of the XMLDiff bean.