Summary

The DOM Load and Save LSSerializer does not have an explicit control for whether or not the XML Declaration ends with a newline. A JDK implementation specific property and corresponding System property are added to control the addition of a newline.

Add an implementation note in the java.xml module summary to document implementation specific features and properties.

Problem

The DOM Load and Save LSSerializer writes out an XML document without a newline after the XML declaration even when pretty-print is required. This issue is a regression introduced after the update of Xalan 2.7.1. In Xalan 2.7.1, two conditions were added to determine whether a newline should be added after the declaration: standalone is specified; A DOCTYPE exists. Without meeting either or one of these conditions, the serializer would produce no newline after the declaration even though pretty-print is requested through the property “format-pretty-print”. The behavior change may cause failure in applications that depend on the format of the resulting document.

A bug report was first filed in 7u4 (JDK-7150637) when the change in the serializer was manifested through the Transform API. The current report (https://bugs.openjdk.java.net/browse/JDK-8249867) showed similar issue when the DOM Load and Save API are used.

In addition to the current issue, it is noted that there is a lack of documentation for the implementation specific features and properties in the javadoc.

Solution

To address the current issue, add a JDK implementation specific property isStandalone that can be set on a LSSerializer through the DOMConfiguration in the org.w3c.dom.ls package. The new property can be used in new code to reverse the behavior change. Add a corresponding System property as a means for existing code to do the same.

To address the generally inadequacy on documentation, add an implementation note to java.xml module summary to cover the property above and also establish a framework for documenting other new or existing properties.

Specification

Add an implementation note for the isStandalone property to java.xml module-summary (java.xml/module-info.java). Since this is the first property to be added to the module-info, a full description about Implementation specific features and properties is added prior to the introduction of the property. Further property additions will simply be appended to the Properties table.

Specification attached. Please see the Implementation Note section in page java.xml/module-summary.html.

Below is a link to the page for convenience: http://cr.openjdk.java.net/~joehw/jdk17/8249867/spec_04/java.xml/module-summary.html