8360575: java.util.Properties.list() methods trim each value to 37 characters in the listed output #26018

jaikiran · 2025-06-27T13:20:35Z

Can I please get a review of this doc-only change which proposes to clarify the current implementation of the java.util.Properties.list(...) methods?

As noted in https://bugs.openjdk.org/browse/JDK-8360575, the current implementation trims each value to a size of 37 when printing out the value. This behaviour isn't documented by these methods. The change in this PR adds an @implNote to make a mention of this current behaviour.

Progress

Change must be properly reviewed (1 review required, with at least 1 Reviewer)
Change must not contain extraneous whitespace
Commit message must refer to an issue
Change requires a CSR request matching fixVersion 26 to be approved (needs to be created)

Issue

JDK-8360575: java.util.Properties.list() methods trim each value to 37 characters in the listed output (Bug - P4)

Reviewers

Andy Goryachev (@andy-goryachev-oracle - no project role) 🔄 Re-review required (review applies to 049e43ea)

Reviewing

Using git

Checkout this PR locally:
$ git fetch https://git.openjdk.org/jdk.git pull/26018/head:pull/26018
$ git checkout pull/26018

Update a local copy of the PR:
$ git checkout pull/26018
$ git pull https://git.openjdk.org/jdk.git pull/26018/head

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 26018

View PR using the GUI difftool:
$ git pr show -t 26018

Using diff file

Download this PR as a diff file:
https://git.openjdk.org/jdk/pull/26018.diff

Using Webrev

Link to Webrev Comment

…aracters in the listed output

bridgekeeper · 2025-06-27T13:21:21Z

👋 Welcome back jpai! A progress list of the required criteria for merging this PR into master will be added to the body of your pull request. There are additional pull request commands available for use with this pull request.

openjdk · 2025-06-27T13:22:07Z

❗ This change is not yet ready to be integrated.
See the Progress checklist in the description for automated requirements.

openjdk · 2025-06-27T13:22:42Z

@jaikiran The following label will be automatically applied to this pull request:

core-libs

When this pull request is ready to be reviewed, an "RFR" email will be sent to the corresponding mailing list. If you would like to change these labels, use the /label pull request command.

mlbridge · 2025-06-27T13:27:46Z

Webrevs

AlanBateman · 2025-06-27T13:41:11Z

Are you sure you want to describe the format, even in an implNote? Although the string representation probably hasn't changed in 25+ years, it's not something that anything should become dependent on. Updating the method description to include an example of how to print out the properties and their values might be more useful. We also need to think about whether to just deprecate this method (ThreadGroup.list too).

jaikiran · 2025-06-27T14:02:02Z

Are you sure you want to describe the format, even in an implNote? Although the string representation probably hasn't changed in 25+ years, it's not something that anything should become dependent on.

I wasn't too sure how much detail to include. I've now trimmed it down to just note that the values are trimmed to 37 characters.

Updating the method description to include an example of how to print out the properties and their values might be more useful.

I've updated the PR to include a snippet which shows an alternate way of listing the Properties to a PrintStream or PrintWriter.

We also need to think about whether to just deprecate this method (ThreadGroup.list too).

Would you suggest doing it as part of the current changes or as a separate task? I can create follow up issues if it's OK to do that separately.

RogerRiggs · 2025-06-27T14:10:28Z

History note from the commit added by avh:

"Added some debugging methods.

jdk/src/share/classes/java/util/Properties.java 1.8 Tue 13-06-1995 18:04:34"

It does not seem to be intended as anything but a debugging aid.

andy-goryachev-oracle · 2025-06-27T14:31:53Z

src/java.base/share/classes/java/util/Properties.java

+     *      p.forEach((k, v) -> out.println(k + "=" + v));
+     * }
+     *
+     * @param   out   a PrintStream


suggestion: (here and L1263) "the output PrintStream"

andy-goryachev-oracle · 2025-06-27T14:33:30Z

src/java.base/share/classes/java/util/Properties.java

+     * this method writes only the first 37 characters of that value
+     * followed by 3 dot characters.
+     * <p>
+     * An alternative for listing the {@code Properties} to a {@code PrintStream} is:


suggestion:
``
An alternative for listing the {@code Properties} to a {@code PrintStream} without truncation is:

Good point. I've now updated the PR with this text.

andy-goryachev-oracle

I am not a JDK reviewer, but it looks good to me. Thank you!

RogerRiggs · 2025-06-27T15:27:45Z

You'll need a CSR since you're changing spec text. (output stream -> PrintStream) and the new ImplNote.
It might be worth considering this list() method should be deprecated.
And/or document as being useful for debugging only.

Consider proposing better replacement. But that's a bigger (possibly more satisfying task)

andy-goryachev-oracle · 2025-06-27T15:31:04Z

You'll need a CSR since you're changing spec text.

isn't this PR a mere clarification, as opposed to the spec change? Or any change is a spec change in the JDK project? (openjfx allows for minor javadoc corrections without a CSR)

RogerRiggs · 2025-06-27T15:34:59Z

isn't this PR a mere clarification, as opposed to the spec change? Or any change is a spec change in the JDK project? (openjfx allows for minor javadoc corrections without a CSR)

For JDK, (nearly) all changes to the javadoc require a CSR, if the changes the published form.

AlanBateman · 2025-06-28T07:01:29Z

src/java.base/share/classes/java/util/Properties.java

-     * @param   out   an output stream.
+     * @implNote If any property's value is greater than 40 characters then
+     * this method writes only the first 37 characters of that value
+     * followed by 3 dot characters.


I don't think the note needs to that specific. I think it need only say that the implementation truncates the output for very long property values.

Hello Alan, I think not noting the character count which determines the truncation would lead to questions about what "very long property values" are. However, this is a method which is specified to be for debug purposes only and I see that there's a suggestion to deprecate these methods. So I have gone ahead and updated this text to follow your suggestion. I'll respond to the deprecation proposal separately in this PR.

jaikiran · 2025-06-30T06:03:45Z

I see that both Alan and Roger suggest that we consider deprecating these methods (and the one in ThreadGroup). I was thinking of doing that separately but looking at the text being proposed here, I don't see much value in just integrating this @implNote and then coming back to this to deprecate these methods. Unless there are objections, I'll go ahead and repurpose this PR to deprecate these methods.

jaikiran · 2025-06-30T06:03:50Z

/csr needed

openjdk · 2025-06-30T06:04:34Z

@jaikiran has indicated that a compatibility and specification (CSR) request is needed for this pull request.

@jaikiran please create a CSR request for issue JDK-8360575 with the correct fix version. This pull request cannot be integrated until the CSR request is approved.

liach · 2025-07-13T14:20:22Z

src/java.base/share/classes/java/util/Properties.java

+     *      Properties p = ...
+     *      PrintWriter out = ...
+     *      // list the properties to PrintWriter
+     *      p.forEach((k, v) -> out.println(k + "=" + v));


Should our example recommend using toString as a utility to obtain a debug string instead, as it performs no truncation?

Using toString() will be harder to read; as proposed each property is on a separate line.

RogerRiggs

Looks good.

RogerRiggs · 2025-07-14T17:05:31Z

src/java.base/share/classes/java/util/Properties.java

+     *      Properties p = ...
+     *      PrintWriter out = ...
+     *      // list the properties to PrintWriter
+     *      p.forEach((k, v) -> out.println(k + "=" + v));


Using toString() will be harder to read; as proposed each property is on a separate line.

jmehrens · 2025-07-15T04:34:35Z

If I understand the code, Properties::forEach doesn't walk up the default Properties. Properties::list walks the defaults. To get the same keys you would have to use
p.stringPropertyNames() and p.getProperty to fetch the value.

RogerRiggs

The example should be updated as suggested.

RogerRiggs · 2025-07-15T21:37:43Z

The example could get complicated; depending on what output is desired. The existence of a separate "default" Properties object adds complexity.
For simplicity, I'd print the direct map elements and then recursively print the default Propertys.
No flattening of the property names and no sorting.
Keep the example simple, leave the embellishments to whoever copies the example.
Don't try to exactly reproduce the existing method.

8360575: java.util.Properties.list() methods trim each value to 37 ch…

c898609

…aracters in the listed output

openjdk bot added the rfr Pull request is ready for review label Jun 27, 2025

openjdk bot added the core-libs [email protected] label Jun 27, 2025

Alan's review - limit the details in implNote

d276ad0

andy-goryachev-oracle reviewed Jun 27, 2025

View reviewed changes

Andy's review suggestions

049e43e

andy-goryachev-oracle approved these changes Jun 27, 2025

View reviewed changes

AlanBateman reviewed Jun 28, 2025

View reviewed changes

Alan's review - no need to state the number of characters

df9c7ca

openjdk bot added the csr Pull request needs approved CSR before integration label Jun 30, 2025

liach reviewed Jul 13, 2025

View reviewed changes

RogerRiggs approved these changes Jul 14, 2025

View reviewed changes

RogerRiggs suggested changes Jul 15, 2025

View reviewed changes

8360575: java.util.Properties.list() methods trim each value to 37 characters in the listed output #26018

Are you sure you want to change the base?

8360575: java.util.Properties.list() methods trim each value to 37 characters in the listed output #26018

Conversation

jaikiran commented Jun 27, 2025 • edited by openjdk bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Progress

Issue

Reviewers

Reviewing

Uh oh!

bridgekeeper bot commented Jun 27, 2025

Uh oh!

openjdk bot commented Jun 27, 2025

Uh oh!

openjdk bot commented Jun 27, 2025

Uh oh!

mlbridge bot commented Jun 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Webrevs

Uh oh!

AlanBateman commented Jun 27, 2025

Uh oh!

jaikiran commented Jun 27, 2025

Uh oh!

RogerRiggs commented Jun 27, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

andy-goryachev-oracle left a comment

Choose a reason for hiding this comment

Uh oh!

RogerRiggs commented Jun 27, 2025

Uh oh!

andy-goryachev-oracle commented Jun 27, 2025

Uh oh!

RogerRiggs commented Jun 27, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jaikiran commented Jun 30, 2025

Uh oh!

jaikiran commented Jun 30, 2025

Uh oh!

openjdk bot commented Jun 30, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

RogerRiggs left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jmehrens commented Jul 15, 2025

Uh oh!

RogerRiggs left a comment

Choose a reason for hiding this comment

Uh oh!

RogerRiggs commented Jul 15, 2025

Uh oh!

Uh oh!

jaikiran commented Jun 27, 2025 •

edited by openjdk bot

Loading

mlbridge bot commented Jun 27, 2025 •

edited

Loading