JDK-8262427 : Add documentation for the XML processing limits in java.xml module summary
  • Type: CSR
  • Component: xml
  • Sub-Component: jaxp
  • Priority: P4
  • Status: Closed
  • Resolution: Approved
  • Fix Versions: 17
  • Submitted: 2021-02-25
  • Updated: 2021-03-01
  • Resolved: 2021-03-01
Related Reports
CSR :  
Description
Summary
-------

Add documentation for the XML processing limits in java.xml module summary

Problem
-------

The XML processing limits were previously documented in Java Tutorials (https://docs.oracle.com/javase/tutorial/jaxp/limits/index.html) and Guide (https://docs.oracle.com/javase/8/docs/technotes/guides/security/jaxp/jaxp.html). With the addition of implementation note via JDK-8260858, it would be good to add the documentation into the java.xml module summary.

Solution
--------

Add the documentation into the java.xml module summary.

In the previous documentation, the table that currently contains only `Properties` was named `Features and Properties`. Considering that we will be adding `Features` that would have a different prefix, the name of table shall be changed to `Implementation Specific Properties`. 

Specification
-------------

1. Copy the definitions in <a href="https://docs.oracle.com/javase/tutorial/jaxp/limits/limits.html">section Processing Limit Definitions</a> of the Java tutorial into the table `Implementation Specific Properties`;

2. Change the name of the table from `Features and Properties` to `Implementation Specific Properties`;

3. Change the description of the table to indicate that the list of the properties is not exhaustive by replacing the statement in spec_02:

        The table below lists Implementation Specific Properties supported by the JDK. 

    with the following in spec_3:

        The Implementation Specific Features and Properties reflect JDK's choice to manage the limitations
        on resources while complying with the API specification, or allow applications to alter behaviors 
        beyond those required by the standards.

        The table below lists the Implementation Specific Properties currently supported by the JDK. 
        More properties may be added in the future if necessary. 


4. Add the following to note [3] of the table at the end of the statement:

        If the type is Integer, the value of the System Property is the String representation of the 
        value (e.g. "64000" for entityExpansionLimit). 


Specification attachment: 8261670_spec_03.zip
Convenient link: http://cr.openjdk.java.net/~joehw/jdk17/8261670/spec_03/java.xml/module-summary.html



Comments
Moving to Approved.
01-03-2021

Moving to Provisional, not Approved. To accommodate the potential desire to add properties during update releases, I'd like to see wording noting that such additions are possible. In other words, the list of supported properties is not necessarily exhaustive.
01-03-2021

Thanks Joe. Added Item 3 in the specification section.
01-03-2021