2 Unified Java API for XML

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.

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.

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.

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:

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.