CSR :
|
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