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

Deflater::deflate methods omit javadoc for ReadOnlyBufferException

    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
    • Compatibility Risk Description:
      The javadoc update simply clarifies the existing behavior.
    • Interface Kind:
      Java API
    • Scope:
      SE

      Description

      Summary

      The Deflater::deflate methods that were added as part of JDK-6341887 could throw a ReadOnlyBufferException. This was inadvertently omitted from the javadoc for these new methods

      Problem

      The javadoc for Deflater methods deflate(ByteBuffer output, int flush) and deflate(ByteBuffer output) do not indicate that a ReadOnlyBufferException may be thrown

      Solution

      Add the following:

      @throws ReadOnlyBufferException if the given output buffer is read-only

      to the javadoc for the Deflater methods deflate(ByteBuffer output, int flush) and deflate(ByteBuffer output).

      Specification

      Update the javadoc to be

         /**
           * Compresses the input data and fills specified buffer with compressed
           * data. Returns actual number of bytes of compressed data. A return value
           * of 0 indicates that {@link #needsInput() needsInput} should be called
           * in order to determine if more input data is required.
           *
           * <p>This method uses {@link #NO_FLUSH} as its compression flush mode.
           * An invocation of this method of the form {@code deflater.deflate(output)}
           * yields the same result as the invocation of
           * {@code deflater.deflate(output, Deflater.NO_FLUSH)}.
           *
           * @param output the buffer for the compressed data
           * @return the actual number of bytes of compressed data written to the
           *         output buffer
           * @throws ReadOnlyBufferException if the given output buffer is read-only
           * @since 11
           */
          public int deflate(ByteBuffer output) 
      
      /**
       * Compresses the input data and fills the specified buffer with compressed
       * data. Returns actual number of bytes of data compressed.
       *
       * <p>Compression flush mode is one of the following three modes:
       *
       * <ul>
       * <li>{@link #NO_FLUSH}: allows the deflater to decide how much data
       * to accumulate, before producing output, in order to achieve the best
       * compression (should be used in normal use scenario). A return value
       * of 0 in this flush mode indicates that {@link #needsInput()} should
       * be called in order to determine if more input data is required.
       *
       * <li>{@link #SYNC_FLUSH}: all pending output in the deflater is flushed,
       * to the specified output buffer, so that an inflater that works on
       * compressed data can get all input data available so far (In particular
       * the {@link #needsInput()} returns {@code true} after this invocation
       * if enough output space is provided). Flushing with {@link #SYNC_FLUSH}
       * may degrade compression for some compression algorithms and so it
       * should be used only when necessary.
       *
       * <li>{@link #FULL_FLUSH}: all pending output is flushed out as with
       * {@link #SYNC_FLUSH}. The compression state is reset so that the inflater
       * that works on the compressed output data can restart from this point
       * if previous compressed data has been damaged or if random access is
       * desired. Using {@link #FULL_FLUSH} too often can seriously degrade
       * compression.
       * </ul>
       *
       * <p>In the case of {@link #FULL_FLUSH} or {@link #SYNC_FLUSH}, if
       * the return value is equal to the {@linkplain ByteBuffer#remaining() remaining space}
       * of the buffer, this method should be invoked again with the same
       * {@code flush} parameter and more output space. Make sure that
       * the buffer has at least 6 bytes of remaining space to avoid the
       * flush marker (5 bytes) being repeatedly output to the output buffer
       * every time this method is invoked.
       *
       * <p>On success, the position of the given {@code output} byte buffer will be
       * advanced by as many bytes as were produced by the operation, which is equal
       * to the number returned by this method.
       *
       * <p>If the {@link #setInput(ByteBuffer)} method was called to provide a buffer
       * for input, the input buffer's position will be advanced by the number of bytes
       * consumed by this operation.
       *
       * @param output the buffer for the compressed data
       * @param flush the compression flush mode
       * @return the actual number of bytes of compressed data written to
       *         the output buffer
       *
       * @throws IllegalArgumentException if the flush mode is invalid
       * @throws ReadOnlyBufferException if the given output buffer is read-only
       * @since 11
       */
      public int deflate(ByteBuffer output, int flush) 

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              lancea Lance Andersen
              Reporter:
              lancea Lance Andersen
              Reviewed By:
              Brian Burkhalter, Iris Clark
              Votes:
              0 Vote for this issue
              Watchers:
              2 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved: