JDK-8275014 : Improve discussion of serialization method declarations in java.io.Object{Input, Output}Stream
  • Type: CSR
  • Component: core-libs
  • Sub-Component: java.io
  • Priority: P4
  • Status: Closed
  • Resolution: Approved
  • Fix Versions: 18
  • Submitted: 2021-10-10
  • Updated: 2021-10-15
  • Resolved: 2021-10-15
Related Reports
CSR :  
Description
Summary
-------
Improve discussion of how to declared `readObject`, `readObjectNoData`, and `writeObject` in the classes `java.io.ObjectInputStream` and `java.io.Output}Stream`.

Problem
-------
The discussion of how to declare the methods is inconsistent between `java.io.ObjectInputStream` and `java.io.Output}Stream` and does not give clear guidance on the methods' throws clauses.

Solution
--------

Update the discussion to be accurate and the same in both classes.

Specification
-------------

    diff --git a/src/java.base/share/classes/java/io/ObjectInputStream.java b/src/java.base/share/classes/java/io/Obj
    ectInputStream.java
    index 315df036949..d58bf1d91c9 100644
    --- a/src/java.base/share/classes/java/io/ObjectInputStream.java
    +++ b/src/java.base/share/classes/java/io/ObjectInputStream.java
    @@ -145,8 +145,8 @@ import sun.security.action.GetIntegerAction;
      * entire graphs.
      *
      * <p>Serializable classes that require special handling during the
    - * serialization and deserialization process should implement the following
    - * methods:
    + * serialization and deserialization process should implement methods
    + * with the following signatures:
      *
      * <pre>
      * private void writeObject(java.io.ObjectOutputStream stream)
    @@ -157,6 +157,12 @@ import sun.security.action.GetIntegerAction;
      *     throws ObjectStreamException;
      * </pre>
      *
    + * <p>The method name, modifiers, return type, and number and type of
    + * parameters must match exactly for the method to be used by
    + * serialization or deserialization. The methods should only be
    + * declared to throw checked exceptions consistent with these
    + * signatures.
    + *
      * <p>The readObject method is responsible for reading and restoring the state
      * of the object for its particular class using data written to the stream by
      * the corresponding writeObject method.  The method does not need to concern
    diff --git a/src/java.base/share/classes/java/io/ObjectOutputStream.java b/src/java.base/share/classes/java/io/Ob
    jectOutputStream.java
    index a64186c7ed7..8d34fcec483 100644
    --- a/src/java.base/share/classes/java/io/ObjectOutputStream.java
    +++ b/src/java.base/share/classes/java/io/ObjectOutputStream.java
    @@ -83,9 +83,10 @@ import sun.reflect.misc.ReflectUtil;
      *      oos.close();
      * </pre>
      *
    - * <p>Classes that require special handling during the serialization and
    - * deserialization process must implement special methods with these exact
    - * signatures:
    + * <p>Serializable classes that require special handling during the
    + * serialization and deserialization process should implement methods
    + * with the following signatures:
    + *
      * <br>
      * <pre>
      * private void readObject(java.io.ObjectInputStream stream)
    @@ -96,6 +97,12 @@ import sun.reflect.misc.ReflectUtil;
      *     throws ObjectStreamException;
      * </pre>
      *
    + * <p>The method name, modifiers, return type, and number and type of
    + * parameters must match exactly for the method to be used by
    + * serialization or deserialization. The methods should only be
    + * declared to throw checked exceptions consistent with these
    + * signatures.
    + *
      * <p>The writeObject method is responsible for writing the state of the object
      * for its particular class so that the corresponding readObject method can
      * resto

re it.  The method does not need to concern itself with the state

Comments
Moving to Approved.
15-10-2021