Summary

The specification of java.util.zip.DeflaterOutputStream, java.util.zip.DeflaterInputStream, java.util.zip.InflaterInputStream and java.util.zip.InflaterOutputStream classes will be enhanced to specify the usage and closure of java.util.zip.Deflater and java.util.zip.Inflater instances by these classes.

Problem

The implementation of DeflaterOutputStream and DeflaterInputStream uses Deflater instance to compress the stream data. Each of these classes have more than one constructor to construct the stream. Some of these constructors allow application code to pass a Deflater instance whereas some other constructors do not accept a Deflater and instead create a Deflater instance of their own. When the stream is closed, the current implementation of these classes close the Deflater instance if the stream was constructed without being passed a Deflater. On the other hand, if a Deflater was passed during construction of the stream, the application code is expected to close that Deflater instance after the stream has been closed.

Similar implementation resides in InflaterOutputStream and InflaterInputStream classes which can be constructed either by passing a Inflater or the Inflater being created by the stream during construction.

Neither of these classes specify that the application code needs to take responsibility of closing the Deflater/Inflater instance if the stream was constructed by passing it the Deflater/Inflater.

Solution

The specification of these 4 classes will be updated to match the current implementation and clarify the responsibility of the application code when dealing with the Deflater/Inflater instance.

Specification

