RFR: 8231640: (prop) Canonical property storage [v21]

[Jaikiran Pai]

On Wed, 22 Sep 2021 10:05:04 GMT, Alan Bateman <alanb at openjdk.org> wrote:

>> Jaikiran Pai has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Roger's suggestion to reword the implSpec text
>
> src/java.base/share/classes/java/lang/System.java line 766:
> 
>> 764:      * <tr><th scope="row">{@systemProperty java.properties.date}</th>
>> 765:      *     <td>Text for the comment that must replace the default date comment
>> 766:      *     written out by {@code Properties.store()} methods <em>(optional)</em> </td></tr>
> 
> To date, the table in getProperties has listed the supported system properties that the runtime makes available to applications. It hasn't historically listed the many other standard properties that can be set on the command line. So I'm sure about adding this one to the table as it opens the door to expanding the table to all the other system properties that are documented elsewhere in the API docs. Note that javadoc creates a table of system properties from usages of `@systemProperty` so there is already a more complete table in the javadoc build.

After this change to include this property in System::getProperties() javadoc was added, there have been inputs (here and on the CSR) which suggest that we probably shouldn't include it here. I've now updated this PR to revert this specific change.

> src/java.base/share/classes/java/util/Properties.java line 928:
> 
>> 926:             // in the natural order of their key. Else, we consider that the subclassed implementation may potentially
>> 927:             // have returned a differently ordered entries and so we just use the iteration order of the returned instance.
>> 928:             if (entries instanceof Collections.SynchronizedSet<?> ss
> 
> Would you mind re-formatting the comment to keep the line length a bit more consistent with the rest of the code, is's just a bit annoying to have it wrapping.

Done. I've updated the PR to reduce the line length of that code comment.

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

PR: https://git.openjdk.java.net/jdk/pull/5372