E Java APIs: Quick Reference

This appendix provides a quick reference for the Oracle XML DB Java application program interfaces (APIs).

This appendix contains these topics:

Java DOM API For XMLType (oracle.xdb and oracle.xdb.dom Classes)
Oracle XML DB Resource API for Java (oracle.xdb.spi Classes)
Oracle Database 10g Release 1 (10.1): New Java APIs

Java DOM API For XMLType (oracle.xdb and oracle.xdb.dom Classes)

Packages oracle.xdb and oracle.xdb.dom implements the Java Document Object Model (DOM) API for XMLType. Java DOM API for XMLType implements the W3C DOM Recommendation Level 1.0 and Level 2.0 Core and also provides Oracle-specific extensions.

Table E-1 lists the Java DOM API for XMLType (oracle.xdb.dom and oracle.xdb) classes. Note that class XMLType is in package oracle.xdb and not oracle.xdb.dom.

See Also:

Java Methods Not Supported

The following are methods documented in release 2 (9.2.0.1), but not currently supported:

XDBDocument.getElementByID
XDBDocument.importNode
XDBNode.normalize
XDBNode.isSupported
XDBDomImplementation.hasFeature

Table E-1 Java DOM API for XMLType (mostly oracle.xdb.dom) Classes

Java DOM API for XMLType	Description
`XDBAttribute`	Implements the W3C DOM Node interface for interacting with `XOB`s.
`XDBCData`	Implements `org.w3c.dom.CData`, the W3C text interface.
`XDBCharData`	Implements `org.w3c.dom.CharData`, the W3C CharacterData interface.
`XDBComment`	Implements the `org.w3c.dom.Comment` interface.
`XDBDocument`	Implements the `org.w3c.dom.Document` interface. Methods: `XDBDocument()` constructor: `XDBDocument()`; Creates new Document. Can be used in server only. `XDBDocument( byte[ ] source)`; Populates Document from source. Can be used in server only. `XDBDocument( Connection conn)`; Opens connection for caching Document source. `XDBDocument( Connection conn,byte[] source)`; Connection for caching bytes for Document source. `XDBDocument( Connection conn,String source)`; Opens connection for caching string containing XML text. `XDBDocument(String source)`; The string containing XML text. Can be used in server only. Parameters: `source` - Contains XML text., conn -Connection to be used.
`XDBDomImplementation`	Implements `org.w3c.dom.DomImplementation`. Methods: `XDBDomImplementation()`- Opens a JDBC connection to the server.
`XDBElement`	Implements `org.w3c.dom.Element`.
`XDBEntity`	Implements `org.w3c.dom.Entity`.
`XDBNodeMap`	Implements `org.w3c.dom.NamedNodeMap`.
`XDBNode`	Implements `org.w3c.dom.Node`, the W3C DOM Node interface for interacting with XOBs. Methods: `write()` -Writes XML for this Node and all subnodes to an OutputStream. If the OutputStream is ServletOutputStream, the servlet output is committed and data is written using native streaming. public void write( OutputStream s, String charEncoding, short indent); Parameters: `s` - stream to write the output to contains XML text `charEncoding` - IANA char code (for example, "ISO-8859") `indent` - number of characters to indent nested elements
`XDBNodeList`	Implements `org.w3c.dom.NodeList`.
`XDBNotation`	Implements `org.w3c.dom.Notation.`
`XDBProcInst`	Implements `org.w3c.dom.ProcInst`, the W3C DOM ProcessingInstruction interface.
`XDBText`	Implements `org.w3c.dom.Text`.
`XMLType` (package `oracle.xdb`)	Implements Java methods for the SQL type `SYS.XMLTYPE`. Methods: `createXML()` - Creates an `XMLType.` Use this method when accessing data through JDBC. `getStringVal()` - Retrieves 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`.
`createXML()`	Creates an `XMLType`. Throws `java.sql.SQLException` if the `XMLType` could not be created: `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. Parameters: `opq` - opaque object from which the `XMLType` is to be constructed `conn` - connection object to be used, xmlval - contains the XML data `domdoc` - the DOM Document which represents the DOM tree,
`getStringVal()`	Retrieves the string value containing the XML data from the `XMLType`. Throws `java.sql.SQLException.` `public String getStringVal()`;
`getClobVal()`	Retrieves the CLOB value containing the XML data from the `XMLType`. Throws `java.sql.SQLException` `public CLOB getClobVal();`
`getBlobVal()`	Retrieves the BLOB value containing the XML data from the XMLType. Throws java.sql.SQLException. `public oracle.sql.BLOB getBlobVal(int csid)`Parameters: `csid` - the character encoding of the returned BLOB. This value must be a valid Oracle character set id.
`extract()`	Extracts and returns the given set of nodes from the `XMLType`. The 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` `public XMLType extract( String xpath, String nsmap);` Parameters: `xpath` - xpath expression which specifies for which nodes to search `nsmap` - map of namespaces which resolves the prefixes in the xpath expression; format is "xmlns=a.com xmlns:b=b.com"
`existsNode()`	Checks for existence of 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` public boolean existsNode( String xpath, String nsmap); Parameters: `xpath` - xpath expression that specifies for which nodes to search `nsmap` - map of namespaces that resolves prefixes in the xpath expression; format is "xmlns=a.com xmlns:b=b.com",
`transform()`	Transforms and returns the `XMLType` using the given XSL document. The new (transformed) XML document is returned. Throws `java.sql.SQLException.` public `XMLType` transform( `XMLType` xsldoc, String parammap); Parameters: `xsldoc` - The XSL document to be applied to the `XMLType` `parammap` - top level parameters to be passed to the XSL transformation. Use format "a=b c=d e=f". Can be `NULL`.
i`sFragment()`	Checks if the `XMLType` is a regular document or document fragment. Returns `TRUE` if doc is a fragment; otherwise, returns `FALSE`. Throws `java.sql.SQLException.` `public boolean isFragment();`
`getDOM()`	Retrieves the DOM document associated with the `XMLType`. This document is the org.w3c.dom.Document. The caller can perform all DOM operations on the Document. If the document is binary, `getDOM` returns `NULL`. Throws `java.sql.SQLException.` `public org.w3c.dom.Document getDOM();`

