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

Fix doclint warnings in java/nio

    XMLWordPrintable

Details

    • CSR
    • Resolution: Approved
    • P4
    • 17
    • core-libs
    • None
    • minimal
    • Clarifying existing serialized-form
    • Java API
    • SE

    Description

      Summary

      Clarify and add missing serialized-form specification to several NIO Exception classes.

      Problem

      There are several Exception classes in java.nio (and its subpackages) that have either missing or inadequate information in their serialized-form specification. Nine Serializable fields are missing comments which results in only the name of the field appearing in the serialized-form specification (without a description). There is also one readObject method with missing information about its parameters and declared exceptions.

      Solution

      The above issues are resolved in java.nio (and its subpackages) as follows:

      • Missing comments are added to the Serializable fields concerned
      • @param and @throws tags are added to the method that was missing these details (DirectoryIteratorException::readObject)

      Specification

      Specification additions and clarifications that ultimately show in the serialized-form page are as follows:

          package java.nio.charset;
          public class UnsupportedCharsetException ... {
      
             @java.io.Serial
             private static final long serialVersionUID = 1490765524727386367L;
      
          +  /**
          +   * The name of the unsupported charset.
          +   */
             private String charsetName;
      
             ...
          }
          package java.nio.charset;
          public class IllegalCharsetNameException ... {
      
             @java.io.Serial
             private static final long serialVersionUID = 1457525358470002989L;
      
          +  /**
          +   * The illegal charset name.
          +   */
             private String charsetName;
      
             ...
         }
          package java.nio.charset;
          public class MalformedInputException  ... {
      
             @java.io.Serial
             private static final long serialVersionUID = -3438823399834806194L;
      
          +  /**
          +   * The length of the input.
          +   */
             private int inputLength;
      
             ...
          }
          package java.nio.charset;
          public class UnmappableCharacterException ... {
      
             @java.io.Serial
             private static final long serialVersionUID = -7026962371537706123L;
      
          +  /**
          +   * The length of the input character (or byte) sequence.
          +   */
             private int inputLength;
      
             ...
          }
          package java.nio.file;
          public final class DirectoryIteratorException ... {
      
             @java.io.Serial
             private static final long serialVersionUID = -6012699886086212874L;
      
             ...
      
             /**
              * Called to read the object from a stream.
              *
          +   * @param   s
          +   *          the {@code ObjectInputStream} to read
          +   *
              * @throws  InvalidObjectException
              *          if the object is invalid or has a cause that is not
              *          an {@code IOException}
          +   *
          +   * @throws  IOException
          +   *          if an I/O error occurs
          +   *
          +   * @throws  ClassNotFoundException
          +   *          if the class of a serialized object could not be
          +   *          found
              */
             @java.io.Serial
             private void readObject(ObjectInputStream s)
                 throws IOException, ClassNotFoundException { ... }
             ...
         }       
          package java.nio.file;
          public class FileSystemException ... {
      
             @java.io.Serial
             static final long serialVersionUID = -3055425747967319812L;
      
          +  /**
          +   *  String identifying the file or {@code null} if not known.
          +   */
             private final String file;
      
          +  /**
          +   *  String identifying the other file or {@code null} if there isn't
          +   *  another file or if not known.
          +   */
             private final String other;
      
             ...
          }
          package java.nio.file;
          public class InvalidPathException ... {
      
             @java.io.Serial
             static final long serialVersionUID = 4355821422286746137L;
      
          +  /**
          +   * The input string.
          +   */
             private String input;
      
          +  /**
          +   * The index of the input string at which the error occurred or
          +   * {@code -1} if not known.
          +   */
             private int index;
      
             ...
          }
          package java.nio.file.attribute;
          public class UserPrincipalNotFoundException ... {
      
             @java.io.Serial
             static final long serialVersionUID = -5369283889045833024L;
      
          +  /**
          +   * The user principal name.
          +   */
             private final String name;
      
             ...
          }

      Attachments

        Issue Links

          Activity

            People

              ccleary Conor Cleary
              ccleary Conor Cleary
              Chris Hegarty
              Votes:
              0 Vote for this issue
              Watchers:
              1 Start watching this issue

              Dates

                Created:
                Updated:
                Resolved: