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

Update serialization javadoc once JOSS changes for records are complete

    XMLWordPrintable

Details

    • CSR
    • Status: Closed
    • P3
    • Resolution: Approved
    • 16
    • core-libs
    • None
    • source
    • minimal
    • Java API
    • SE

    Description

      Summary

      The changes for record serialization have been integrated into the Java Object Serialization Specification (JOSS). The javadoc of certain serialization classes needs to be adjusted accordingly.

      Problem

      • The class-level javadoc of ObjectInputStream contains a lengthy @implSpec on record serialization.
      • The class-level javadoc of ObjectOutputStream contains an @implSpec on record serialization.
      • The class-level javadoc of Serializable does not contain any mention of record serialization.
      • The class-level javadoc of java.lang.Record links to the @implSpec in java.io.ObjectInputStream.

      Solution

      • ObjectInputStream: replace @implSpec with a short note and a link to the JOSS.
      • ObjectOutputStream: turn @implSpec into a regular javadoc section.
      • Serializable: add section on record serialization, including a link to the JOSS.
      • java.lang.Record: replace link to ObjectInputStream with link to the JOSS.

      Specification

      src/java.base/share/classes/java/io/ObjectInputStream.java

      -    * @implSpec
           * <a id="record-serialization"></a>
      -    * Records are serialized differently than ordinary serializable or externalizable
      -    * objects. The serialized form of a record object is a sequence of values derived
      -    * from the record components. The stream format of a record object is the same as
      -    * that of an ordinary object in the stream. During deserialization, if the local
      -    * class equivalent of the specified stream class descriptor is a record class,
      -    * then first the stream fields are read and reconstructed to serve as the record's
      -    * component values; and second, a record object is created by invoking the
      -    * record's <i>canonical</i> constructor with the component values as arguments (or the
      -    * default value for component's type if a component value is absent from the
      -    * stream).
      -    * Like other serializable or externalizable objects, record objects can function
      -    * as the target of back references appearing subsequently in the serialization
      -    * stream. However, a cycle in the graph where the record object is referred to,
      -    * either directly or transitively, by one of its components, is not preserved.
      -    * The record components are deserialized prior to the invocation of the record
      -    * constructor, hence this limitation (see
      -    * <a href="{@docRoot}/../specs/serialization/serial-arch.html#cyclic-references">
      -    * <cite>Java Object Serialization Specification,</cite>
      -    * Section 1.14, "Circular References"</a> for additional information).
      -    * The process by which record objects are serialized or externalized cannot be
      -    * customized; any class-specific writeObject, readObject, readObjectNoData,
      -    * writeExternal, and readExternal methods defined by record classes are
      -    * ignored during serialization and deserialization. However, a substitute object
      -    * to be serialized or a designate replacement may be specified, by the
      -    * writeReplace and readResolve methods, respectively.  Any
      -    * serialPersistentFields field declaration is ignored. Documenting serializable
      -    * fields and data for record classes is unnecessary, since there is no variation
      -    * in the serial form, other than whether a substitute or replacement object is
      -    * used. The serialVersionUID of a record class is 0L unless explicitly
      -    * declared. The requirement for matching serialVersionUID values is waived for
      -    * record classes.
      +    * <p>Records are serialized differently than ordinary serializable or externalizable
      +    * objects. During deserialization the record's canonical constructor is invoked
      +    * to construct the record object. Certain serialization-related methods, such
      +    * as readObject and writeObject, are ignored for serializable records. See
      +    * <a href="{@docRoot}/../specs/serialization/serial-arch.html#serialization-of-records">
      +    * <cite>Java Object Serialization Specification,</cite> Section 1.13,
      +    * "Serialization of Records"</a> for additional information.

      src/java.base/share/classes/java/io/ObjectOutputStream.java

      -    * @implSpec
      -    * Records are serialized differently than ordinary serializable or externalizable
      +    * <p>Records are serialized differently than ordinary serializable or externalizable
           * objects, see <a href="ObjectInputStream.html#record-serialization">record serialization</a>.

      src/java.base/share/classes/java/io/Serializable.java

      +    * Record classes can implement {@code Serializable} and receive treatment defined
      +    * by the <a href="{@docRoot}/../specs/serialization/serial-arch.html#serialization-of-records">
      +    * <cite>Java Object Serialization Specification,</cite> Section 1.13,
      +    * "Serialization of Records"</a>. Any declarations of the special
      +    * handling methods discussed above are ignored for record types.<p>

      src/java.base/share/classes/java/lang/Record.java

           * and writeObject, are ignored for serializable records. More information about
      -    * serializable records can be found in
      -    * <a href="{@docRoot}/java.base/java/io/ObjectInputStream.html#record-serialization">record serialization</a>.
      +    * serializable records can be found in the
      +    * <a href="{@docRoot}/../specs/serialization/serial-arch.html#serialization-of-records">
      +    * <cite>Java Object Serialization Specification,</cite> Section 1.13,
      +    * "Serialization of Records"</a>.

      Attachments

        Issue Links

          Activity

            People

              jboes Julia Boes (Inactive)
              smarks Stuart Marks
              Chris Hegarty
              Votes:
              0 Vote for this issue
              Watchers:
              1 Start watching this issue

              Dates

                Created:
                Updated:
                Resolved: