8 Using XDK JavaBeans

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.

One of the main benefits 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 calls 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 XSLT stylesheet, 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 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 calling application receives notification when the transformation completes.

DBAccess

The oracle.xml.dbaccess.DBAccess bean maintains CLOB tables that contain multiple XML and text documents. You can use it when you need to store and retrieve XML documents in the database, but do not need to process them within the database. Java applications that use the DBAccess bean connect to the database through JDBC. Note that 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 the following 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 the following 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 the following 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 whitespace. The oracle.xml.differ.XMLDiff bean performs the following useful 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 see 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 an XML document, compare it with a previous version of the document, and store the XSLT stylesheet that shows the differences between them.

XMLCompress

As explained in "Compressing 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 the following 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 the following advantages when serializing and deserializing XML:

• It encapsulates the method that serializes the DOM, which results in 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 only be used 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. One of the most useful features 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 obtain 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 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 should import the following 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 3, "Using the XML Parser for Java". The most important DOM-related classes and interfaces in the javax.xml.async package are described in Table 8-1.

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

Figure 8-1 DOMBuilder JavaBean Usage

Description of the illustration adxdk080.gif

Figure 8-1 shows the following 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. Call 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 should import the following 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 3, "Using the XML Parser for Java". The most important XSL-related classes and interfaces in the javax.xml.async package are described in Table 8-2.

Figure 8-2 illustrates XSLTransformer bean usage.

Figure 8-2 XSLTransformer JavaBean Usage

Description of the illustration adxdk079.gif

Figure 8-2 goes through the following 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. Call the XSLT listener when the program receives an asynchronous call. The listener, which must implement the XSLTransformerListener interface, is called by invoking the xslTranfsformerOver() 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 should use the following 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 3, "Using the XML Parser for Java". Some of the more important methods in the XMLDBAccess class are described in Table 8-3.

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

Figure 8-3 XMLDBAccess JavaBean Usage

Description of the illustration adxdk104.gif

For example, an XMLDBAaccess program could process XML documents in the following 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 the following 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 3, "Using the XML Parser for Java". Some important methods in the XMLDiff class are described in Table 8-4.

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

Figure 8-4 XMLDiff JavaBean Usage

For example, an XMLDiff program could process XML documents in the following 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.

Running sample1

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

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 stylesheets to XML interactively. To use the database connectivity feature in this program, you need to 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 stylesheet transformation to XML files and display the result.The program displays a panel with tabs on the top and the bottom. The first two top tabs are used to switch between the XML buffer and the XSLT buffer. The third tab performs XSL transformation on the XML buffer and displays the result. The first two tabs on the bottom can be used 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 as follows:

java ViewSample

Running sample3

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

java AsyncTransformSample

Running sample4

Sample4 is a visual demo for the DBViewer bean, which is deprecated. It runs in the following 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 a number of tables, views, and types for use by the DBViewSample demo program.

2. It runs the DBViewSample program as follows:

   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 the following 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 will be created (for example, hr)

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

For example, you can run the program as follows:

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 will be 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 as follows:

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() call. 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 illustrates 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 as follows:

java compviewer

Running sample8

The sample8 demo illustrates 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 comply with schema defined in purchaseorder.xsd.

You can run the program manually as follows:

java XMLSchemaTreeViewer

Running sample9

The sample9 demo illustrates 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 as follows:

java XMLSrcViewer

Running sample10

The sample10 demo illustrates the use of the XSDValidator bean. The XSDValidatorSample program two arguments as input: 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 the following 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 Stylesheet

The makeXSLDocument() method illustrates a simple DOM parse of the input stylesheet. 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 illustrates this technique:

   DOMParser parser = new DOMParser();
   
   

2. Configure the parser. The following code fragment specifies that whitespace should 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 illustrates this technique:

   parser.parse (xslURL);
   
   

5. Obtain 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 illustrates this technique:

   xsldoc = parser.getDocument();
   

Processing the XML Documents Asynchronously

The runDOMBuilders() method illustrates 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 obtains the The following code fragment illustrates 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 whitespace 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. Refer to "Transforming the XML with the XSLTransformer Bean" for an explanation of this method.

   The following code fragment illustrates 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 illustrates this technique:

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

Comparing the XML Files and Generating a Stylesheet

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

The method follows these steps:

1. Set the files for the XMLDiff processor. The following statement illustrates 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 illustrates 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 stylesheet that shows the differences between the two documents. The following code fragment illustrates this technique:

   xslDoc = xmlDiff.generateXSLDoc();
   
   

4. Display the documents in the JFrame implemented by XMLDiffFrame. Note that 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 as follows:

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

   3. Create the pane for the XSLT stylesheet. Pass the DOM of the stylesheet as follows:

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