RFR: 8358530: enhanced Properties#list javadoc

[Justin Lu]

On Tue, 20 May 2025 16:03:14 GMT, cagliostro92 <duke at openjdk.org> wrote:

> Trivial PR to enhance Javadoc for the `Properties#list` method, which has cost me some debugging time.

It does appear true that a `ClassCastException` is thrown if a value is not a String for `Properties.list(PrintWriter)` and the behavior looks to be long-standing. A minimal update to make this apparent seems appropriate. 

I filed the following issue: [JDK-8358530](https://bugs.openjdk.org/browse/JDK-8358530) for this PR. I can create a CSR (to cover the specification changes) for you when the wording changes are finalized.

The class description wording,

> the call to the propertyNames or list method will fail if it is called on a "compromised" Properties object that contains a non-String key. 

should also probably get an update as well.

src/java.base/share/classes/java/util/Properties.java line 1240:

> 1238:      *
> 1239:      * @param   out   an output stream.
> 1240:      * @throws  ClassCastException if either a key or a value

This change can be applied to `Properties.list(PrintStream out)` as well.

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

Changes requested by jlu (Committer).

PR Review: https://git.openjdk.org/jdk/pull/25334#pullrequestreview-3011894003
PR Review Comment: https://git.openjdk.org/jdk/pull/25334#discussion_r2201789369