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

Specify the javadoc for the serial forms in java.logging module

    XMLWordPrintable

    Details

    • Type: CSR
    • Status: Closed
    • Priority: P4
    • Resolution: Approved
    • Fix Version/s: 16
    • Component/s: core-libs
    • Labels:
      None
    • Subcomponent:
    • Compatibility Risk:
      minimal
    • Compatibility Risk Description:
      Documentation is clarified. No change to the source code.
    • Interface Kind:
      Java API
    • Scope:
      SE

      Description

      Summary

      Some serialization primitive in java.logging are missing (or have incomplete) API documentation.

      Problem

      doclint has been extended to detect more cases and this generates warning

      Solution

      Add missing documentation

      Specification

      src/java.logging/share/classes/java/util/logging/Level.java

      -    // Serialization magic to prevent "doppelgangers".
      -    // This is a performance optimization.
      +    /**
      +     * Returns a {@code Level} instance with the same {@code name},
      +     * {@code value}, and {@code resourceBundleName} as the deserialized
      +     * object.
      +     * @return a {@code Level} instance corresponding to the deserialized
      +     * object.
      +     */
      +    @Serial
            private Object readResolve() {
      +        // Serialization magic to prevent "doppelgangers".
      +        // This is a performance optimization.

      src/java.logging/share/classes/java/util/logging/LogRecord.java

           /**
            * @serialData Serialized fields, followed by a two byte version number
            * (major byte, followed by minor byte), followed by information on
            * the log record parameter array.  If there is no parameter array,
            * then -1 is written.  If there is a parameter array (possible of zero
            * length) then the array length is written as an integer, followed
            * by String values for each parameter.  If a parameter is null, then
            * a null String is written.  Otherwise the output of Object.toString()
            * is written.
      +     *
      +     * @param out the {@code ObjectOutputStream} to write to
      +     *
      +     * @throws  IOException if I/O errors occur
            */
           @Serial
           private void writeObject(ObjectOutputStream out) throws IOException {

      ...

           /**
            * Initializes the LogRecord from deserialized data.
            * <ul>
            * <li>If {@code longThreadID} is present in the serial form, its value
            * takes precedence over {@code threadID} and a value for {@code threadID}
            * is synthesized from it, such that for {@code longThreadID} values between
            * {@code 0} and {@code Integer.MAX_VALUE} inclusive, {@code longThreadID}
            * and {@code threadID} will have the same value. For values outside of this
            * range a negative synthesized value will be deterministically derived
            * from {@code longThreadID}.
            * <li>Otherwise, when only {@code threadID} is
            * present, {@code longThreadID} is initialized with the value of
            * {@code threadID} which may be anything between {@code Integer.MIN_VALUE}
            * and {Integer.MAX_VALUE}.
            * </ul>
            * {@code threadID} which may be anything between {@code Integer.MIN_VALUE}
            * and {Integer.MAX_VALUE}.
            * </ul>
      +     *
      +     * See {@code writeObject} for a description of the serial form.
      +     *
      +     * @param in the {@code ObjectInputStream} to read from
      +     *
      +     * @throws  ClassNotFoundException if the class of a serialized object
      +     *          could not be found.
      +     * @throws  IOException if an I/O error occurs.
            */
           @Serial
           private void readObject(ObjectInputStream in)
                throws IOException, ClassNotFoundException {

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              dfuchs Daniel Fuchs
              Reporter:
              dfuchs Daniel Fuchs
              Reviewed By:
              Lance Andersen, Mandy Chung
              Votes:
              0 Vote for this issue
              Watchers:
              3 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved: