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

[Joe Wang]

On Mon, 13 Mar 2023 09:58:51 GMT, Alan Bateman <alanb at openjdk.org> wrote:

>> 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`.

I'll rewrite the "configuration file" section in the module description to include a general override procedure to discuss "scope and order" and have these properties point to that.

Thanks for the pointer, that link to the module-summary looks cleaner.

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

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