Accessing Oracle XML Transviewer Beans

The Oracle XML Transviewer beans are provided as part of XDK for JavaBeans with the Oracle9i Enterprise and Standard Editions from Release 2 (8.1.6) and higher. If you do not have these editions, then you can download the beans from the site: http://otn.oracle.com/tech/xml

XDK for Java: XML Transviewer Bean Features

Direct Access from JDeveloper

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

Sample Transviewer Bean Application

A sample application that demonstrates all of the beans to create a simple XML editor and XSL transformer is included with your software.

The included sample application with the XML SQL Utility (XSU) cause the following:

Database queries to materialize XML

Transform the XML through an XSL stylesheet

Store the resulting XML document in the database for fast retrieval

Database Connectivity

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

XML Transviewer Beans

XML Transviewer Beans comprises the following beans:

DOMBuilder Bean

The DOMBuilder bean is a non-visual bean. It builds a DOMTree from an XML document.

The DOMBuilder bean 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.

Treeviewer Bean

XMLSourceView Bean

The XMLSourceView bean is a visual Java bean. It allows visualization of XML documents and editing. It enables the display of XML and XSL formatted files with color syntax highlighting when modifying an XML document with a text editor. This helps view and edit the files. It can be integrated with DOMBuilder bean, and allows pre- or post-parsing visualization and validation against a specified DTD.

XMLTransformPanel Bean

DBViewer Bean

DBViewer bean is Java bean that displays database queries or any XML by applying XSL stylesheets and visualizing the resulting HTML in a scrollable swing panel. DBViewer bean has XML and XSL tree buffers as well as a result buffer. DBViewer bean allows the calling program to:

Load or save buffers from various sources such as from CLOB tables in an Oracle database or from the file system. Control can be also used to move files between the file system and the user schema in the database.

Apply stylesheet transformations to the XML buffer using the stylesheet in the XSL buffer.

The result can be stored in the result buffer. The XML and XSL buffer content can be shown as a source or tree structure. The result buffer content can be rendered as HTML and also shown as source or tree structure. The XML buffer can be loaded from a database query.

Using DOMBuilder Bean

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.

Used 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.

DOMBuilder Bean Parses Many Files Fast

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

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.

Parses the XML document pointed to by the given URL and creates the corresponding XML document hierarchy.

parseDTD(InputSource, String)

Parses the XML External DTD from given input source.

parseDTD(InputStream, String)

Parses the XML External DTD from given input stream.

parseDTD(Reader, String)

Parses the XML External DTD from given input stream.

Parses the XML External DTD from the URL indicated.

parseDTD(URL, String)

Parses the XML External DTD document pointed to by the given URL and creates the corresponding XML document hierarchy.

removeDOMBuilderErrorListener(DOMBuilderErrorListener)

Removes DOMBuilderErrorListener.

removeDOMBuilderListener(DOMBuilderListener)

Removes DOMBuilderListener.

run()

This method runs in a thread.

Set the base URL for loading external enitites and DTDs.

setDebugMode(boolean)

Sets a flag to turn on debug information in the document.

setDoctype(DTD)

Sets the DTD.

setErrorStream(OutputStream)

Creates an output stream for the output of errors and warnings.

setErrorStream(OutputStream, String)

Creates an output stream for the output of errors and warnings.

setErrorStream(PrintWriter)

Creates an output stream for the output of errors and warnings.

Sets the node factory.

setPreserveWhitespace(boolean)

Sets the white space preserving mode.

setValidationMode(boolean)

Sets the validation mode.

showWarnings(boolean)

Switches to determine whether to print warnings.

Using XSLTransformer Bean

The XSLTransformer bean 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 bean 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.

Do You Have Many Files to Transform? Use XSLTransformer Bean

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

Do You Need a Responsive User Interface? Use XSLTransformer Bean

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

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.

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

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, can for example, do the following:

Run the query

Apply the stylesheet

Store the resulting HTML in a CLOB table

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 (Java Server Page) can display the HTML.

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

Figure 10-2 XSLTransformer Bean Usage

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

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

Optionally, other work can be assigned to the XSLTransformer bean. Table 10-2 lists the XSLTransformer bean methods.

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.

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

It ouputs the XML document fragment.

Table 10-2 XSLTransformer Bean: Methods

Method

Description

addXSLTransformerErrorListener(XSLTransformerErrorListener)

Adds an error event listener.

addXSLTransformerListener(XSLTransformerListener)

Adds a listener.

