2 Unified Java API for XML

This chapter introduces you to the Unified Java API for XMLType and provides information about the APIs that are unified for Oracle XML DB and Oracle XML Developer's Kit.

This chapter contains these topics:

Overview of Unified Java API

Unified Java API is a programming interface that combines the functionality required by both Oracle XDK and Oracle XML DB. Oracle XML DB implements Java DOM API using the Java package oracle.xdb.dom and Oracle XML Developer's Kit implements it using the oracle.xml.parser.v2 package. With Unified Java APIs, you can use a unified set of core DOM APIs required by both Oracle XDK and Oracle XML DB, as well as make use of the new Java classes that provide extra functionality that is built on top of the DOM API.

You can use Unified Java APIs irrespective of how your XML data is stored, that is, whether it resides within or outside the database. This is because Unified Java APIs use a session pool model of connection management. If you do not specify the connection type as thick (that uses OCI APIs and is C-based) or thin (that uses JDBC APIs and is pure Java-based), then Java Document Object Model (DOM) APIs are used for connecting to a local document object that is not stored in the database.

See Also:

Oracle Database XML Java API Reference for information about the oracle.xml.parser.v2 package.

Component Unification

Certain components that were either supported by only the thick connection or the thin connection have been unified in the Unified Java API model. The components that were earlier supported by thin connection but have been unified include:

  • DOM Parser

  • JAXP Transformer

  • XSU

  • XSLT

Moving to the Unified Java API Model

Unified Java API provides new Java classes that replace the old oracle.xdb.dom Java classes. All classes in the oracle.xdb.dom package have been deprecated. If you are using any of the old classes, you need to migrate to the new Unified Java API and use the oracle.xml.parser.v2 classes instead.

Java DOM APIs for XMLType Classes

Table 2-1 lists the oracle.xdb.dom package classes that have been deprecated in the Oracle Database 11g release 1.

Table 2-1 Deprecated XDB Package Classes And Their Unified Java API Equivalent

oracle.xdb.dom.* classes oracle.xml.parser.v2 (Unified Java API) classes

XDBAttribute

XMLAttr

XDBBinaryDocument

This has been deprecated and has no replacement in the Java DOM API XMLType classes

XDBCData

XMLCDATA

XDBCharData

CharData

XDBComment

XMLComment

XDBDocFragment

XMLDocumentFragment

XDBDocument

XMLDocument

XDBDocumentType

DTD

XDBDOMException

XMLDomException

XDBDomImplementation

XMLDomImplementation

XDBDOMNotFoundErrException

This has been deprecated and has no replacement in the Java DOM API XMLType classes

XDBElement

XMLElement

XDBEntity

XMLEntity

XDBEntityReference

XMLEntityReference

XDBNamedNodeMap

XMLAttrList

XDBNode

XMLNode

XDBNotation

XMLNotation

XDBNotImplementedException

This has been deprecated and has no replacement in the Java DOM API XMLType classes

XDBProcInst

XMLPI

XDBText

XMLText


When you use the Java DOM API to retrieve XML data, you either get an XMLDocument instance if the connection is thin, or an XDBDocument instance with method getDOM() and an XMLDocument instance with method getDocument(). Both XMLDocument and XDBDocument are instances of the W3C DOM interface. The getDOM() method and XDBDocument class have been deprecated in the Unified Java APIs. Table 2-2 lists the new methods and classes that are supported with the current release.

Table 2-2 Deprecated XMLType Methods

oracle.xdb.XMLType old API oracle.xdb.XMLType new API

getDOM()

getDocument()

public XMLType createXML(...)

public XMLType createXML(..., int kind) where kind is either XMLDocument.THICK or XMLDocument.THIN


Extension APIs

In addition to the W3C Recommendation, the Unified Java API implementation provides some extension APIs that extend the W3C DOM APIs in various ways. You can use the Oracle-specific extension APIs for either performing the basic functions like connecting to a database or for performance enhancement.

XMLDocument is a class that represents the DOM for the instantiated XML document. You can retrieve the XMLType value from the XML document using the XMLType constructor that takes a Document argument:

XMLType createXML(Connection conn, Document domdoc)

Use the freeNode() extension API available in the oracle.xml.parser.v2 package (XMLNode class) for manual dereferencing of nodes. When you use freeNode(), you explicitly dereference a document fragment from the DOM tree.

Document Creation Java APIs

The unified Java APIs that create an XMLDocument must create either a thin document or a thick document. A thick document requires a Connection object in order to establish communication with the database. So the creation APIs are extended to accept a Connection object.

Note:

You must specify the Connection type. Old document creation APIs are still supported for backward compatibility.

For XMLType.createXML APIs, Connection determines the type of object and for other APIs, a thin (pure Java) object is created if not explicitly specified.

Table 2-3 lists the XMLDocument output, based on the KIND and Connection property:

Table 2-3 XMLDocument Output Based on XMLDocument.KIND and XMLDocument.CONNECTION

XMLDocument.KIND XMLDocument.CONNECTION XMLDocument

XMLDocument.THICK

Thick or KPRB connection

Thick DOM

XMLDocument.THICK

Thin or no connection

Exception

XMLDocument.THIN

Any connection type

Thin DOM

Not specified

Any connection type

Non-XMLType APIs. Thin DOM

XMLType.createXML APIs - Based on connection type. That is, Thick DOM for OCI or KPRB connection, and Thin DOM for a Thin connection.


The following objects and methods are provided for document creation in the unified Java API model:

  • DOMParser object and parse() method: Use the DOMParser object and parse() method to parse XML documents. You must specify the type of object, that is, thick or thin. For thick objects, you must also provide the Connection property using the DOMParser.setAttribute() API. For example:

    DOMParser parser = new oracle.xml.parser.v2.DOMParser();
    parser.setAttribute(XMLDocument.KIND, XMLDocument.THICK);
    parser.setAttribute(XMLDocument.CONNECTION, conn);
    
  • DocumentBuilder object: Use the DocumentBuilder object to parse XML document using the Java-specific API, JAXP. You need to create a DOM parser factory with the DocumentBuilderFactory class. The DocumentBuilderFactory class then passes the connection into the DOMParser, which is used to create the document from these APIs.

  • DocumentBuilder builds DOM from input SAX events. This takes the Connection from a property set on the DocumentBuilderFactory. For example:

    DocumentBuilderFactory.setAttribute(XMLDocument.CONNECTION, conn);
    DocumentBuilderFactory.setAttribute(XMLDocument.KIND,XMLDocument.THICK); 
    

    DocumentBuilderFactory passes the connection into the DOMParser that is used to create the document from the following APIs:

    DocumentBuilder.newDocument()
    DocumentBuilder parse(InputStream)
    DocumentBuilder parse(InputStream, int)
    DocumentBuilder.parse(InputSource)
    
  • XSU: These methods return an XMLDocument to the user. You can specify whether they want a thick or thin object:

    OracleXMLUtil util = new OracleXMLUtil(...);
    util.setAttribute(XMLDocument.KIND, XMLDocument.THICK);
    util.setAttribute(XMLDocument.CONNECTION, conn);
    Document doc = util.getXMLDOMFromStruct(struct, enc);
    
    OracleXMLQuery query = new OracleXMLQuery(...);
    query.setAttribute(XMLDocument.KIND, XMLDocument.THICK);
    query.setAttribute(XMLDocument.CONNECTION, conn);
    Document doc = query.getXMLDOM (root, meta);
    
    OracleXMLDocGenDOM dgd = new OracleXMLDocGenDOM(...);
    dgd.setAttribute(XMLDocument.KIND, XMLDocument.THICK);
    dgd.setAttribute(XMLDocument.CONNECTION, conn);
    Document doc = dgd.getXMLDocumentDOM(struct, enc);
    
  • XMLType: Using the getDocument() method, you can specify whether you want a thick or thin object. All existing XMLType methods are still available. In this example, the connection is inferred from the OPAQUE:

    XMLType xt = XMLType.createXML(orset.getOPAQUE(1), XMLDocument.THICK);
    Document doc = xt.getDocument();
    

One known case that will not allow for the user to specify the type is the case of an XMLType that is created using the ResultSet.getObject() API. If a user has a table with an XMLType column, and the user selects of this column, the user can call getObject() on the ResultSet. This will return an XMLType object. The type is determined by the Connection used in the JDBC call to fetch the column.