10
Oracle XML JavaBeans

Oracle XML JavaBeans are synonymous with the following packages:

• oracle.xml.async Package
• oracle.xml.dbviewer Package
• oracle.xml.srcviewer Package
• oracle.xml.transviewer Package
• oracle.xml.treeviewer Package
• oracle.xml.differ Package

  See Also: Oracle9i XML Developer's Kits Guide - XDK Oracle9i Supplied Java Packages Reference

---

oracle.xml.async Package

---

Description

This is a non-visual bean. It enables asynchronous DOM parsing in separate threads in the background. It utilizes the EventHandler interface to notify the calling class when the job is complete. The classes of the oOracle.xml.async are summarized in Table 10-1.

Table 10-1 Summary of Classes of oracle.xml.async  

Class	Description
DOMBuilder Class	This class encapsulates an eXtensible Markup Language (XML) 1.0 parser to parse an XML document and build a DOM tree.
DOMBuilderBeanInfo Class	This class provides information about the DOMBuilder Bean.
DOMBuilderErrorEvent Class	This class defines the error event which is sent when parse exception occurs.
DOMBuilderErrorListener Interface	This interface must be implemented in order to receive notifications when error is found during parsing.
DOMBuilderEvent Class	The event object that DOMBuilder uses to notify all registered listeners about parse events.
DOMBuilderListener Interface	This interface must be implemented in order to receive notifications about events during the asyncronous parsing.
ResourceManager Class	This class implements a simple semaphore that maintains access to a fixed number of logical resources.
XSLTransformer Class	Applies XSL transformation in a background thread.
XSLTransformerBeanInfo Class	This class provides information about the XSLTransformer Bean.
XSLTransformerErrorEvent Class	The error event object that XSLTransformer uses to notify all registered listeners about transformation error events.

---

DOMBuilder Class

---

Description of DOMBuilder

This class encapsulates an eXtensible Markup Language (XML) 1.0 parser 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.

---

Syntax of DOMBuilder

public class DOMBuilder extends java.lang.Object implements 
java.io.Serializable, oracle.xml.async.DOMBuilderConstants, java.lang.Runnable
 
java.lang.Object
  |
  +--oracle.xml.async.DOMBuilder

---

Implemented Interfaces

• oracle.xml.async.DOMBuilderConstants
• java.lang.Runnable
• java.io.Serializable

---

Fields of DOMBuilder

Table 10-2 Fields of DOMBuilder  

Field	Syntax	Description
inSource	protected org.xml.sax.InputSource inSource	InputSource containing XML data to parse
url	protected java.net.URL url	URL to parse XML data from
inStream	protected java.io.InputStream inStream	InputStream containing XML data to parse
inString	protected java.lang.String inString	String containing the URL to parse XML data from
methodToCall	protected int methodToCall	XML Parser method to call based on input types
reader	protected java.io.Reader reader	java.io.Reader containing XML data to be parsed
result	protected oracle.xml.async.XMLDocument result	XML Document being parsed
rootName	protected java.lang.String rootName	Name of the XML element to be treated as root

---

Methods of DOMBuilder

Table 10-3 Summary of Methods of DOMBuilder  

Method	Description
DOMBuilder()	Creates a new parser object.
addDOMBuilderErrorListener()	Adds DOMBuilderErrorListener.
addDOMBuilderListener()	Adds DOMBuilderListener.
getDoctype()	Gets the DTD.
getDocument()	Gets the document for parsing.
getId()	Returns the parser object ID.
getReleaseVersion()	Returns the release version of Oracle XML Parser.
getResult()	Gets the document being parsed.
getValidationMode()	Returns the validation mode.
parse()	Parses the XML from given input.
parseDTD()	Parses the XML External DTD.
removeDOMBuilderErrorListener()	Removes the DOMBuilderErrorListener.
removeDOMBuilderListener()	Removes the DOMBuilderListener.
run()	Runs in a thread.
setBaseURL()	Sets the base URL for lading external entities and DTD.
setDebugMode()	Sets a flag to run on debug information in the document.
setDoctype()	Sets the DTD.
setErrorStream()	Creates an output stream for errors and warnings.
setNodeFactory()	Sets the node factory.
setPreserveWhitespace()	Sets the white space preservation mode.
setValidationMode()	Sets the validation mode.
showWarnings()	Determines whether to print warnings.

DOMBuilder()

Description

Creates a new parser object. The options are described in the following table.

Syntax	Description
public DOMBuilder();	Creates a new parser object.
public DOMBuilder( int id);	Creates a new parser object with a given id.

Parameter	Description
id	The DOMBuilder id.

addDOMBuilderErrorListener()

Description

Adds DOMBuilderErrorListener.

Syntax

public void addDOMBuilderErrorListener( DOMBuilderErrorListener p0);

Parameter	Description
p0	The DOMBuilderErrorListener to add.

addDOMBuilderListener()

Description

Adds DOMBuilderListener

Syntax

public void addDOMBuilderListener(DOMBuilderListener p0);

Parameter	Description
p0	The DOMBuilderListener to add.

getDoctype()

Description

Gets the DTD.

Syntax

public synchronized oracle.xml.async.DTD getDoctype();

getDocument()

Description

Gets the document for parsing.

Syntax

public synchronized oracle.xml.async.XMLDocument getDocument();

getId()

Description

Returns the parser object id (DOMBuilder).

Syntax

public int getId();

getReleaseVersion()

Description

Returns the release version of the Oracle XML Parser, as a String.

Syntax

public synchronized java.lang.String getReleaseVersion();

getResult()

Description

Gets the document being parsed.

Syntax

public synchronized org.w3c.dom.Document getResult();

getValidationMode()

Description

Returns the validation mode; TRUE if XML parser is validating, FALSE otherwise.

Syntax

public synchronized boolean getValidationMode()

parse()

Description

Parses the XML from given input. Throws the following exceptions:

XMLParseException	If syntax or other error encountered.
SAXException	Any SAX exception, possibly wrapping another exception.
IOExceptiopn	I/O Error.

The options are described in the following table.

Syntax	Description
public final synchronized void parse ( InputSource in);	Parses the XML from an InputSource
public final synchronized void parse ( j InputStream in);	Parses the XML from an InputStream; the base URL should be set for resolving external entities and DTD.
public final synchronized void parse ( Reader r);	Parses the XML from an Reader; the base URL should be set for resolving external entities and DTD.
public final synchronized void parse ( String urlName);	Parses the XML from the URL indicated by the argument.
public final synchronized void parse ( URL url);	Parses the XML document pointed to by the given URL and creates the corresponding XML document hierarchy.

Parameter	Description
in	The input to parse.
r	The Reader containing XML data to parse.
urlName	The String containing the URL from which to parse.
url	The ULR that points to the XML document to parse.

parseDTD()

Description

Parses the XML External DTD. Throws the following exceptions:

XMLParseException	If syntax or other error encountered.
SAXException	Any SAX exception, possibly wrapping another exception.
IOExceptiopn	I/O Error.

The options are described in the following table.

Syntax	Description
public final synchronized void parseDTD ( InputSource in, String rootName);	Parses from a given InputSource.
public final synchronized void parseDTD ( InputStream in, String rootName);	Parses from a givenInputStream. The base URL should be set for resolving external entities and DTD.
public final synchronized void parseDTD ( Reader in, String rootName);	Parses from a given Reader. The base URL should be set for resolving external entities and DTD.
public final synchronized void parseDTD ( String urlName, String rootName);	Parses from the URL indicated.
public final synchronized void parseDTD ( URL url, String rootName);	Parses the XML External DTD document pointed to by the given URL and creates the corresponding XML document hierarchy.

Parameter	Description
in	The input to parse.
rootName	The element to be used as root element.
r	The Reader containing XML data to parse.
urlName	The String containing the URL from which to parse.
utl	The ULR that points to the XML document to parse.

removeDOMBuilderErrorListener()

Description

Removes DOMBuilderErrorListener.

Syntax

public synchronized void removeDOMBuilderErrorListener(
                    DOMBuilderErrorListener p0);

Parameter	Description
po	The DOMBuilderErrorListener to remove.

removeDOMBuilderListener()

Description

Removes DOMBuilderListener.

Syntax

public synchronized void removeDOMBuilderListener(
                    DOMBuilderListener p0);

Parameter	Description
p1	The DOMBuilderListener to remove.

run()

Description

This method runs in a thread. It is specified in java.lang.Runnable.run() in interface java.lang.Runnable.

Syntax

public void run();

setBaseURL()

Description

Sets the base URL for loading external entities and DTDs. This method should to be called if the parse(InputStream) option is used to parse the XML Document.

Syntax

public synchronized void setBaseURL( java.net.URL url);

Parameter	Description
url	The base URL.

setDebugMode()

Description

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

Syntax

public void setDebugMode(boolean flag);

Parameter	Description
flag	Determines whether debug information is stored; TRUE when information is stored, FALSE otherwise.

setDoctype()

Description

Sets the DTD.

Syntax

public synchronized void setDoctype(oracle.xml.async.DTD dtd)

Parameter	Description
dtd	The DTD to set and use while parsing.

setErrorStream()

Description

Creates an output stream for errors and warnings. If an output stream for errors is not specified, the parser will use the standard error output stream System.err for outputting errors and warnings. The options are described in the following table.

Syntax	Description
public final synchronized void setErrorStream( OutputStream out);	Uses OutputSteam.
public final synchronized void setErrorStream( OutputStream out, String enc);	Uses OutputSteam. An IOException is thrown if the encoding specified is not supported.
public final synchronized void setErrorStream( PrintWriter out);	Uses PrintWriter.

Parameter	Description
out	The the output for errors and warnings.
enc	The encoding to use.

setNodeFactory()

Description

Sets the node factory. Applications can extend the NodeFactory and register it through this method. The parser will then use the user supplied NodeFactory to create nodes of the DOM tree. Throws the following exception:

XMLParseException

If an invalid factory is set.

Syntax

public synchronized void setNodeFactory( 
                    oracle.xml.async.NodeFactory factory);

Parameter	Description
factory	The NodeFactory to set.

setPreserveWhitespace()

Description

Sets the white space preservation mode.

Syntax

public synchronized void setPreserveWhitespace( boolean flag);

Parameter	Description
flag	The preserving mode; TRUE to preserve whitespace, FALSE otherwise.

setValidationMode()

Description

Sets the validation mode.

Syntax

public synchronized void setValidationMode(boolean yes);

Parameter	Description
yes	Determines whether the XML parser should be validating; TRUE for validation, FALSE otherwise.

showWarnings()

Description

Determines whether to print warnings.

Syntax

public synchronized void showWarnings(boolean yes);

Parameter	Description
yes	Switch; TRUE to print warnings, FALSE otherwise.

---

DOMBuilderBeanInfo Class

---

Description of DOMBuilderBeanInfo

This class provides information about the DOMBuilder Bean.

---

Syntax of DOMBuilderBeanInfo

public class DOMBuilderBeanInfo extends java.beans.SimpleBeanInfo
 
java.lang.Object
  |
  +--java.beans.SimpleBeanInfo
        |
        +--oracle.xml.async.DOMBuilderBeanInfo

---

Implemented Interfaces of DOMBuilderBeanInfo

• java.beans.BeanInfo

---

Methods of DOMBuilderBeanInfo

Table 10-4 Summary of Methods of DOMBuilderBeanInfo  

Method	Description
DOMBuilderBeanInfo()	The default constructor.
getIcon()	Gets an image object that can be used to represent the DOMBuilder bean in toolbars, toolboxes, and so on.
getPropertyDescriptors()	Retrieves the array of DOMBuilder bean's editable PropertyDescriptiors.