getId()

Returns the unique XSLTransformer id.

getResult()

Returns the document fragment for the resulting document.

processXSL(XSLstylesheet, InputStream, URL)

Initiates XSL Transformation in the background.

processXSL(XSLstylesheet, Reader, URL)

Initiates XSL Transformation in the background.

processXSL(XSLstylesheet, URL, URL)

Initiates XSL Transformation in the background.

processXSL(XSLstylesheet, XMLDocument)

Initiates XSL Transformation in the background.

processXSL(XSLstylesheet, XMLDocument, OutputStream)

Initiates XSL Transformation in the background.

removeDOMTransformerErrorListener(XSLTransformerErrorListener)

Removes an error event listener.

removeXSLTransformerListener(XSLTransformerListener)

Removes a listener.

run()

setErrorStream(OutputStream)

Sets the error stream used by the XSL processor.

showWarnings(boolean)

Sets the showWarnings flag used by the XSL processor.

Using Treeviewer Bean

The Treeviewer bean displays an XML document as a tree. It recognizes the following XML DOM nodes:

Figure 10-4 XML Treeviewer Bean Usage

Using XMLSourceView Bean

XMLSourceView bean is a visual Java bean that displays an XML document. It improves the viewing of XML and XSL files by color-highlighting the XML/XSL syntax. It also offers an Edit mode. XMLSourceView bean easily integrates with DOMBuilder bean. It allows for pre- or post-parsing visualization and validation against a specified DTD.

XMLSourceView bean recognizes the following XML token types:

Tag

Attribute Name

Attribute Value

Comment

CDATA

PCDATA

PI Data

PI Name

NOTATION Symbol

Each token type has a foreground color and font. The default color/font settings can be changed by the user. This takes an org.w3c.dom.Document object as input.

XMLSourceView Bean Usage

Figure 10-5 displays an XML document with tags shown in blue, tag content in black, and attributes in red.

Figure 10-6 XMLSourceView Bean Usage

The following table, Table 10-3, lists the XMLSourceView Bean methods.

Table 10-3 XMLSourceView Bean Methods

Method

Description

fontGet(AttributeSet)

Extracts and returns the font from a given attributeset.

fontSet(MutableAttributeSet, Font)

Sets the mutableattributeset font.

getAttributeNameFont()

Returns the Attribute Value font.

getAttributeNameForeground()

Returns the Attribute Name foreground color.

getAttributeValueFont()

Returns the Attribute Value font.

getAttributeValueForeground()

Returns the Attribute Value foreground color.

getBackground()

Returns the background color.

getCDATAFont()

Returns the CDATA font.

getCDATAForeground()

Returns the CDATA foreground color.

getCommentDataFont()

Returns the Comment Data font.

getCommentDataForeground()

Returns the Comment Data foreground color.

getEditedText()

Returns the edited text.

getJTextPane()

Returns the viewer JTextPane component.

getMinimumSize()

Returns the XMLSourceView minimal size.

getNodeAtOffset(int)

Returns the XML node at a given offset.

getPCDATAFont()

Returns the PCDATA font.

getPCDATAForeground()

Returns the PCDATA foreground color.

getPIDataFont()

Returns the PI Data font.

getPIDataForeground()

Returns the PI Data foreground color.

getPINameFont()

Returns the PI Name font.

getPINameForeground()

Returns the PI Data foreground color.

getSymbolFont()

Returns the NOTATION Symbol font.

getSymbolForeground()

Returns the NOTATION Symbol foreground color.

getTagFont()

Returns the Tag font.

getTagForeground()

Returns the Tag foreground color.

getText()

Returns the XML document as a String.

isEditable()

Returns boolean to indicate whether this object is editable.

selectNodeAt(int)

Moves the cursor to XML Node at offset i.

setAttributeNameFont(Font)

Sets the Attribute Name font.

setAttributeNameForeground(Color)

Sets the Attribute Name foreground color.

setAttributeValueFont(Font)

Sets the Attribute Value font.

setAttributeValueForeground(Color)

Sets the Attribute Value foreground color.

setBackground(Color)

Sets the background color.

setCDATAFont(Font)

Sets the CDATA font.

setCDATAForeground(Color)

Sets the CDATA foreground color.

setCommentDataFont(Font)

Sets the Comment font.

setCommentDataForeground(Color)

Sets the Comment foreground color.

setEditable(boolean)

Sets the specified boolean to indicate whether this object should be editable.

setPCDATAFont(Font)