diff --git a/src/java.base/share/classes/java/util/zip/DeflaterInputStream.java b/src/java.base/share/classes/java/util/zip/DeflaterInputStream.java
+ * <h2 id="compressor-usage">Compressor Usage</h2>
+ * A {@code DeflaterInputStream} created without
+ * specifying a {@linkplain Deflater compressor} will create a compressor
+ * at construction time, and close the compressor when the input stream
+ * is {@linkplain #close closed}.
+ * <p>
+ * If a compressor is specified when creating a {@code DeflaterInputStream}, it is the
+ * responsibility of the caller to {@linkplain Deflater#close close} the
+ * compressor after closing the input stream.
+ *
+ * @apiNote
+ * The {@link #close} method should be called to release resources used by this
+ * stream, either directly, or with the {@code try}-with-resources statement.
+ *
@@ -68,8 +82,11 @@ private void ensureOpen() throws IOException {
     }

     /**
-     * Creates a new input stream with a default compressor and buffer
-     * size.
+     * Creates a new input stream and compressor with the
+     * default compression level and a default buffer size.
+     * <p>
+     * The compressor will be closed when this input stream
+     * is {@linkplain #close() closed}.
      *
      * @param in input stream to read the uncompressed data to
      * @throws NullPointerException if {@code in} is null
@@ -82,6 +99,10 @@ public DeflaterInputStream(InputStream in) {
     /**
      * Creates a new input stream with the specified compressor and a
      * default buffer size.
+     * <p>
+     * {@linkplain #close() Closing} this input stream
+     * {@linkplain ##compressor-usage will not close} the given
+     * {@linkplain Deflater compressor}.
      *
      * @param in input stream to read the uncompressed data to
      * @param defl compressor ("deflater") for this stream
@@ -94,6 +115,10 @@ public DeflaterInputStream(InputStream in, Deflater defl) {
     /**
      * Creates a new input stream with the specified compressor and buffer
      * size.
+     * <p>
+     * {@linkplain #close() Closing} this input stream
+     * {@linkplain ##compressor-usage will not close} the given
+     * {@linkplain Deflater compressor}.
      *
      * @param in input stream to read the uncompressed data to
      * @param defl compressor ("deflater") for this stream
@@ -123,6 +148,7 @@ public DeflaterInputStream(InputStream in, Deflater defl, int bufLen) {

diff --git a/src/java.base/share/classes/java/util/zip/DeflaterOutputStream.java b/src/java.base/share/classes/java/util/zip/DeflaterOutputStream.java
+ * <h2 id="compressor-usage">Compressor Usage</h2>
+ * A {@code DeflaterOutputStream} created without
+ * specifying a {@linkplain Deflater compressor} will create a compressor
+ * at construction time, and close the compressor when the output stream
+ * is {@linkplain #close closed}.
+ * <p>
+ * If a compressor is specified when creating a {@code DeflaterOutputStream}, it is the
+ * responsibility of the caller to {@linkplain Deflater#close close} the
+ * compressor after closing the output stream.
+ *
+ * @apiNote
+ * The {@link #close} method should be called to release resources used by this
+ * stream, either directly, or with the {@code try}-with-resources statement.
+ *
@@ -63,6 +77,10 @@ public class DeflaterOutputStream extends FilterOutputStream {
     /**
      * Creates a new output stream with the specified compressor,
      * buffer size and flush mode.
+     * <p>
+     * {@linkplain #close() Closing} this output stream
+     * {@linkplain ##compressor-usage will not close} the given
+     * {@linkplain Deflater compressor}.
      *
      * @param out the output stream
      * @param def the compressor ("deflater")
@@ -98,7 +116,11 @@ public DeflaterOutputStream(OutputStream out,
      * buffer size.
      *
      * <p>The new output stream instance is created as if by invoking
-     * the 4-argument constructor DeflaterOutputStream(out, def, size, false).
+     * the 4-argument constructor {@code DeflaterOutputStream(out, def, size, false)}.
+     * <p>
+     * {@linkplain #close() Closing} this output stream
+     * {@linkplain ##compressor-usage will not close} the given
+     * {@linkplain Deflater compressor}.
      *
      * @param out the output stream
      * @param def the compressor ("deflater")
@@ -112,6 +134,10 @@ public DeflaterOutputStream(OutputStream out, Deflater def, int size) {
     /**
      * Creates a new output stream with the specified compressor, flush
      * mode and a default buffer size.
+     * <p>
+     * {@linkplain #close() Closing} this output stream
+     * {@linkplain ##compressor-usage will not close} the given
+     * {@linkplain Deflater compressor}.
      *
      * @param out the output stream
      * @param def the compressor ("deflater")
@@ -135,7 +161,11 @@ public DeflaterOutputStream(OutputStream out,
      * a default buffer size.
      *
      * <p>The new output stream instance is created as if by invoking
-     * the 3-argument constructor DeflaterOutputStream(out, def, false).
+     * the 3-argument constructor {@code DeflaterOutputStream(out, def, false)}.
+     * <p>
+     * {@linkplain #close() Closing} this output stream
+     * {@linkplain ##compressor-usage will not close} the given
+     * {@linkplain Deflater compressor}.
      *
      * @param out the output stream
      * @param def the compressor ("deflater")
@@ -148,8 +178,12 @@ public DeflaterOutputStream(OutputStream out, Deflater def) {


     /**
-     * Creates a new output stream with a default compressor, a default
-     * buffer size and the specified flush mode.
+     * Creates a new output stream and compressor with the
+     * default compression level, a default buffer size and
+     * the specified flush mode.
+     * <p>
+     * The compressor will be closed when this output stream
+     * is {@linkplain #close() closed}.
      *
      * @param out the output stream
      * @param syncFlush
@@ -166,10 +200,14 @@ public DeflaterOutputStream(OutputStream out, boolean syncFlush) {
     }

     /**
-     * Creates a new output stream with a default compressor and buffer size.
+     * Creates a new output stream and compressor with the
+     * default compression level and a default buffer size.
      *
      * <p>The new output stream instance is created as if by invoking
-     * the 2-argument constructor DeflaterOutputStream(out, false).
+     * the 2-argument constructor {@code DeflaterOutputStream(out, false)}.
+     * <p>
+     * The compressor will be closed when this output stream
+     * is {@linkplain #close() closed}.
      *
      * @param out the output stream
      */
@@ -184,6 +222,7 @@ public DeflaterOutputStream(OutputStream out) {

diff --git a/src/java.base/share/classes/java/util/zip/InflaterInputStream.java b/src/java.base/share/classes/java/util/zip/InflaterInputStream.java
+ *
+ * <h2 id="decompressor-usage">Decompressor Usage</h2>
+ * An {@code InflaterInputStream} created without
+ * specifying a {@linkplain Inflater decompressor} will create a decompressor
+ * at construction time, and close the decompressor when the input stream
+ * is {@linkplain #close closed}.
+ * <p>
+ * If a decompressor is specified when creating a {@code InflaterInputStream}, it is the
+ * responsibility of the caller to {@linkplain Inflater#close close} the
+ * decompressor after closing the input stream.
+ *
+ * @apiNote
+ * The {@link #close} method should be called to release resources used by this
+ * stream, either directly, or with the {@code try}-with-resources statement.
+ *
     /**
      * Creates a new input stream with the specified decompressor and
      * buffer size.
+     * <p>
+     * {@linkplain #close() Closing} this input stream
+     * {@linkplain ##decompressor-usage will not close} the given
+     * {@linkplain Inflater decompressor}.
+     *
      * @param in the input stream
      * @param inf the decompressor ("inflater")
      * @param size the input buffer size
@@ -94,6 +114,11 @@ public InflaterInputStream(InputStream in, Inflater inf, int size) {
     /**
      * Creates a new input stream with the specified decompressor and a
      * default buffer size.
+     * <p>
+     * {@linkplain #close() Closing} this input stream
+     * {@linkplain ##decompressor-usage will not close} the given
+     * {@linkplain Inflater decompressor}.
+     *
      * @param in the input stream
      * @param inf the decompressor ("inflater")
      */
@@ -104,7 +129,12 @@ public InflaterInputStream(InputStream in, Inflater inf) {
     boolean usesDefaultInflater = false;

     /**
-     * Creates a new input stream with a default decompressor and buffer size.
+     * Creates a new input stream and decompressor with a
+     * default buffer size.
+     * <p>
+     * The decompressor will be closed when this input stream
+     * is {@linkplain #close() closed}.
+     *
      * @param in the input stream
      */
     public InflaterInputStream(InputStream in) {
@@ -120,6 +150,7 @@ public InflaterInputStream(InputStream in) {

diff --git a/src/java.base/share/classes/java/util/zip/InflaterOutputStream.java b/src/java.base/share/classes/java/util/zip/InflaterOutputStream.java
+ * <h2 id="decompressor-usage">Decompressor Usage</h2>
+ * An {@code InflaterOutputStream} created without
+ * specifying a {@linkplain Inflater decompressor} will create a decompressor
+ * at construction time, and close the decompressor when the output stream
+ * is {@linkplain #close closed}.
+ * <p>
+ * If a decompressor is specified when creating a {@code InflaterOutputStream}, it is the
+ * responsibility of the caller to {@linkplain Inflater#close close} the
+ * decompressor after closing the output stream.
+ *
+ * @apiNote
+ * The {@link #close} method should be called to release resources used by this
+ * stream, either directly, or with the {@code try}-with-resources statement.
+ *
     /**
-     * Creates a new output stream with a default decompressor and buffer
-     * size.
+     * Creates a new output stream and decompressor with a
+     * default buffer size.
+     * <p>
+     * The decompressor will be closed when this output stream
+     * is {@linkplain #close() closed}.
      *
      * @param out output stream to write the uncompressed data to
      * @throws NullPointerException if {@code out} is null
@@ -82,6 +99,10 @@ public InflaterOutputStream(OutputStream out) {
     /**
      * Creates a new output stream with the specified decompressor and a
      * default buffer size.
+     * <p>
+     * {@linkplain #close() Closing} this output stream
+     * {@linkplain ##decompressor-usage will not close} the given
+     * {@linkplain Inflater decompressor}.
      *
      * @param out output stream to write the uncompressed data to
      * @param infl decompressor ("inflater") for this stream
@@ -94,6 +115,10 @@ public InflaterOutputStream(OutputStream out, Inflater infl) {
     /**
      * Creates a new output stream with the specified decompressor and
      * buffer size.
+     * <p>
+     * {@linkplain #close() Closing} this output stream
+     * {@linkplain ##decompressor-usage will not close} the given
+     * {@linkplain Inflater decompressor}.
      *
      * @param out output stream to write the uncompressed data to
      * @param infl decompressor ("inflater") for this stream
@@ -123,6 +148,7 @@ public InflaterOutputStream(OutputStream out, Inflater infl, int bufLen) {