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.

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.

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.

This JDK implementation specific property isStandalone was initially introduced in JDK 17 (https://bugs.openjdk.java.net/browse/JDK-8259352) and it is documented as an implementation note in the java.xml module summary. Identical documentation approach can be applied for JDK16u and Oracle JDK11u, whereas the documentation for Oracle JDK8u and Oracle JDK7u are going to be the release notes.

Specification

Relevant package and interfaces:

Package: org.w3c.dom.ls

Interface: DOMConfiguration and LSSerializer

Specification change:

1. Add a JDK Implementation specific property for LSSerializer as follows that will be supported by the DOMConfiguration interface, refer to LSSerializer::getDomConfig()

   Name: http://www.oracle.com/xml/jaxp/properties/isStandalone.

   Definition: indicates that the serializer should treat the output as a standalone document. The property can be used to ensure a newline is written after the XML declaration when the property “format-pretty-print” is set to true. Unlike the property “xml-declaration”, this property does not have an effect on whether an XML declaration should be written out.

   Value: a boolean, false by default.

2. Add a System property as follows

   Name: jdk.xml.isStandalone.

   Definition: functions exactly the same as the LSSerializer property "http://www.oracle.com/xml/jaxp/properties/isStandalone". The system property should be set prior to creating the serializer, and may be cleared afterwards.

   Value: a String, the system property is true only if it is "true" and false otherwise.

Documentation:

JDK16u and Oracle JDK11u

Add an implementation note for the isStandalone property to java.xml module-summary (java.xml/module-info.java). The javadoc will be exactly the same as described in the JDK17 CSR (https://bugs.openjdk.java.net/browse/JDK-8249867). A link is provided below for convenience:

http://cr.openjdk.java.net/~joehw/jdk17/8249867/spec_04/java.xml/module-summary.html

Oracle JDK8u and Oracle JDK7u

The new property will be documented in the release notes with the same content as in the release note subtask (https://bugs.openjdk.java.net/browse/JDK-8259502).