Sets the PCDATA font.

setPCDATAForeground(Color)

Sets the PCDATA foreground color.

setPIDataFont(Font)

Sets the PI Data font.

setPIDataForeground(Color)

Sets the PI Data foreground color.

setPINameFont(Font)

Sets the PI Name font.

setPINameForeground(Color)

Sets the PI Name foreground color.

setSelectedNode(Node)

Sets the cursor position at the selected XML node.

setSymbolFont(Font)

Sets the NOTATION Symbol font.

setSymbolForeground(Color)

Sets the NOTATION Symbol foreground color.

setTagFont(Font)

Sets the Tag font.

setTagForeground(Color)

Sets the Tag foreground color.

setXMLDocument(Document)

Associates the XMLviewer with a XML document.

Using XMLTransformPanel Bean

XMLTransformPanel visual bean applies XSL transformations to XML documents. It visualizes the result and allows editing of input XML and XSL documents and files. XMLTransformPanel bean requires no programmatic input. It is a component that interacts directly with you and is not customizable.

XMLTransformPanel Bean Features

XMLTransformPanel bean has the following features:

Imports and exports XML and XSL files from the file system, and XML, XSL, and HTML files from Oracle9i. With Oracle9i, XMLTransformPanel bean uses two-column CLOB tables. The first column stores the data name (file name) and the second stores the data text (file's data) in a CLOB. The bean lists all CLOB tables in your schema. When you click on a table, the bean lists its file names. You can also create or delete tables and retrieve or add files to the tables. This can be useful for organizing your information. See Figure 10-7.

Creates XML from database result sets. This feature enables you to submit any SQL query to the database that you are currently connected. The bean converts the result set into XML and automatically loads this XML data into the bean's XML buffer for further processing.

Edits XML and XSL data loaded into the bean.

Applies XSL transformations to XML buffers and show the results. See With the bean, you can also export results to the file system or a CLOB in the database.

Transviewer Bean Application

The Transviewer bean is one application that illustrates the use of XMLTransform Panel bean. It can be used from a command line to perform the following actions:

Edit and parse XML files

Edit and apply XSL transformations

Retrieve and save XML, XSL and result files in the file system or in Oracle9i

DBViewer bean API allows the calling program to load or save buffers from various sources and apply stylesheet transformation to the XML buffer using the stylesheet in the XSL buffer. Results can be stored in the result buffer.

Showing Content

Content in the XML and XSL buffers can be shown as a source or tree structure. Content in the result buffer can be rendered as HTML and also shown as a source or tree structure.

Loading and Saving the Buffers

The XML buffer can be loaded using a database query. All the buffers can be loaded from and files saved from the following:

CLOB tables in Oracle9i

File system

Therefore, control can also be used to move files between the file system and the user schema in the database.

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. CLOB tables are automatically maintained by the Transviewer bean. The CLOB tables maintained by DBAccess bean can be later used by the Transviewer bean. DBAccess bean does the following tasks:

Using the XMLDiff Bean

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

Red--Used to show a modified Node or Attribute

Blue--Used to show a new Node or Attribute

Black--Used to show a deleted Node or Attribute

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

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

Note:

Currently you cannot customize the GUI display.

XMLDiff Methods

The XMLDiff Bean has the methods described in this section.

boolean diff()

Finds the differences between the two XML files or the two XMLDocument objects.

void domBuilderError(DOMBuilderEvent p0)

Implements the DOMBuilderErrorListener interface called only by the DOM parser.

void domBuilderErrorCalled(DOMBuilderErrorEvent p0)

Implements the DOMBuilderErrorListener interface called only by the DOM parser when there is an error while parsing.

void domBuilderOver(DOMBuilderEvent p0)

Implements the DOMBuilderListener interface called only by a DOM parser thread when the parsing is done.

void domBuilderStarted(DOMBuilderEvent p0)

Implements the DOMBuilderListener interface called only by the DOM parser when the parsing begins.

boolean equals(Node node1, Node node2)

Performs the comparison of two nodes. It is called by the differ algorithm. You can overwrite this function for customized comparisons.

XMLDocument generateXSLDoc()

Generates an XSL stylesheet as an XMLDocument that initially represents the differences between the two XML document sets.

void generateXSLFile(java.lang.String filename)

Generates an XSL file of input filename that represents the differences between the two XML files which were initially set.

javax.swing.JTextPane getDiffPane1()

Gets the text panel as JTextPane object that visually shows the diffs in the first XML file.

javax.swing.JTextPane getDiffPane2()

Gets the text panel as a JTextPane object that visually shows the diffs in the second XML file or document.

XMLDocument getDocument1()

Gets the document root as an XMLDocument object of the first XML tree

XMLDocument getDocument2()

Gets the document root as an XMLDocument object of the second XML tree

void printDiffTree(int tree, BufferedWriter out)

Prints the diff tree that contains the node names and values that have been identified as diffs by the algorithm. This method is useful for debugging.

void setDocuments(XMLDocument doc1, XMLDocument doc2)

Sets the XML documents which need to be compared.

void setFiles(java.io.File file1, java.io.File file2)

Sets the XML files which need to be compared.

void setIndentIncr(int spaces)

Sets the indentation for the XSL generation. This should be called before the generateXSLFile() or generateXSLDoc() methods. The indentation will be applied to all attributes only. For indenting newly inserted nodes besides attributes see void setNewNodeIndentIncr(int spaces).

void setInput1(java.io.File file1)

Sets the first XML file that needs to be compared.

void setInput1(XMLDocument doc1)

Sets the first XML document that needs to be compared.

void setInput2(java.io.File file2)

Sets the second XML file that needs to be compared.

void setInput2(XMLDocument doc2)

Sets the second XML document that needs to be compared.

void setNewNodeIndentIncr(int spaces)

Sets the indentation for the XSL generation. This should be called before the generateXSLFile() or generateXSLDoc() methods. The indentation will be applied to all newly inserted nodes only (except attributes). For attributes indentation support see void setIndentIncr(int spaces).

void setNoMoves()

Assumes that there are no moves to be detected by the diff algorithm. This function should be called before the diff() function. Using this method should improve performance.

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.

A visual application that uses XMLTransformPanel bean. This bean uses all four beans from above. It applies XSL transformations on XML documents and shows the result Visualizes and allows editing of XML and XSL input files.

A sample visual application by which users can graphically compare any two XML files. The differences between the two files can be viewed as XSLT code. The first XML file can be transformed into the second XML file using the generated XSLT.

Installing the Transviewer Bean Samples

The Transviewer beans require as a minimum JDK 1.1.6, and can be used with any version of JDK 1.2.

Download and install the following components used by the Transviewer beans:

Oracle JDBC Driver for thin client (jar file classes111.zip)

Oracle XML SQL Utility (jar file oraclexmlsql.jar)

After installing this components, include classes111.zip and oraclexmlsql.jar in your classpath.

The beans and the samples use swing 1.1. If you use jdk1.2, go to step 3. If you use jdk1.1, you will need to download Swing 1.1 from Sun. After downloading Swing, add swingall.jar to your CLASSPATH.

Change JDKPATH in Makefile to point to your JDK path. In addition, on Windows NT, change the file separator as stated in the Makefile. If you do not have an ORACLE_HOME set, then set it to the root directory of your XDK JavaBeans installation.

If you are not using the default database with a scott/tiger account, change USERID and PASSWORD in the Makefile to run Sample4

Run "make" to generate .class files.

Run the sample programs using commands:

gmake sample1

gmake sample2

gmake sample3

gmake sample4

gmake sample6

Visualize the results in .log files using the ViewSample.

Use the XSLT document from './tohtml.xsl' to transform the XML document from './booklist.xml'.

Use the sample files XMLDiffData1.txt and XMLDiffData2.txt to test the demo sample6 for the XMLDiff Bean. A few .xml files are provided as test cases. An XSL stylesheet 'doc.xsl' is used by XSLTransformer.

Note:

sample1 runs the XMLTransViewer program so that you can import and export XML files from Oracle9i, keep your XSL transformation files in Oracle9i, and apply stylesheets to XML interactively.

Using Database Connectivity

To use the database connectivity feature in this program, you must know the following:

Network name of the computer where Oracle9i or Oracle9i Application Server runs

Port (usually 1521)

Name of the oracle instance (usually orcl)

You also need an account with CREATE TABLE privilege.

You can try the default account scott with password tiger if it still enabled on your Oracle9i system.

Transviewer Bean Example 4a: DBViewer Bean -- DBViewClaims.java

This is an interactive example which lets you input the name or policy of an insurance claim. The appropriate claim is loaded as an XML buffer from the result set of an XML query. An XSL stylesheet is loaded from the file system. The DBViewer bean transforms the XML buffer using the XSL stylesheet to HTML. This HTML output can then be viewed.