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

RandomAccessFile#write method could throw IndexOutOfBoundsException that is not described in javadoc

    XMLWordPrintable

    Details

    • Type: CSR
    • Status: Closed
    • Priority: P4
    • Resolution: Approved
    • Fix Version/s: 18
    • Component/s: core-libs
    • Labels:
      None
    • Subcomponent:
    • Compatibility Risk:
      minimal
    • Compatibility Risk Description:
      Align javadoc with long standing behavior, there is no compatibility risk.
    • Interface Kind:
      Java API
    • Scope:
      SE

      Description

      Summary

      Update the javadoc for the 3-arg write methods defined by java.io.DataOutput and java.io.RandomAccessFile to document that they throw IndexOutOfBoundsException.

      Problem

      The 3-arg write methods defined by java.io.DataOutput and java.io.RandomAccessFile do no document that they throw IndexOutOfBoundsException.

      Solution

      Specify that IndexOutOfBoundsException will be thrown in the javadoc for DataOutput::write that is the super interface for RandomAccessFile. The implementation class RandomAccessFile inherits the javadoc of the exception.

      Specification

      DataOutput::write:

           /**
            * Writes {@code len} bytes from array
            * {@code b}, in order,  to
            * the output stream.  If {@code b}
            * is {@code null}, a {@code NullPointerException}
            * is thrown.  If {@code off} is negative,
            * or {@code len} is negative, or {@code off+len}
            * is greater than the length of the array
            * {@code b}, then an {@code IndexOutOfBoundsException}
            * is thrown.  If {@code len} is zero,
            * then no bytes are written. Otherwise, the
            * byte {@code b[off]} is written first,
            * then {@code b[off+1]}, and so on; the
            * last byte written is {@code b[off+len-1]}.
            *
            * @param      b     the data.
            * @param      off   the start offset in the data.
            * @param      len   the number of bytes to write.
            * @throws     IOException  if an I/O error occurs.
      +     * @throws     IndexOutOfBoundsException If {@code off} is negative,
      +     *             {@code len} is negative, or {@code len} is greater than
      +     *             {@code b.length - off}
            */
           void write(byte[] b, int off, int len) throws IOException;

      RandomAccessFile::write:

           /**
            * Writes {@code len} bytes from the specified byte array
            * starting at offset {@code off} to this file.
            *
            * @param      b     the data.
            * @param      off   the start offset in the data.
            * @param      len   the number of bytes to write.
            * @throws     IOException  if an I/O error occurs.
      +     * @throws     IndexOutOfBoundsException {@inheritDoc}
            */
           public void write(byte[] b, int off, int len) throws IOException {
               writeBytes(b, off, len);
           }

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              myano Masanori Yano
              Reporter:
              myano Masanori Yano
              Reviewed By:
              Alan Bateman
              Votes:
              0 Vote for this issue
              Watchers:
              1 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved: