21
Java API for XMLType

The classes described in this chapter are contained in package oracle.xdb.dom and implement the Java DOM API for XMLType. In addition to implementing the W3C DOM Recommendation, the DOM API for Oracle XML DB provides Oracle-specific extensions. This chapter contains these sections:

• XDBAttribute Class
• XDBCData Class
• XDBCharData Class
• XDBComment Class
• XDBDocument Class
• XDBDomImplementation Class
• XDBElement Class
• XDBEntity Class
• XDBNamedNodeMap Class
• XDBNode Class
• XDBNodeList Class
• XDBNotation Class
• XDBProcInst Class
• XDBText Class
• XMLType Class

Table 21-1 lists each class and the W3C DOM interface it implements.

Table 21-1 Java DOM API for XMLType Classes and W3C Interfaces 

Java DOM API for XMLType Class	W3C DOM Interface Recommendation
XDBAttribute Class	org.w3c.dom.Attribute
XDBCData Class	org.w3c.dom.CData
XDBCharData Class	org.w3c.dom.CharData
XDBComment Class	org.w3c.dom.Comment
XDBDocument Class	org.w3c.dom.Document
XDBDomImplementation Class	org.w3c.dom.DOMImplementation
XDBElement Class	org.w3c.dom.Element
XDBEntity Class	org.w3c.dom.Entity
XDBNamedNodeMap Class	org.w3c.dom.NamedNodeMap
XDBNode Class	org.w3c.dom.Node
XDBNodeList Class	org.w3c.dom.NodeList
XDBNotation Class	org.w3c.dom.Notation
XDBProcInst Class	org.w3c.dom.ProcessingInstruction
XDBText Class	org.w3c.dom.Text

---

XDBAttribute Class

---

Description of XDBAttribute

This class implements org.w3c.dom.Attribute, the W3C DOM Node interface for interacting with XOBs.

---

Syntax XDBAttribute

public class XDBAttribute
 
oracle.xdb.dom.XDBAttribute

---

XDBCData Class

---

Description of XDBCData

This class implements org.w3c.dom.CData, the W3C text interface.

---

Syntax of XDBCData

public class XDBCData
 
oracle.xdb.dom.XDBCData

---

XDBCharData Class

---

Description of XDBCharData

This class implements org.w3c.dom.CharData, the W3C CharacterData interface.

---

Syntax of XDBCharData

public class XDBCharData
 
oracle.xdb.dom.XDBCharData

---

XDBComment Class

---

Description of XDBComment

This class implements the org.w3c.dom.Comment interface.

---

Syntax of XDBComment

public class XDBComment
 
oracle.xdb.dom.XDBComment

---

XDBDocument Class

---

Description of XDBDocument

This class implements the org.w3c.dom.Document interface.

---

Syntax of XDBDocument

public class XDBDocument
 
oracle.xdb.dom.XDBDocument

---

Methods for XDBDocument

XDBDocument()

Description

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

Syntax	Description
public XDBDocument();	Creates new Document. Can be used in server only.
public XDBDocument( byte[] source);	Populates Document from source. Can be used in server only.
public XDBDocument( Connection conn);	Opens connection for caching Document source.
public XDBDocument( Connection conn, byte[] source);	Connection for caching bytes for Document source.
public XDBDocument( Connection conn, String source);	Opens connection for caching string containing XML text.
public XDBDocument( String source);	The string containing XML text. Can be used in server only.

Parameter	Description
source	Contains XML text.
conn	Connection to be used.

---

XDBDomImplementation Class

---

Description of XDBDomImplementation

This class implements org.w3c.dom.DomImplementation.

---

Syntax of XDBDomImplementation

public class XDBDomImplementation
 
oracle.xdb.dom.XDBDomImplementation

---

Methods for XDBDomImplementation

XDBDomImplementation()

Description

Opens a JDBC connection to the server.

Syntax

public  XDBDomImplementation();

---

XDBElement Class

---

Description of XDBElement

This class implements org.w3c.dom.Element.

---

Syntax of XDBElement

public class XDBElement
 
oracle.xdb.dom.XDBElement

---

XDBEntity Class

---

Description of XDBEntity

This class implements org.w3c.dom.Entity.

---

Syntax of XDBEntity

public class XDBEntity
 
oracle.xdb.dom.XDBEntity

---

XDBNamedNodeMap Class

---

Description of XDBNamedNodeMap

This class implements org.w3c.dom.NamedNodeMap.

---

Syntax of XDBNamedNodeMap

public class XDBNamedNodeMap
 
oracle.xdb.dom.XDBNamedNodeMap

---

XDBNode Class

---

Syntax of XDBNode

public abstract class XDBNode
 
oracle.xdb.dom.XDBNode

---

Description of XDBNode

This class implements org.w3c.dom.Node, the W3C DOM Node interface for interacting with XOBs.

---

Methods for XDBNode Class

write()

Description

Writes the XML for this Node (and all subnodes) to an OutputStream. If the OutputStream is a ServletOutputStream, the servlet output is committed and the data is written using a native stream mechanism.

Syntax

public void write( OutputStream s,
                   String charEncoding,
                   short indent);

Parameter	Description
s	The stream to write the output to. Contains XML text.
charEncoding	The IANA char code, such as "ISO-8859".
indent	Number of chars to indent nested elements.

---

XDBNodeList Class

---

Description of XDBNodeList

This class implements org.w3c.dom.NodeList.

---

Syntax of XDBNodeList

public class XDBNodeList
 
oracle.xdb.dom.XDBNodeList

---

XDBNotation Class

---

Description of XDBNotation

This class implements org.w3c.dom.Notation.

---

Syntax of XDBNotation

public class XDBNotation
 
oracle.xdb.dom.XDBNotation

---

XDBProcInst Class

---

Description of XDBProcInst

This class implements org.w3c.dom.ProcInst, the W3C DOM ProcessingInstruction interface.

---

Syntax of XDBProcInst

public class XDBProcInst
 
oracle.xdb.dom.XDBProcInst

---

XDBText Class

---

Description of XDBText

This class implements org.w3c.dom.Text.

---

Syntax of XDBText

public class XDBText
 
oracle.xdb.dom.XDBText

---

XMLType Class

---

Description of XMLType

XMLType implements the Java methods for the sql type SYS.XMLTYPE.

---

Syntax of XMLType

public class XMLType
 
oracle.xdb.XMLType

---

Methods for XMLType Class

Table 21-2 Summary of Methods for XMLType  

Method	Description
createXML()	Creates an XMLType.
getInputStream()	Returns an InputStream corresponding the XMLType data.
getStringVal()	Retrieves the string value containing the XML data from the XMLType.
getClobVal()	Retrieves the CLOB value containing the XML data from the XMLType.
extract()	Extracts the given set of nodes from the XMLType.
existsNode()	Checks for the existence of the given set of nodes in the XMLType.
transform()	Transforms the XMLType using the given XSL document.
isFragment()	Checks if the XMLType is a regular document or a document fragment.
getDOM()	Retrieves the DOM document associated with the XMLType.
writeToOutputStream()	Writes the XML Type data to the specified OutputStream.

createXML()

Description

Creates an XMLType. Throws java.sql.SQLException if the XMLType could not be created. The options are described in the following table.

Syntax	Description
public static XMLType createXML( OPAQUE opq);	Creates and returns an XMLType given the opaque type containing the XMLType bytes.
public static XMLType createXML( Connection conn, String xmlval);	Creates and returns an XMLType given the string containing the XML data.
public static XMLType createXML( Connection conn, CLOB xmlval);	Creates and returns an XMLType given a CLOB containing the XML data.
public static XMLType createXML( Connection conn, Document domdoc);	Creates and returns an XMLType given an instance of the DOM document.
public static XMLType createXML( Connection conn, InputStream is);	Creates and returns an XMLType given the InputStream for the XML data.

Parameter	Description
opq	The opaque object from which the XMLType is to be constructed.
conn	The connection object to be used.
xmlval	Contains the XML data.
domdoc	The DOM Document which represents the DOM tree.

getInputStream()

Description

Returns an input stream which corresponds to the XMLType document. Users can then read the XML data using the InputStream methods.

Syntax

public InputStream getInputStream();

getStringVal()

Description

Retrieves the string value containing the XML data from the XMLType. Throws java.sql.SQLException.

Syntax

public String getStringVal();

getClobVal()

Description

Retrieves the CLOB value containing the XML data from the XMLType. Throws java.sql.SQLException.

Syntax

public CLOB getClobVal();

extract()

Description

Extracts and returns the given set of nodes from the XMLType. This set of nodes is specified by the XPath expression. The original XMLType remains unchanged. Works only in the thick case. If no nodes match the specified expression, returns NULL. Throws java.sql.SQLException.

Syntax

public XMLType extract( String xpath,
                        String nsmap);

Parameter	Description
xpath	The xpath expression which specifies for which nodes to search.
nsmap	The map of namespaces which resolves the prefixes in the xpath expression; format is "xmlns=a.com xmlns:b=b.com"

existsNode()

Description

Checks for the existence of the given set of nodes in the XMLType. This set of nodes is specified by the xpath expression. Returns TRUE if specified nodes exist in the XMLType; otherwise, returns FALSE. Throws java.sql.SQLException.

Syntax

public boolean existsNode( String xpath,
                           String nsmap);

Parameter	Description
xpath	The xpath expression which specifies for which nodes to search.
nsmap	The map of namespaces which resolves the prefixes in the xpath expression; format is "xmlns=a.com xmlns:b=b.com"

transform()

Description

Transforms and returns the XMLType using the given XSL document. The new (transformed) XML document is returned. Throws java.sql.SQLException.

Syntax

public XMLType transform( XMLType xsldoc,
                          String parammap);

Parameter	Description
xsldoc	The XSL document to be applied to the XMLType.
parammap	The top level parameters to be passed to the XSL transformation. This should be of the format "a=b c=d e=f". This can be NULL.

isFragment()

Description

Checks if the XMLType is a regular document or a document fragment. Returns TRUE if doc is a fragment; otherwise, returns FALSE. Throws java.sql.SQLException.

Syntax

public boolean isFragment();

getDOM()

Description

Retrieves the DOM document associated with the XMLType. This document is the org.w3c.dom.Document. The caller can perform all the DOM operations on the Document. If the document is a binary document, the getDOM function will return NULL. Throws java.sql.SQLException.

Syntax

public org.w3c.dom.Document getDOM();

writeToOutputStream()

Description

Writes the XML data into the specified OutputStream.

Syntax

public void writeToOutputStream( OutputStream os);

Parameter	Description
os	Specified Output Stream where data is written.