Summary

Improve DOM API's handling on XML declaration.

Problem

The followings are issues with DOM's handling of the XML declaration:

1. Default values hide the exact settings

   The getXmlVersion and getXmlStandalone methods of DOM Document returns a default value when there is no XML declaration, that makes it impossible for applications to determine whether the values are explicitly declared.

2. Inconsistent handling of null

   While the getXmlVersion and getXmlStandalone methods return a default value when the underlying settings are null, the getXmlEncoding method was specified to return null.

3. Missing setXmlEncoding

   The API defined setXmlVersion and setXmlStandalone, but was missing a method for setting the encoding.

4. Creating Document with XML Declaration

   There's no direct way to construct a DOM Document with XML declaration.

Solution

1. Add three new get methods

   Add new methods to resolve issue 1 and 2, and avoid incompatibility. Methods getDeclaredXmlVersion and getDeclaredXmlStandalone add the ability to represent no declaration with the value "null", while getDeclaredXmlEncoding is for method naming consistency only.

   The existing methods are not deprecated since returning default value, "1.0" for getXmlVersion and false for getXmlStandalone are desirable in certain use cases.

2. Add setXmlEncoding

   Add setXmlEncoding to complete the set methods and resolve issue 3. This method may be used for setting encoding on the Document object.

3. Add new Builder methods

   Add new DocumentBuilder methods that allows constructing a Document object with XML declaration attributes..

Specification

The specdiff is attached.

A convenient link is available below: http://cr.openjdk.java.net/~joehw/jdk14/8231633/specdiff_06/overview-summary.html