D Oracle XML Developer's Kit JavaBeans (Deprecated)

DOMBuilder

The oracle.xml.async.DOMBuilder bean constructs a DOM tree from an XML document. The DOMBuilder JavaBean encapsulates the XML parser for Java DOMParser class with a bean interface and enhances by supporting asynchronous parsing. By registering a listener, Java programs can initiate parsing of large or successive 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.

XSLTransformer

The oracle.xml.async.XSLTransformer bean supports asynchronous transformation. It accepts an XML document, applies an Extensible Stylesheet Language Transformation (XSLT) style sheet, and creates an output file. The XSLTransformer JavaBean enables you to 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.

DBAccess

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.

XMLDBAccess

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

XMLDiff

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 style sheet 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 style sheet that shows the differences between them.

XMLCompress

As explained in "Compressing and Decompressing XML," the Oracle XML parser includes a compressor that can serialize XML document objects as binary streams. 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.

XSDValidator

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, the getStackList() method 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.

Using the DOMBuilder JavaBean: Basic Process

The 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. The DOMBuilderListener interface 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

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

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.

Using the XSLTransformer JavaBean: Basic Process

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 Chapter 4, "XML Parsing for Java". The most important XSL-related classes and interfaces in the javax.xml.async package are described in Table D-2.

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 style sheet and XML instance document.

2. Add an XSLT listener. The program invokes the XSLTransfomer.addXSLTransformerListener()method.

3. Apply the style sheets. 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.

Using the XMLDBAccess JavaBean: Basic Process

When developing applications that use the XMLDBAccess bean, you must use these subpackages:

• 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 Chapter 4, "XML Parsing for Java". Some of the more important methods in the XMLDBAccess class are described in Table D-3.

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.

Using the XMLDiff JavaBean: Basic Process

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

The oracle.xml.parser.v2 subpackage is described in detail in Chapter 4, "XML Parsing for Java". Some important methods in the XMLDiff class are described in Table D-4.

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 style sheet that shows the differences between the input XML documents. For example, generateXSLDoc() generates an XSL style sheet as an XMLDocument.

6. Display the DOM trees created by XMLDiff.

Running sample1

Sample1 is the program that uses the XMLTransViewer bean. You can run the program manually:

java XMLTransformPanelSample

You can use the program to import and export XML files from Oracle Database, store XSL transformation files in the database, and apply style sheets to XML interactively. To use the database connectivity feature in this program, you must know the network name of the computer where the database runs, the port (usually 1521), and the name of the Oracle instance (usually orcl). You also need an account with CREATE TABLE privileges. If you have installed the sample schemas, then you can use the account hr. You can the XMLTransViewer program to apply style sheet transformation to XML files and display the result.The program displays a panel with tabs on the top and the bottom. You can use the first two top tabs to switch between the XML buffer and the XSLT buffer. The third tab performs XSL transformation on the XML buffer and displays the result. You can use the first two tabs on the bottom to load and save data from Oracle Database and from the file system. The remaining bottom tabs switch the display of the current content to tree view, XML source, edit mode and, in case of the result view after the transformation, HTML.

Running sample2

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. You can run the program manually:

java ViewSample

Running sample3

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

java AsyncTransformSample

Running sample4

Sample4 is a visual demo for the DBViewer bean, which is deprecated. It runs in these stages:

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
   

JDBC connection information is hard-coded in the DBViewClaims.java source file, which implements a class used by the demo. Specifically, the program assumes the values for USERID, PASSWORD, and so forth set in the Makefile. If your configuration is different, navigate to line 92 in DBViewClaims.java and modify setUsername(), setPassword(), and so forth with values that reflect your Oracle Database configuration.

Running sample5

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. To run the program you must specify these pieces of information as command-line arguments:

• Host name (for example, myhost)

• Port number (for example, 1521)

• SID of the database (for example, ORCL)

• Database account in which the tables are created (for example, hr)

• Password for the database account (for example, hr)

For example, you can run the program:

java XMLDBAccessSample myhost 1521 ORCL hr hr

The following text shows sample output from dbaccess.log:

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>

Running sample6

The sample6 program is a visual demo for the XMLDiff bean. The XMLDiffSample class invokes a GUI that enables you to choose the input data files from the File menu by selecting Compare XML Files. The Transform menu enables you to apply the generated XSLT generated to the first input XML. Select Save As in the File menu to save the output XML file, which is the same as the second input file. By default, the program compares XMLDiffData1.txt to XMLDiffData2.txt and stores the XSLT output as XMLDiffSample.xsl.

You can run the program manually:

java -mx50m XMLDiffSample XMLDiffData1.txt XMLDiffData2.txt

If the input XML files use a DTD that accesses a URL outside a firewall, then modify XMLDiffSample.java to include the proxy server settings before the setFiles() invocation. For example, modify the program as follows:

/* 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.*; */

Running sample7

The sample7 visual demo shows the use of the XMLCompress bean. The compviewer class invokes a GUI which lets the user compress and uncompress XML files and data obtained from the database. The loading options enable the user to retrieve the data either from a file system or a database. This application does not support loading and saving compressed data from the database. The compression factor indicates a rough estimate by which the XML data is reduced.

You can run the program manually:

java compviewer

Running sample8

The sample8 demo shows the use of the XMLTreeViewer bean. The XMLSchemaTreeViewer program enables the user to view an XMLDocument in a tree format. The user can input a schema document and validate the instance document against the schema. If the document is invalid, then the invalid nodes are highlighted with the error message. Also, the program displays a log of all the line information in a separate panel, which enables the user to edit the instance document and revaluated. Test the program with sample files purchaseorder.xml and purchaseorder.xsd. The instance document purchaseorder.xml does not conform to the schema defined in purchaseorder.xsd.

You can run the program manually:

java XMLSchemaTreeViewer

Running sample9

The sample9 demo shows the use of the SourceViewer bean. The XMLSrcViewer program enables you to view an XML document or a DTD with syntax highlighting turned on. You can validate the XML document against an input XML Schema or DTD. The DTD can be internal or external.

If the validation is successful, then you can view the instance document and XML schema or DTD in the Source View pane. If errors were encountered during schema validation, then an error log with line numbers is available in the Error pane. The Source View pane shows the XML document with error nodes highlighted.You can use sample files purchaseorder.xml and purchaseorder.xsd for testing XML schema validation with errors. You can use note_in_dtd.xml with DTD validation mode to view an internal DTD with validation errors. You can run the program manually:

java XMLSrcViewer

Running sample10

The sample10 demo shows the use of the XSDValidator bean. The XSDValidatorSample program's two input arguments are an XML document and its associated XML schema. The program displays errors occurring during validation, including line numbers.

The following program uses purchaseorder.xsd to validate the contents of purchaseorder.xml:

java XSDValidatorSample purchaseorder.xml purchaseorder.xsd

The XML document fails (intentionally) to validate against the schema. The program displays these errors:

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 the Input XSLT Style Sheet

The makeXSLDocument() method shows a simple DOM parse of the input style sheet. It does not use asynchronous parsing. The technique is the same described in "Performing Basic DOM Parsing."

The method follows these steps:

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 style sheet. The following code fragment invokes the createURL() helper method to accomplish this task:

   xslURL = createURL (xslFile);
   

4. Parse the input XSLT style sheet. 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();
   

Processing the XML Documents Asynchronously

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

The method follows these steps:

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));
   

Comparing the XML Files and Generating a Style Sheet

The showDiffs() method shows the use of the XMLDiff bean.

The method follows these steps:

1. Set the files for the XMLDiff processor. The following statement shows this technique:

   xmlDiff.setFiles(file1, file2);
   

2. Compare the files. The diff() method returns a boolean value that indicates whether the input documents have identical structure and content. If they are equivalent, then the method prints a message to the JFrame implemented by the XMLDiffFrame class. The following code fragment shows this technique:

   if(!xmlDiff.diff())
   {
     JOptionPane.showMessageDialog
     (
       diffFrame,
       "Files are equivalent in XML representation",
       "XMLDiffSample Message",
       JOptionPane.PLAIN_MESSAGE
     );
   }
   

3. Generate a DOM for the XSLT style sheet that shows the differences between the two documents. The following code fragment shows this technique:

   xslDoc = xmlDiff.generateXSLDoc();
   

4. Display the documents in the JFrame implemented by XMLDiffFrame. XMLDiffFrame instantiates the XMLSourceView bean, which is deprecated. The method follows these steps:

   1. Create the source pane for the input documents. Pass the DOM handles of the two documents to the diffFrame object to make the source pane:

      diffFrame.makeSrcPane(xmlDiff.getDocument1(), xmlDiff.getDocument2());
      

   2. Create the pane that shows the differences between the documents. Pass references to the text panes to diffFrame:

      diffFrame.makeDiffSrcPane(new XMLDiffSrcView(xmlDiff.getDiffPane1()),
                                new XMLDiffSrcView(xmlDiff.getDiffPane2()));
      

   3. Create the pane for the XSLT style sheet. Pass the DOM of the style sheet:

      diffFrame.makeXslPane(xslDoc, "Diff XSL Script");
      diffFrame.makeXslTabbedPane();