Oracle8i Application Developer's Guide - XML Release 3 (8.1.7) Part Number A86030-01 |
Library | Service | Contents | Index

Using XML Transviewer Beans, 5 of 15

## Using DOMBuilder Bean (Async API)

DOMBuilder() class implements an eXtensible Markup Language (XML) 1.0 parser according to the World Wide Web Consortium (W3C) recommendation, to parse an XML document and build a DOM tree.

The parsing is done in a separate thread and DOMBuilderListener interface must be used for notification when the tree is built.

### Used for Asynchronous Parsing in the Background

DOM Builder Bean encapsulates 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 can freeze till the parsing has completed. This can be avoided with the DOMBuilder Bean. After calling the DOMBuilder Bean parse method, the application can receive control back immediately 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 you much time. Up to 40% faster times have been recorded when compared to parsing the files one by one.

### DOMBuilder Bean Usage

Figure 20-1 illustrates DOMBuilder Bean usage.

1. The XML document to be parsed is input as a file, string buffer, or URL.

2. This inputs `DOMBuilder.addDOMBuilderListener(DOMBuilderListener)`method. This adds DOMBuilderListener.

3. The DOMBuilder.parser() method parses the XML document.

4. Optionally, the parsed result undergoes further processing. See Table 20-1 for a list of available methods to apply.

5. DOMBuilderListener API is called using DOMBuilderOver() method. This is called when it received an async 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 error occur.

   - domBuilderOver(DOMBuilderEvent). This method is called when the parse is complete

   - domBuilderStarted(DOMBuilderEvent). This method is called when parsing starts

6. DOMBuilder.getDocument() fetches the resulting DOM document and outputs the DOM document.

#### Figure 20-1 DOMBuilder Bean Usage

.

##### Table 20-1 DOMBuilder Bean (Async API): Methods

Method | Description
--- | ---
addDOMBuilderErrorListener(DOMBuilderErrorListener) | Adds DOMBuilderErrorListener
addDOMBuilderListener(DOMBuilderListener) | Adds DOMBuilderListener
| Get the DTD
getDocument() | Gets the document
getId() | Returns the parser object id.
getReleaseVersion() | Returns the release version of the Oracle XML Parser
| Gets the document
getValidationMode() | Returns the validation mode
parse(InputSource) | Parses the XML from given input source
| Parses the XML from given input stream.
parse(Reader) | Parses the XML from given input stream.
parse(String) | Parses the XML from the URL indicated
parse(URL) | 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) | Remove DOMBuilderErrorListener
removeDOMBuilderListener(DOMBuilderListener) | Remove 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) | Set 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.
| Set the node factory.
setPreserveWhitespace(boolean) | Set the white space preserving mode
setValidationMode(boolean) | Set the validation mode
showWarnings(boolean) | Switch to determine whether to print warnings

| Copyright © 1996-2000, Oracle Corporation. All Rights Reserved. |
Library | Service | Contents | Index