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

Move javadoc for the lookup mechanism to module summary

    XMLWordPrintable

    Details

    • Type: CSR
    • Status: Closed
    • Priority: P4
    • Resolution: Approved
    • Fix Version/s: 17
    • Component/s: xml
    • Labels:
      None
    • Subcomponent:
    • Compatibility Risk:
      minimal
    • Compatibility Risk Description:
      No compatibility risk. This is a doc-only change.
    • Interface Kind:
      Java API
    • Scope:
      SE

      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

      1. The JAXP Lookup Mechanism in module summary

      1.1 Jaxp Factories
      Added a table "Jaxp Factories" with a list of factories that support the mechanism.

      1.2 jaxp.properties and stax.properties
      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.

      1.3 The Lookup Procedure
      The Procedure is identical to the original javadoc in jaxp factories except the followings:

      - System Properties are listed in the Jaxp Factories table;
      - The previous jaxp.properties and/or stax.properties descriptions are replaced with links to the aforementioned separated javadoc for these configuration files;
      - The procedures are identical to all factories except for the SchemaFactory and XPathFactory where specific statements are added under their names.


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


      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.

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              joehw Joe Wang
              Reporter:
              joehw Joe Wang
              Reviewed By:
              Iris Clark, Lance Andersen
              Votes:
              0 Vote for this issue
              Watchers:
              1 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved: