Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8259352

Documenting the implementation specific features and properties

    XMLWordPrintable

    Details

    • Type: CSR
    • Status: Closed
    • Priority: P3
    • Resolution: Approved
    • Fix Version/s: 17
    • Component/s: xml
    • Labels:
      None
    • Subcomponent:
    • Compatibility Risk:
      minimal
    • Compatibility Risk Description:
      No compatibility risk. The proposed change is to add an implementation-only property that by default will do nothing. No change to the public interface.
    • Interface Kind:
      System or security property
    • Scope:
      JDK

      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.

      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

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              joehw Joe Wang
              Reporter:
              webbuggrp Webbug Group
              Reviewed By:
              Roger Riggs, Stuart Marks
              Votes:
              0 Vote for this issue
              Watchers:
              2 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved: