JDK-8263611 : Move javadoc for the lookup mechanism to module summary
  • Type: CSR
  • Component: xml
  • Sub-Component: jaxp
  • Priority: P4
  • Status: Closed
  • Resolution: Approved
  • Fix Versions: 17
  • Submitted: 2021-03-15
  • Updated: 2021-03-23
  • Resolved: 2021-03-23
Related Reports
CSR :  
Description
Summary
-------

Consolidate and move the description for the JAXP Lookup Mechanism to module summary, and update the factories accordingly.

Problem
-------

The JAXP Lookup Mechanism, or the Lookup Procedure were documented in each and every factory, mostly identical and repetitive with a few exceptions. As we add javadoc to the module summary and also refer to elements of the Procedure, it would be a good opportunity to consolidate and move the javadoc to the module summary.

Solution
--------

Move the javadoc for the Lookup Mechanism to the module summary

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

Attached specdiff_02.zip and spec_02.zip. Note that the specdiff tool did not generate diff for the module summary. Although it can be reached from a link in any one of the changed factory methods, the spec_01 is added for a better html view.

Convenient links:
specdiff: http://cr.openjdk.java.net/~joehw/jdk17/8261673/specdiff_02/overview-summary.html

spec: http://cr.openjdk.java.net/~joehw/jdk17/8261673/spec_02/java.xml/module-summary.html

**Summary of Changes**
<p>
1. The JAXP Lookup Mechanism in module summary<br><br>
1.1 Jaxp Factories<br>
    Added a table "Jaxp Factories" with a list of factories that support the mechanism.<br><br>
1.2 jaxp.properties and stax.properties<br>
    Separated the javadoc for jaxp.properties and stax.properties from the Lookup Procedure so that they can be referenced from the Procedure and other parts of the document.<br><br>
1.3 The Lookup Procedure<br>
    The Procedure is identical to the original javadoc in jaxp factories except the followings:<br><br>
 - System Properties are listed in the Jaxp Factories table;<br>
 - The previous jaxp.properties and/or stax.properties descriptions are replaced with links to the
   aforementioned separated javadoc for these configuration files; <br>
 - The procedures are identical to all factories except for the
   SchemaFactory and XPathFactory where specific statements are added
   under their names.

<br>
2. Factories<br>
    For all factories that support the mechnism, the original javadoc for the Procedure is replaced with a link to that in the module summary.

<br>
3. Refer to jaxp.properties in the implNote
   A reference to jaxp.properties in implNote: `Implementation Specific Features and Properties` is replaced with a link to the jaxp.properties section above. Previously, it was referring to the lookup procedure in SAXParserFactory.


Comments
Moving to Approved.
23-03-2021