RFR: 8303530: Add system property for custom JAXP configuration file [v2]

[Alan Bateman]

On Sat, 11 Mar 2023 05:34:39 GMT, Joe Wang <joehw at openjdk.org> wrote:

>> Add a system property, jdk.xml.config.file, to return the path to a custom JAXP configuration file. The current configuration file, jaxp.properties, that the JDK supports will become the default configuration file.
>> 
>> CSR: https://bugs.openjdk.org/browse/JDK-8303531
>> 
>> Tests: XML SQE and JCK tests passed.
>
> Joe Wang has updated the pull request incrementally with one additional commit since the last revision:
> 
>   clean up tests; fix copy&paste error.

src/java.xml/share/classes/javax/xml/XMLConstants.java line 247:

> 245:          * <a href="../../module-summary.html#ConfigurationFile">configuration file</a>.
> 246:          * If the file exists and the system property is specified, its value will
> 247:          * be used to override the default of the property.

This follows the documenting of the equivalent system property but that text doesn't say what it overrides. I think it overrides the default value but does not override programmatic use. The new text documents that the configuration file can be used. It is a bit clearer that it overrides the default value but doesn't say anything about programmatic use. The reader will also wonder if the system property overrides the configuration file or the other way around. So I think my point is that the precedent needs to clearly documented, maybe it document the ordering in one place and have each property reference it. In the case of XMLConstants, then it might also be simpler to put the text in the class description rather than having it repeated in every property - maybe experiment with that to see if it helps or not.

In passing, I assume these links can be use `{@docRoot}/java.xml/module-summary.html`.

src/java.xml/share/classes/javax/xml/catalog/CatalogFeatures.java line 171:

> 169:  * system properties, and
> 170:  * <a href="../../../module-summary.html#ConfigurationFile">configuration file</a>,
> 171:  * with a preference in the same order.

You may need to clarify the preference order a bit further, is is left-to-right or right-to-left in this list?

-------------

PR: https://git.openjdk.org/jdk/pull/12985