The Java DOM APIs for XMLType classes are listed, together with their deprecated equivalents.

Table 2-1 lists the oracle.xdb.dom package classes that were deprecated in Oracle Database 11g Release 1 (11.1) and their Unified Java API for XML equivalents.

When you use the Java DOM API to retrieve XML data, you get either 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 World Wide Web Consortium (W3C) DOM interface. The getDOM() method and XDBDocument class have been deprecated in the Unified Java API for XML.

Table 2-2 lists the deprecated XMLType methods and their Unified Java API equivalents.

In addition to the W3C Recommendation, the Unified Java API for XML implementation provides extension APIs that extend the W3C DOM APIs. You can use the Oracle-specific extension APIs for performing basic functions (like connecting to a database) and performance enhancement.

XMLDocument is a class that represents the DOM for the instantiated XML document. Retrieve the XMLType value from the XML document using the XMLType constructor that takes a Document argument. For example:

XMLType createXML(Connection conn, Document domdoc)

To dereference a node manually—that is, to explicitly dereference a document fragment from the DOM tree—use the freeNode() extension API in the oracle.xml.parser.v2 package (XMLNode class).

A Java API that creates an XMLDocument must create either a thin document or a thick document. Because a thick document needs a Connection object to establish communication with the database, each document creation API is extended to accept a Connection object.

For an XMLType.createXML API, you must specify a Connection type, which determines the type of object. Old document creation APIs (provided only for backward compatibility), create thin (pure Java) objects unless you specify otherwise.

Table 2-3 lists the XMLDocument output, based on KIND and CONNECTION.

These objects, methods, and classes are available for document creation in the unified Java API:

• DOMParser object and parse() method

  Use the DOMParser object and parse() method to parse XML documents. You must specify object type—thick or thin. For a thick object, you must also provide the Connection type, 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 and DocumentBuilderFactory class

  Use the DocumentBuilder object to parse XML documents using the Java-specific API, JAXP.

  You must create a DOM parser factory with the DocumentBuilderFactory class. DocumentBuilder builds DOM from input SAX events, taking 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 to the DOMParser object that creates the document from these APIs:

  DocumentBuilder.newDocument()
  DocumentBuilder parse(InputStream)
  DocumentBuilder parse(InputStream, int)
  DocumentBuilder.parse(InputSource)
  

• XSU methods

  Each XSU method returns an XMLDocument to the user. You can specify whether the user wants a thick or thin object. For example:

  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 methods

  You can use the XMLType.createXML method to specify the type of the document (thin or thick) that you want the getDocument() method to get. In this example, the connection is inferred from OPAQUE:

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