Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8275014

Improve discussion of serialization method declarations in java.io.Object{Input, Output}Stream

    XMLWordPrintable

    Details

    • Type: CSR
    • Status: Closed
    • Priority: P4
    • Resolution: Approved
    • Fix Version/s: 18
    • Component/s: core-libs
    • Labels:
      None
    • Subcomponent:
    • Compatibility Kind:
      behavioral
    • Compatibility Risk:
      minimal
    • Interface Kind:
      Java API
    • Scope:
      SE

      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

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              darcy Joe Darcy
              Reporter:
              darcy Joe Darcy
              Reviewed By:
              Roger Riggs, Stuart Marks
              Votes:
              0 Vote for this issue
              Watchers:
              1 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved: