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)