RFR: 8373186: Improve readability of core reflection toString specifications
Partial implementation of a spec refactoring to get some feedback before writing similar changes for other core reflection types. ------------- Commit messages: - JDK-8373186: Improve readability of core reflection toString specifications Changes: https://git.openjdk.org/jdk/pull/28688/files Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=28688&range=00 Issue: https://bugs.openjdk.org/browse/JDK-8373186 Stats: 33 lines in 1 file changed: 9 ins; 6 del; 18 mod Patch: https://git.openjdk.org/jdk/pull/28688.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/28688/head:pull/28688 PR: https://git.openjdk.org/jdk/pull/28688
On Sat, 6 Dec 2025 21:35:57 GMT, Joe Darcy <darcy@openjdk.org> wrote:
Partial implementation of a spec refactoring to get some feedback before writing similar changes for other core reflection types.
src/java.base/share/classes/java/lang/reflect/Field.java line 360:
358: * private int java.io.FileDescriptor.fd 359: * public static java.util.List Foo.bar 360: * </pre>
Having such examples here means this method has a specified output that users can parse. We should move this to some non-normative section like an implementation note. (Don't know why github mobile didn't capture my comment before, I already commented yesterday) ------------- PR Review Comment: https://git.openjdk.org/jdk/pull/28688#discussion_r2596780908
On Mon, 8 Dec 2025 01:14:19 GMT, Chen Liang <liach@openjdk.org> wrote:
Partial implementation of a spec refactoring to get some feedback before writing similar changes for other core reflection types.
src/java.base/share/classes/java/lang/reflect/Field.java line 360:
358: * private int java.io.FileDescriptor.fd 359: * public static java.util.List Foo.bar 360: * </pre>
Having such examples here means this method has a specified output that users can parse. We should move this to some non-normative section like an implementation note.
(Don't know why github mobile didn't capture my comment before, I already commented yesterday)
Hmm. it is possible to move the examples so they are more clearly _informative_ rather than _normative_. As a counterpoint, the toString() spec for java.lang.annotation.Annotation states:
Returns a string representation of this annotation. The details of the representation are implementation-dependent, but the following may be regarded as typical:
` @com.example.Name(first="Duke", middle="of", last="Java")`
Developers used this string successfully for informative purposes, even though the exact details have been changed (improved and corrected) a number of times over the years. ------------- PR Review Comment: https://git.openjdk.org/jdk/pull/28688#discussion_r2600548329
On Sat, 6 Dec 2025 21:35:57 GMT, Joe Darcy <darcy@openjdk.org> wrote:
Partial implementation of a spec refactoring to get some feedback before writing similar changes for other core reflection types.
src/java.base/share/classes/java/lang/reflect/Field.java line 349:
347: 348: /** 349: * {@return a string describing this {@code Field}}
Field::toString has been specified this way since JDK 1.1 and we have to assume there are frameworks or libraries that would break if we were ever change the format of the String representation. Would it be possible to put more context for the proposal in the JBS or PR? I think I'm mostly trying to understand if this is just about readability or whether an incompatible change to the string representation might follow. ------------- PR Review Comment: https://git.openjdk.org/jdk/pull/28688#discussion_r2597701327
On Mon, 8 Dec 2025 09:06:13 GMT, Alan Bateman <alanb@openjdk.org> wrote:
Partial implementation of a spec refactoring to get some feedback before writing similar changes for other core reflection types.
src/java.base/share/classes/java/lang/reflect/Field.java line 349:
347: 348: /** 349: * {@return a string describing this {@code Field}}
Field::toString has been specified this way since JDK 1.1 and we have to assume there are frameworks or libraries that would break if we were ever change the format of the String representation. Would it be possible to put more context for the proposal in the JBS or PR? I think I'm mostly trying to understand if this is just about readability or whether an incompatible change to the string representation might follow.
I don't have any implementation changes planned, but if there are new kinds of things added, I prefer to avoid treating the toString() method as a home for a context free grammar to provide all the necessary information about the item. ------------- PR Review Comment: https://git.openjdk.org/jdk/pull/28688#discussion_r2600550124
On Sat, 6 Dec 2025 21:35:57 GMT, Joe Darcy <darcy@openjdk.org> wrote:
Partial implementation of a spec refactoring to get some feedback before writing similar changes for other core reflection types.
src/java.base/share/classes/java/lang/reflect/Field.java line 349:
347: 348: /** 349: * {@return a string describing this {@code Field}}
I don't see a compelling reason to backtrack on the format of toString. Its likely to break some application or description of the field to a user. src/java.base/share/classes/java/lang/reflect/Field.java line 365:
363: * Specific information about {@linkplain #getModifiers() 364: * modifiers} or other aspects of the field should be retrieved 365: * using methods for that purpose.
This is needlessly vague and gives an opportunity to reinforce the preferred order of modifiers. ------------- PR Review Comment: https://git.openjdk.org/jdk/pull/28688#discussion_r2600352283 PR Review Comment: https://git.openjdk.org/jdk/pull/28688#discussion_r2600354349
On Mon, 8 Dec 2025 22:27:21 GMT, Roger Riggs <rriggs@openjdk.org> wrote:
Partial implementation of a spec refactoring to get some feedback before writing similar changes for other core reflection types.
src/java.base/share/classes/java/lang/reflect/Field.java line 349:
347: 348: /** 349: * {@return a string describing this {@code Field}}
I don't see a compelling reason to backtrack on the format of toString. Its likely to break some application or description of the field to a user.
I think the reason to change the format is some future modifiers, like ACC_STRICT_INIT, won't get printed. ------------- PR Review Comment: https://git.openjdk.org/jdk/pull/28688#discussion_r2600533536
On Mon, 8 Dec 2025 23:44:02 GMT, Chen Liang <liach@openjdk.org> wrote:
src/java.base/share/classes/java/lang/reflect/Field.java line 349:
347: 348: /** 349: * {@return a string describing this {@code Field}}
I don't see a compelling reason to backtrack on the format of toString. Its likely to break some application or description of the field to a user.
I think the reason to change the format is some future modifiers, like ACC_STRICT_INIT, won't get printed.
Also, it helps avoid "attractive nuisance" questions like "how does the toString() of a bridge method indicate it is a bridge method"? (There is no such indication in the toString output, other than indirectly via the return type, but there is a Method.isBridge() predicate.) ------------- PR Review Comment: https://git.openjdk.org/jdk/pull/28688#discussion_r2600613169
On Mon, 8 Dec 2025 22:28:19 GMT, Roger Riggs <rriggs@openjdk.org> wrote:
Partial implementation of a spec refactoring to get some feedback before writing similar changes for other core reflection types.
src/java.base/share/classes/java/lang/reflect/Field.java line 365:
363: * Specific information about {@linkplain #getModifiers() 364: * modifiers} or other aspects of the field should be retrieved 365: * using methods for that purpose.
This is needlessly vague and gives an opportunity to reinforce the preferred order of modifiers.
I think you can probably refer to the JLS/JVMS difference, noting JVM (classfile) information may be missing from this string output, such as ACC_SYNTHETIC or future ACC_STRICT_INIT. ------------- PR Review Comment: https://git.openjdk.org/jdk/pull/28688#discussion_r2730183925
On Sat, 6 Dec 2025 21:35:57 GMT, Joe Darcy <darcy@openjdk.org> wrote:
Partial implementation of a spec refactoring to get some feedback before writing similar changes for other core reflection types.
src/java.base/share/classes/java/lang/reflect/Field.java line 352:
350: * 351: * The string includes information about access modifiers of the 352: * field, the type of the field, the type declaring the field,
Suggestion: * field, the type of the field, the class or interface declaring the field, We might also note that the access modifiers might not be comprehensive. Since you link "modifiers" below, I wonder if it's better for us to link up here instead, where we can link to more proper getters like accessFlags, getType, getDeclaringClass, getName. ------------- PR Review Comment: https://git.openjdk.org/jdk/pull/28688#discussion_r2730178443
On Sat, 6 Dec 2025 21:35:57 GMT, Joe Darcy <darcy@openjdk.org> wrote:
Partial implementation of a spec refactoring to get some feedback before writing similar changes for other core reflection types.
This pull request has been closed without being integrated. ------------- PR: https://git.openjdk.org/jdk/pull/28688
participants (5)
-
Alan Bateman
-
Chen Liang
-
duke
-
Joe Darcy
-
Roger Riggs