DOMBuilderBeanInfo()

Description

The default constructor.

Syntax

public  DOMBuilderBeanInfo();

getIcon()

Description

Gets an image object that can be used to represent the DOMBuilder bean in toolbars, toolboxes, and so on. Returns an image object representing the requested icon type. Overrides getIcon() method in java.beans.SimpleBeanInfo Class.

Syntax

public java.awt.Image getIcon( int iconKind);

Parameter	Description
iconKind	The kind of icon requested.

getPropertyDescriptors()

Description

Retrieves the array of DOMBuilder bean's editable PropertyDescriptiors. Overrides getPropertyDescriptors() in java.beans.SimpleBeanInfo Class.

Syntax

public java.beans.PropertyDescriptor[] getPropertyDescriptors();

---

DOMBuilderErrorEvent Class

---

Description of DOMBuilderErrorEvent

This class defines the error event which is sent when parse exception occurs.

---

Syntax of DOMBuilderErrorEvent

public class DOMBuilderErrorEvent extends java.util.EventObject
 
java.lang.Object
  |
  +--java.util.EventObject
        |
        +--oracle.xml.async.DOMBuilderErrorEvent

---

Implemented Interfaces of DOMBuilderErrorEvent

• java.io.Serializable

---

Fields of DOMBuilderErrorEvent

Table 10-5 Fields of DOMBuilderErrorEvent

Field	Syntax	Description
e	protected java.lang.Exception	The exception being raised.

---

Methods of DOMBuilderErrorEvent

Table 10-6 Summary of Methods of DOMBuilderErrorEvent  

Method	Description
DOMBuilderErrorEvent()	Constructor for DOMBuilderErrorEvent.
getException()	Retrieves the exception being raised.
getMessage()	Returns the error message generated by the parser.

DOMBuilderErrorEvent()

Description

Constructor for DOMBuilderErrorEvent.

Syntax

public  DOMBuilderErrorEvent( Object p0, 
                              Exception e);

Parameter	Description
p0	The Object that created this error event.
e	The Exception being raised.

getException()

Description

Retrieves the exception being raised.

Syntax

public java.lang.Exception getException();

getMessage()

Description

Returns the error message generated by the parser, as a String.

Syntax

public java.lang.String getMessage();

---

DOMBuilderErrorListener Interface

---

Description of DOMBuilderErrorListener

This interface must be implemented in order to receive notifications when error is found during parsing. The class implementing this interface must be added to the DOMBuilder using addDOMBuilderErrorListener method.

---

Syntax of DOMBuilderErrorListener

public interface DOMBuilderErrorListener extends java.util.EventListener

---

Methods of DOMBuilderErrorListener

domBuilderErrorCalled()

Description

This method is called when a parse error occurs.

Syntax

public void domBuilderErrorCalled( DOMBuilderErrorEvent p0);

Parameter	Description
p0	The DOMBuilderErrorEvent object produced by the DOMBuilder as result of parsing error.

---

DOMBuilderEvent Class

---

Description of DOMBuilderEvent

The event object that DOMBuilder uses to notify all registered listeners about parse events.

---

Syntax of DOMBuilderEvent

public class DOMBuilderEvent extends java.util.EventObject
 
java.lang.Object
  |
  +--java.util.EventObject
        |
        +--oracle.xml.async.DOMBuilderEvent

---

Implemented Interfaces of DOMBuilderEvent

• java.io.Serializable

---

Fields of DOMBuilderEvent

Table 10-7 Fields of DOMBuilderEvent

Field	Syntax	Description
id	protected int id	ID of the source DOMBuilder object

---

Methods of DOMBuilderEvent

Table 10-8 Summary of Methods of DOMBuilderEvent  

Method	Description
DOMBuilderEvent()	Creates a new DOMBuilderEvent.
getID()	Returns unique id of the source DOMBuilder for the event.

DOMBuilderEvent()

Description

Creates a new DOMBuilderEvent.

Syntax

public  DOMBuilderEvent( Object p0,
                         int p1);

Parameter	Description
p0	The Object creating this event.
p1	Id of the DOMBuilder creating this event.

getID()

Description

Returns unique id of the source DOMBuilder for this event, which can be used to identify which instance of the DOMBuilder generated this event in cases where multiple instances of DOMBuilder may be working in background.

Syntax

public int getID();

---

DOMBuilderListener Interface

---

Description of DOMBuilderListener

This interface must be implemented in order to receive notifications about events during the asyncronous parsing. The class implementing this interface must be added to the DOMBuilder using addDOMBuilderListener method.

---

Syntax of DOMBuilderListener

public interface DOMBuilderListener extends java.util.EventListener

---

Methods of DOMBuilderListener

Table 10-9 Summary of Methods of DOMBuilderListener  

Method	Description
domBuilderError()	This method is called when parse error occur.
domBuilderOver()	This method is called when the parse is complete.
domBuilderStarted()	This method is called when parse starts

domBuilderError()

Description

This method is called when parse error occur.

Syntax

public void domBuilderError( DOMBuilderEvent p0);

Parameter	Description
p0	The DOMBuilderEvent object produced by the DOMBuilder.

domBuilderOver()

Description

This method is called when the parse is complete.

Syntax

public void domBuilderOver( DOMBuilderEvent p0);

Parameter	Description
p0	The DOMBuilderEvent object produced by the DOMBuilder.

domBuilderStarted()

Description

This method is called when parse starts.

Syntax

public void domBuilderStarted( DOMBuilderEvent p0);

Parameter	Description
p0	The DOMBuilderEvent object produced by the DOMBuilder.

---

ResourceManager Class

---

Description of ResourceManager

Implements a semaphore and maintains access to a fixed number of logical resources.

---

Syntax of ResourceManager

public class ResourceManager extends java.lang.Object
 
java.lang.Object
  |
  +--oracle.xml.async.ResourceManager

---

Methods of ResourceManager

Table 10-10 Summary of Methods of ResourceManager

Method	Description
ResourceManager()	The ResourceManager constructor.
activeFound()	Checks if any of the logical resources being managed are in active use.
getResource()	If the number of resources available for use is nonzero, decreases the number of resources by one. Otherwise, waits until a resource is released and it becomes available for use.
releaseResource()	Releases a single resource, increasing the number of resources available.
sleep()	Allows use of Thread.sleep() without try/catch.

ResourceManager()

Description

The ResourceManager constructor.

Syntax

public  ResourceManager(int i);

Parameter	Description
i	The number of resources to manage.

activeFound()

Description

Checks if any of the logical resources being managed are in active use. Returns TRUE if one or more resources in use, FALSE if no resources in use.

Syntax

public boolean activeFound();

getResource()

Description

If the number of resources available for use is nonzero, the method decreases the number of resources by one. Otherwise, it waits until a resource is released and it becomes available for use.

Syntax

public synchronized void getResource();

releaseResource()

Description

Releases a resource. When this method is called, the number of resources available is increased by one.

Syntax

public void releaseResource();

sleep()

Description

Allows use of Thread.sleep() without try/catch.

Syntax

public void sleep(int i);

Parameter	Description
i	The number of resources to manage.

---

XSLTransformer Class

---

Description of XSLTransformer

Applies XSL transformation in a background thread.

---

Syntax of XSLTransformer

public class XSLTransformer extends java.lang.Object implements
     java.io.Serializable, oracle.xml.async.XSLTransformerConstants,
     java.lang.Runnable

java.lang.Object
  |
  +--oracle.xml.async.XSLTransformer

---

Fields of XSLTransformer

Table 10-11 Fields of XSLTransformer

Field	Syntax	Description
methodToCall	protected int methodToCall	The XSL transformation method to call based on input types.
result	protected oracle.xml.async.DocumentFragment result	Transformation result document.

---

Methods of XSLTransformer

Table 10-12 Summary of Methods of XSLTransformer  

Method	Description
XSLTransformer()	XSLTransformer class constructor.
addXSLTransformerErrorListener()	Adds and XSLTransformerErrorListener.
addXSLTransformerListener()	Adds and XSLTransformerListener.
getId()	Returns a unique XSLTransformer id.
getResult()	Returns the document fragment of the XSL transformation for the resulting document.
processXSL()	Initiates XSL Transformation in the background. The control is returned immediately.
removeDOMTransformerErrorListener()	Removes an XSLTransformerErrorListener.
removeXSLTransformerListener()	Removes an XSLTransformerListener.
run()	Starts a separate thread to perform the XSLTransformation.
setErrorStream()	Sets the error stream to be used by XML processor.
showWarnings()	Sets the showWarnings flag used by the XSL processor.

XSLTransformer()

Description

XSLTransformer constructor. The options are described in the following table.

Syntax	Description
public XSLTransformer();	XSLTransformer constructor.
public XSLTransformer( int id);	XSLTransformer constructor accepting an identifier.

Parameter	Description
id	A unique integer that can be used to identify the XSLTransformer instance during event processing

addXSLTransformerErrorListener()

Description

Adds an XSLTransformerErrortListener.

Syntax

public void addXSLTransformerErrorListener( 
                    XSLTransformerErrorListerner p0);

Parameter	Description
p0	XSLTransformerErrorListener to be added.

addXSLTransformerListener()

Description

Adds a XSLTransformerListener.

Syntax

public void addXSLTransformerListener( XSLTransformerListerner p0);

Parameter	Description
p0	XSLTransformerListener to be added.

getId()

Description

Returns the unique XSLTransformer id.

Syntax

public int getId();

getResult()

Description

Returns the document fragment of the XSL transformation for the resulting document. Called only after receiving notification that the transformation is complete. Since the transformation occurs in background and asyncronously, calling this method immediately after processXSL() will result in holding the control until the result is available.

Syntax

public synchronized oracle.xml.async.DocumentFragment getResult();

processXSL()

Description

Initiates XSL Transformation in the background. The control is returned immediately. An XSLException is thrown if an error occurs during XSL transformation. The options are described in the following table.

Syntax	Description
public void processXSL( oracle.xml.async.XSLStylesheet xsl, InputStream xml, URL ref)	The source XML document is provided as an InputStream.
public void processXSL( oracle.xml.async.XSLStylesheet xsl, j Reader xml, URL ref);	The source XML document is provided as a Reader.
public void processXSL( oracle.xml.async.XSLStylesheet xsl, URL xml, URL ref);	The source XML document is provided through a URL.
public void processXSL( oracle.xml.async.XSLStylesheet xsl, oracle.xml.async.XMLDocument xml);	The source XML document is provided as a DOM tree.
public void processXSL( oracle.xml.async.XSLStylesheet xsl, oracle.xml.async.XMLDocument xml, j OutputStream os);	The source XML document is provided as a DOM tree, and the output is written into an OutputStream.

Parameter	Description
xsl	The stylesheet to be used for XSL transformation
xml	The XML document to be used
ref	The reference URL to resolve external entities in input XML
os	Output to which the XSL transformation result is written

removeDOMTransformerErrorListener()

Description

Removes an XSLTransformerErrorListener.

Syntax

public synchronized void removeDOMTransformerErrorListener(
                    XSLTransformerErrorListener p0);

Parameter	Description
p0	The XSLTransformerErrorListener to be removed.

removeXSLTransformerListener()

Description

Removes a XSLTransformerListener.

Syntax

public synchronized void removeXSLTransformerListener(
                    XSLTransformerListener p0);

Parameter	Description
p0	The XSLTransformerListener to be removed.

run()

Description

Starts a separate thread to perform the XSLTransformation. Specified by java.lang.Runnable.run() in java.lang.Runnable Interface.

Syntax

public void run();