RFR: 8275013: Improve discussion of serialization method declarations in java.io.Object{Input, Output}Stream
The java.io.ObjectInputStream and java.io.ObjectOuputStream classes are part of the serialization feature. These classes contain brief descriptions of some of the methods serializable classes can define to interact with the serialization mechanism, readObject, readObjectNoData, and writeObject. These descriptions are not entirely consistent with one another and at least one is arguably misleading. This PR makes the brief discussion the same in both classes and addresses the misleading point: the throws clauses of the methods will not effect whether or not the methods are found by serialization, but throwing unchecked exceptions not declared in the standard signatures is ill-advised. (The current implementation looks up the methods by name using core reflection; the method modifiers are checked to match but the throws information is not.) Please also review the corresponding CSR : https://bugs.openjdk.java.net/browse/JDK-8275014 ------------- Commit messages: - 8275013: Improve discussion of serialization method declarations in java.io.Object{Input, Output}Stream Changes: https://git.openjdk.java.net/jdk/pull/5883/files Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=5883&range=00 Issue: https://bugs.openjdk.java.net/browse/JDK-8275013 Stats: 18 lines in 2 files changed: 13 ins; 0 del; 5 mod Patch: https://git.openjdk.java.net/jdk/pull/5883.diff Fetch: git fetch https://git.openjdk.java.net/jdk pull/5883/head:pull/5883 PR: https://git.openjdk.java.net/jdk/pull/5883
On Sun, 10 Oct 2021 20:25:43 GMT, Joe Darcy <darcy@openjdk.org> wrote:
The java.io.ObjectInputStream and java.io.ObjectOuputStream classes are part of the serialization feature. These classes contain brief descriptions of some of the methods serializable classes can define to interact with the serialization mechanism, readObject, readObjectNoData, and writeObject. These descriptions are not entirely consistent with one another and at least one is arguably misleading.
This PR makes the brief discussion the same in both classes and addresses the misleading point: the throws clauses of the methods will not effect whether or not the methods are found by serialization, but throwing unchecked exceptions not declared in the standard signatures is ill-advised. (The current implementation looks up the methods by name using core reflection; the method modifiers are checked to match but the throws information is not.)
Please also review the corresponding CSR : https://bugs.openjdk.java.net/browse/JDK-8275014
src/java.base/share/classes/java/io/ObjectOutputStream.java line 105:
103: * declared to throw checked exceptions consistent with these 104: * signatures. 105: *
Why the mix of 'should' vs 'must' in this paragraph? The change above downgrades a 'must' to a 'should'. The original text and the java serialization spec use 'must'. Other JDK doc uses 'should' as being more readable but is supposed to mean 'must'. ------------- PR: https://git.openjdk.java.net/jdk/pull/5883
On Thu, 14 Oct 2021 14:47:28 GMT, Roger Riggs <rriggs@openjdk.org> wrote:
The java.io.ObjectInputStream and java.io.ObjectOuputStream classes are part of the serialization feature. These classes contain brief descriptions of some of the methods serializable classes can define to interact with the serialization mechanism, readObject, readObjectNoData, and writeObject. These descriptions are not entirely consistent with one another and at least one is arguably misleading.
This PR makes the brief discussion the same in both classes and addresses the misleading point: the throws clauses of the methods will not effect whether or not the methods are found by serialization, but throwing unchecked exceptions not declared in the standard signatures is ill-advised. (The current implementation looks up the methods by name using core reflection; the method modifiers are checked to match but the throws information is not.)
Please also review the corresponding CSR : https://bugs.openjdk.java.net/browse/JDK-8275014
src/java.base/share/classes/java/io/ObjectOutputStream.java line 105:
103: * declared to throw checked exceptions consistent with these 104: * signatures. 105: *
Why the mix of 'should' vs 'must' in this paragraph? The change above downgrades a 'must' to a 'should'. The original text and the java serialization spec use 'must'. Other JDK doc uses 'should' as being more readable but is supposed to mean 'must'.
Because there is a difference in consequence if the name, modifiers, return type, etc. don't match as opposed to the throws clause not matching. As stated, if the name, modifiers, etc. do not match the method is *not* used by serialization. Either the method is not found from the getDeclaredMethod call or is screened out afterward. If the throws information doesn't match, the method is still found and used by serialization. As the method is invoked reflective at runtime, if it throws a checked exception other than one of the declared one, exception handling code propagates out an InvocationTargetException. ------------- PR: https://git.openjdk.java.net/jdk/pull/5883
On Sun, 10 Oct 2021 20:25:43 GMT, Joe Darcy <darcy@openjdk.org> wrote:
The java.io.ObjectInputStream and java.io.ObjectOuputStream classes are part of the serialization feature. These classes contain brief descriptions of some of the methods serializable classes can define to interact with the serialization mechanism, readObject, readObjectNoData, and writeObject. These descriptions are not entirely consistent with one another and at least one is arguably misleading.
This PR makes the brief discussion the same in both classes and addresses the misleading point: the throws clauses of the methods will not effect whether or not the methods are found by serialization, but throwing unchecked exceptions not declared in the standard signatures is ill-advised. (The current implementation looks up the methods by name using core reflection; the method modifiers are checked to match but the throws information is not.)
Please also review the corresponding CSR : https://bugs.openjdk.java.net/browse/JDK-8275014
Marked as reviewed by smarks (Reviewer). ------------- PR: https://git.openjdk.java.net/jdk/pull/5883
On Sun, 10 Oct 2021 20:25:43 GMT, Joe Darcy <darcy@openjdk.org> wrote:
The java.io.ObjectInputStream and java.io.ObjectOuputStream classes are part of the serialization feature. These classes contain brief descriptions of some of the methods serializable classes can define to interact with the serialization mechanism, readObject, readObjectNoData, and writeObject. These descriptions are not entirely consistent with one another and at least one is arguably misleading.
This PR makes the brief discussion the same in both classes and addresses the misleading point: the throws clauses of the methods will not effect whether or not the methods are found by serialization, but throwing unchecked exceptions not declared in the standard signatures is ill-advised. (The current implementation looks up the methods by name using core reflection; the method modifiers are checked to match but the throws information is not.)
Please also review the corresponding CSR : https://bugs.openjdk.java.net/browse/JDK-8275014
Marked as reviewed by rriggs (Reviewer). ------------- PR: https://git.openjdk.java.net/jdk/pull/5883
On Sun, 10 Oct 2021 20:25:43 GMT, Joe Darcy <darcy@openjdk.org> wrote:
The java.io.ObjectInputStream and java.io.ObjectOuputStream classes are part of the serialization feature. These classes contain brief descriptions of some of the methods serializable classes can define to interact with the serialization mechanism, readObject, readObjectNoData, and writeObject. These descriptions are not entirely consistent with one another and at least one is arguably misleading.
This PR makes the brief discussion the same in both classes and addresses the misleading point: the throws clauses of the methods will not effect whether or not the methods are found by serialization, but throwing unchecked exceptions not declared in the standard signatures is ill-advised. (The current implementation looks up the methods by name using core reflection; the method modifiers are checked to match but the throws information is not.)
Please also review the corresponding CSR : https://bugs.openjdk.java.net/browse/JDK-8275014
This pull request has now been integrated. Changeset: 8c4da9c1 Author: Joe Darcy <darcy@openjdk.org> URL: https://git.openjdk.java.net/jdk/commit/8c4da9c15fec7bd27e243e9a6c9ebcad6310... Stats: 18 lines in 2 files changed: 13 ins; 0 del; 5 mod 8275013: Improve discussion of serialization method declarations in java.io.Object{Input, Output}Stream Reviewed-by: smarks, rriggs ------------- PR: https://git.openjdk.java.net/jdk/pull/5883
participants (3)
-
Joe Darcy
-
Roger Riggs
-
Stuart Marks