JDK-8265252 : Implementation Specific Properties: change prefix, plus add existing properties
  • Type: CSR
  • Component: xml
  • Sub-Component: jaxp
  • Priority: P4
  • Status: Closed
  • Resolution: Approved
  • Fix Versions: 17
  • Submitted: 2021-04-15
  • Updated: 2022-01-25
  • Resolved: 2021-05-17
Related Reports
CSR :  
Relates :  
Description
Summary
-------

Changes the prefix in the `Naming Convention` to `jdk.xml`; Adds documentation for a few existing features and properties to the module summary.

Problem
-------

The documentation for Implementation Specific Features and Properties defined a URL-style prefix, that is, `http://www.oracle.com/xml/jaxp/properties/` for properties, and `http://www.oracle.com/xml/jaxp/features/` for features. These prefixes are long and also dependent on domain names. A better prefix would have been `jdk.xml` that was already used for the properties added since JDK 9.

As Implementation Specific Features and Properties are now documented in the module summary, a few existing properties need to be added to complete the project.

Solution
--------

Change the prefix in the `Naming Convention` from `http://www.oracle.com/xml/jaxp/properties/` and `http://www.oracle.com/xml/jaxp/features/` to `jdk.xml`.

Add documentation for a few existing properties to the module summary.

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

1. Prefix

    In section `Naming Convention`, change the prefix from `http://www.oracle.com/xml/jaxp/properties/` for properties and `http://www.oracle.com/xml/jaxp/features/` for features to `jdk.xml`.
<p>

2. Add the followings to table `Implementation Specific Properties`

    `cdataChunkSize` -- definition copied from the original specification.

    `extensionClassLoader` -- definition copied from the original specification.
<p>

3. Add table `Implementation Specific Features` with the following features

    `enableExtensionFunctions` -- definition copied from the original specification.

    `overrideDefaultParser` -- definition copied from the original specification. To match the style of `enableExtensionFunctions` above, in the `Value` column, changed `a boolean` to `true or false` and started the sentence with `True` instead of Setting it to true.

    `resetSymbolTable` -- definition copied from the original specification. To match the style of `enableExtensionFunctions` above, in the `Value` column, changed `a boolean` to `true or false` and started the sentence with `True` instead of Setting it to true.
<p>

4. Notes for the tables

    Added links to the notes in Features and Properties tables as both tables share the same notes.
<p>

5. `DatatypeFactory` Lookup Mechanism

   Added `DatatypeFactory` to the JAXP Lookup Mechanism. See the first row in table `JAXP Factories`.


----

Spec: http://cr.openjdk.java.net/~joehw/jdk17/8265248/spec_01/java.xml/module-summary.html

Attachment: 8265248_spec_01.zip

----
Update 02: add column `How to set the feature` to table `Processors`

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

Attachment: 8265248_spec_02.zip

----
Update 03: 

  1. Changed the alignment for column `How to set properties` and `How to set Features` in table `Processors` from center to left justified;

  2. Changed the title for the column `Name` in table `Implementation Specific Properties` and `Implementation Specific Features` to `Full Name`; Added `@systemProperty` tag to all but `extensionClassLoader` which does not have a corresponding System Property, that allows the properties to be added to the search index (try putting one, e.g. 'jdk.xml.entityExpansionLimit`, in the search box. The result shall show, leading to the property).

  3. Changed the javadoc for DatatypeFactory::newInstance to be exactly the same as other factories, such as DocumentBuilderFactory::newInstance, pointing to the Lookup Mechanism in the module summary.

Spec: http://cr.openjdk.java.net/~joehw/jdk17/8265248/spec_03/java.xml/module-summary.html

Attachment: 8265248_spec_03.zip

----
Update 04

Added a table `Legacy Property Names` with a list of legacy property names to indicate that the old names will continue to be supported.

Spec: http://cr.openjdk.java.net/~joehw/jdk17/8265248/spec_04/java.xml/module-summary.html

Attachment: 8265248_spec_04.zip

----
Update 05

Clarify that the new one takes precedence if both the new and legacy properties are set; Deprecate the legacy properties.

Spec: http://cr.openjdk.java.net/~joehw/jdk17/8265248/spec_05/java.xml/module-summary.html

Attachment: 8265248_spec_05.zip
Comments
Moving to Approved.
17-05-2021

Thanks for the update. Suggestion for additional clarification: if both new and legacy properties are set, the new one takes precedence. I also recommend stating whether or not the legacy property form is considered deprecated and may be removed at some point. Moving to Provisional.
12-05-2021

So, what happens, if anything, if the old oracle.com settings are used? Nothing? Overridden if the jdk.xml equivalent is set? etc? Moving to Provisional, not Approved.
10-05-2021

Release notes: JDK-8261861
10-05-2021