Binary XML format in Java applications

The IBM® Data Server Driver for JDBC and SQLJ can send XML data to the data server or retrieve XML data from the data server as binary XML data (data that is in the Extensible Dynamic Binary XML DB2® Client/Server Binary XML Format). The data server must provide support for binary XML data.

The IBM Data Server Driver for JDBC and SQLJ presents binary XML data to the application only through XML object interfaces. The user does not see the data in the binary XML format.

The format of XML data is transparent to the application. Storage and retrieval of binary XML data requires version 4.9 or later of the IBM Data Server Driver for JDBC and SQLJ. If you are using binary XML data in SQLJ applications, you also need version 4.9 or later of the sqlj4.zip package.

You use the property xmlFormat to control whether the data format for retrieval of XML data is textual XML format or binary XML format. You set xmlFormat to XML_FORMAT_BINARY (1) to enable binary XML format. The default is textual XML format.

For update of data in XML table columns, xmlFormat has no effect. If the input data is binary XML data, and the data server does not support binary XML data, the input data is converted to textual XML data. Otherwise, no conversion occurs.

When binary XML data is used, the XML data that is passed to the IBM Data Server Driver for JDBC and SQLJ cannot refer to external entities, internal entities, or internal DTDs. External DTDs are supported only if those DTDs were previously registered in the data source.

There is no setXXX method defined on the Connection interface for the xmlFormat property. Therefore, to set the xmlFormat value when you use the Connection interface, you need to specify xmlFormat as a property when you execute the DriverManager.getConnection method. For example:

properties.put("xmlFormat", "1");
DriverManager.getConnection(url, properties);
Restriction: When you send XML data in binary format to a Db2 for z/OS® data server that supports binary XML data, you cannot use an InputStreamReader object with a Charset object named UTF-16LE, UTF-8, or UTF-16BE for an XML document file that contains a byte order mark (BOM). To circumvent this restriction, take one of the following actions:
  • Remove the BOM from the XML instance document in the input file.
  • Use an InputStreamReader object with a Charset object named UTF-16 for the input file.
  • Use an InputStream object instead of an InputStreamReader object for the input file.

Binary XML format is most efficient for cases in which the input or output data is in a non-textual representation, such as SAX, StAX, or DOM. For example, these methods retrieve XML data in non-textual representations:

  • getSource(SAXSource.class)
  • getSource(StAXSource.class)
  • getSource(DOMSource.class)

These methods update XML columns with data in non-textual representations:

  • setResult(SAXResult.class)
  • setResult(StAXResult.class)
  • setResult(DOMResult.class)

The SAX representation is the most efficient way to retrieve data that is in the binary XML format because the data does not undergo extra conversions from binary format to textual format.

Suppose that you set xmlFormat to XML_FORMAT_BINARY (1). In the following JDBC example, the IBM Data Server Driver for JDBC and SQLJ retrieves data in the binary XML format, application uses the SAX parser to parse the retrieved data.
…
Statement stmt = conn.createStatement();
ResultSet rs = stmt.executeQuery("SELECT XMLCOL FROM XMLTABLE");
ContentHandler handler = new MyContentHandler();
while (rs.next()) {
	SQLXML sqlxml = rs.getSQLXML(1);				
	SAXSource source = sqlxml.getSource(SAXSource.class);
	XMLReader reader = source.getXMLReader();
	reader.setContentHandler(handler);
	reader.parse(source.getInputSource());
}
…

The following SQLJ example performs the same actions.

#sql iterator  SqlXmlIter(java.sql.SQLXML);
{
 …
 SqlXmlIter SQLXMLiter = null;
 java.sql.SQLXML outSqlXml = null;
 ContentHandler handler = new MyContentHandler();
 #sql [ctx] SQLXmlIter = {SELECT XMLCOL FROM XMLTABLE};
 #sql {FETCH :SqlXmlIter INTO :outSqlXml}; 
 while (!SQLXMLIter.endFetch()) {
  SAXSource source = outSqlXml.getSource(SAXSource.class);
  XMLReader reader = source.getXMLReader();
  reader.setContentHandler(handler);
  reader.parse(source.getInputSource());
  #sql {FETCH :SqlXmlIter INTO :outSqlXml};
 }
 …
}