Oracle XML DB Resource API for Java (oracle.xdb.spi Classes)

Oracle XML DB Resource API for Java's WebDAV support is implemented using package oracle.xdb.spi classes that render the service provider interface (SPI) drivers. Classes in oracle.xdb.spi implement core WebDAV support for Oracle XML DB. Table E-2 lists the oracle.xdb.spi classes.

Table E-2 Oracle XML DB Resource API for Java (oracle.xdb.spi)

oracle.xdb.spi Class	Description
`XDBContext` Class	Implements the Java naming and context interface for Oracle XML DB, which extends `javax.naming.context`. In this release there is no federation support, in other words, it is completely unaware of the existence of other namespaces. Methods: `XDBContext()` - Class `XDBContext` constructor. `public XDBContext( Hashtable env);` Creates an instance of `XDBContext` class given the environment. `public XDBContext( Hashtable env, String path);` Creates an instance of `XDBContext` class given the environment and path. Parameters: `env` - Environment to describe properties of context, path - Initial path for the context.
`XDBContextFactory` Class	Implements `javax.naming.context`. Methods: `XDBContextFactory()` - Constructor for class `XDBContextFactory.public` `XDBContextFactory();`
`XDBNameParser` Class	Implements `javax.naming.NameParser`
`XDBNamingEnumeration` Class	Implements `javax.naming.NamingEnumeration`
`XDBResource` Class	Implements the core features for Oracle XML DB JNDI service provider interface (SPI). This release has no federation support, and is unaware of the existence of other namespaces. public class XDBResource extends java.lang.Object. Methods: `XDBResource()` - Creates a new instance of XDBResource `getAuthor()` - Returns author of the resource `getComment()` - Returns the DAV comment of the resource `getContent()` - Returns the content of the resource `getContentType()` - Returns the content type of the resource `getCreateDate()` - Returns the create date of the resource `getDisplayName()` - Returns the display name of the resource `getLanguage()` - Returns the language of the resource `getLastModDate()` - Returns the last modification date of the resource `getOwnerId()` - Returns the owner ID of the resource `setACL()` - Sets the ACL on the resource `setAuthor()` - Sets the author of the resource `setComment()` - Sets the DAV comment of the resource `setContent()` - Sets the content of the resource `setContentType()` - Sets the content type of the resource `setCreateDate()` - Sets the creation date of the resource `setDisplayName()` - Sets the display name of the resource `setLanguage()` - Sets the language of the resource `setLastModDate()` - Sets the last modification date of the resource `setOwnerId()` -Sets the owner ID of the resource
`XDBResource()`	Creates a new instance of XDBResource. public Creates a new instance of XDBResource given the environment. `public XDBResource( Hashtable env, String path);` Creates a new instance of XDBResource given the environment and path. Parameters: `env` - Environment passed in, path - Path to the resource
`getAuthor()`	Retrieves the author of the resource. `public String getAuthor();`
`getComment()`	Retrieves the DAV (Web Distributed Authoring and Versioning) comment of the resource. `public String getComment();`
`getContent()`	Returns the content of the resource. `public Object getContent();`
`getContentType()`	Returns the content type of the resource. `public String getContentType();`
`getCreateDate()`	Returns the creation date of the resource. `public Date getCreateDate();`
`getDisplayName()`	Returns the display name of the resource. `public String getDisplayName();`
`getLanguage()`	Returns the Language of the resource. `public String getLanguage();`
`getLastModDate()`	Returns the last modification date of the resource. `public Date getLastModDate();`
`getOwnerId()`	Returns the owner id of the resource. The value expected by this method is the user id value for the database user as provided by the catalog views such as `ALL_USERS`, and so on. `public long getOwnerId();`
`setACL()`	Sets the ACL on the resource. public void setACL( String aclpath); Parameters: `aclpath` - The path to the ACL resource.
`setAuthor()`	Sets the author of the resource. public void setAuthor( String authname); Parameter: `authname` - Author of the resource.
`setComment()`	Sets the DAV (Web Distributed Authoring and Versioning) comment of the resource. `public void setComment(String davcom);` Parameter: `davcom` - DAV comment of the resource.
`setContent()`	Sets the content of the resource. `public void setContent( Object xmlobj);` Parameter: `xmlobj` - Content of the resource.
`setContentType()`	Sets the content type of the resource. `public void setContentType( String conttype);` Parameter: `conttype` - Content type of the resource.
`setCreateDate()`	Sets the creation date of the resource. public void setCreateDate( Date credate); Parameter: `credate` - Creation date of the resource.
`setDisplayName()`	Sets the display name of the resource. `public void setDisplayName( String dname);` Parameter: `dname` - Display name of the resource.
`setLanguage()`	Sets the language of the resource. `public void setLanguage(String lang);` Parameter: `lang` - Language of the resource.
setLastModDate()	Sets the last modification date of the resource. `public void - setLastModDate( Date d);` Parameter: `d` - Last modification date of the resource.
setOwnerId()	Sets the owner id of the resource. The owner id value expected by this method is the user id value for the database user as provided by the catalog views such as `ALL_USERS`, and so on. `public void setOwnerId( long ownerid);` Parameters: `ownerid` - Owner id of the resource.

Oracle Database 10g Release 1 (10.1): New Java APIs

The following lists new Java APIs added for Oracle Database 10g release 1(10.1):

New methods to Manage Node Values Added to XDBNode.java

Get a Node Value

Writes binary data or character data directly to output stream if csid == 0 then data written as binary, else data written in Oracle specified character set id:public void getNodeValue (java.io.OutputStream, int csid) throws IOException, DOMException;
Writes character data directly into output stream: public void getNodeValue (java.io.Writer) throws java.io.IOException, DOMException; Reads binary data from node value. If csid == 0, then data returned in binary, else data returned in Oracle specific character set id: public java.io.InputStream getNodeValue (int csid) throws java.io.IOException, DOMException;
Reads node value as character data: public java.io.Reader getNodeValue () throws java.io.IOException, DOMException;

Set a Node Value

Writes binary data or character data directly to node if csid == 0 then data written as binary, else data written in Oracle specified character set id: public java.io.OutputStream setNodeValue ( int csid) throws IOException, DOMException;
Writes character data directly to node: public java.io.Writer setNodeValue () throws IOException, DOMException;
Passes binary or character data. If csid == 0, data is read as binary, else data is read in Oracle specified character set id: public void setNodeValue (java.io.InputStream, int csid) throws IOException, DOMException;
Passes character data: public void setNodeValue (java.io.Reader) throws IOException, DOMException;

Java DOM APIs to Manage an Attribute Added to XDBAttribute.java

Get an Attribute Value

Writes binary or character data directly to output stream, if csid == 0, then binary data is written to output stream, else character data in Oracle specified character set id: public void getValue (java.io.OutputStream value, int csid) throws IOException, SQLException;
Writes character data directly to output stream: public getValue (java.io.Writer value) throws IOException, SQLException;
Reads binary or character data from attribute value. If csid == 0 then data is returned in binary, else data is returned in Oracle specified character set id: public java.io.InputStream getValue (int csid) throws java.io.IOException, SQLException;
Reads character data from attribute value: public java.io.Reader getValue () throws java.io.IOException, SQLException;

Set an Attribute Value

Writes binary or character data directly into attribute if csid == 0 then data is written in binary, else data written in specified Oracle character set id: public java.io.OutputStream setValue ( int csid) throws IOException, DOMException;
Writes character data directly into attribute value: public java.io.Writer setValue () throws IOException, DOMException;
Passes binary or character data to replace attribute value. if csid == 0 data is read as binary, else data is read in specified Oracle character set id: public void setValue (java.io.InputStream int csid) throws IOException, DOMException;
Passes character data to replace attribute value: public void setValue (java.io.Reader) throws IOException, DOMException;

New Java XMLType APIs

The following lists two new Java XMLType APIs for Oracle Database 10g release 1(10.1):

New XMLType constructor for BLOB with csid argument:

public XMLType (Connection conn, BLOB xmlval, int csid) throws SQLException;

New getBlobVal method with csid argument:

public BLOB getBlobVal(int csid) throws SQLException;

The API s now also cause exceptions in the following cases:

XDBElement.setAttributeNode - throws DOMException.INUSE_ATTRIBUTE_ERR if attribute is in use
XDBElement.setAttributeNodeNS - throws DOMException.INUSE_ATTRIBUTE_ERR if attribute is in use
XDBNamedNodeMap.setNamedItem - throws DOMException.INUSE_ATTRIBUTE_ERR if attribute is in use
XDBNamedNodeMap.setNamedItemNS - throws DOMException.INUSE_ATTRIBUTE_ERR if attribute is in use