JDK-8259704 : DOM LSSerializer control of newline after XML header
  • Type: CSR
  • Component: xml
  • Sub-Component: jaxp
  • Priority: P3
  • Status: Closed
  • Resolution: Approved
  • Fix Versions: 7-pool,8-pool,11-pool,16-pool
  • Submitted: 2021-01-13
  • Updated: 2021-03-04
  • Resolved: 2021-02-08
Related Reports
CSR :  
CSR :  
Relates :  
Description
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.


 1. 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).

Comments
Moving to Approved for the update release trains in question. Filing a separate issues for 7u and 8u is not necessary in this case.
08-02-2021

If a change has a CSR for a feature release, it generally also needs a CSR to be backported to an update release. For 11u and 16u, the same JDK-specific system property could be described in the module-info file; although the change may not be reflected in the on-line docs right away as the docs are not always regenerated. Please Finalize this request when it is ready for the second phase of review.
29-01-2021

Hi Kiran, As Joe said above, we need to note the difference in the Solution section, sth. like: The property was initially introduced in JDK 17 where it was documented in module-info. In JDK 7 and 8, it will be described in the release notes. In the Solution section: remove the duplicate sentence in the 2nd paragraph, e.g. "Add a corresponding System..." In the Specification section: change the property name from "isStandalone" to "http://www.oracle.com/xml/jaxp/properties/isStandalone"; In the definition for the system property, change "jdk-is-standalone" to "isStandalone". For JDK 11, 16, I'm not sure whether we'd need a CSR, can we backport without a CSR?
29-01-2021

Moving to Provisional, not Approved. [~kravikumar], please have an engineer like [~joehw] review this request before Finalizing and note any differences between this backport CSR and the CSR for the main issue.
29-01-2021

[~kravikumar], please resubmit this CSR for the backports after the changes in the main JDK 17 issue are finalized.
15-01-2021