RFR: 8066583: DeflaterInput/OutputStream and InflaterInput/OutputStream should explain responsibility for freeing resources [v3]

[Lance Andersen]

On Mon, 3 Mar 2025 11:59:36 GMT, Eirik Bjørsnøs <eirbjo at openjdk.org> wrote:

> > Given the inputs from Alan, Eirik and Lance, I have now updated this PR [...]
> 
> > Does this look better?
> 
> I like the structure this is shaping into, with the affected constructors linking into a note. I like that the note explains that some forms of constructors require special attention to manage resources.
> 
> As noted by @vy, I find the note perhaps a bit verbose, and I agree that focus should be given to what actually needs attention, which is the constructors which allow passing a `Deflater`. I'm worried that the lengthy "introduction" means we loose readers before they get the message.
> 
> I also think it could maybe help understanding/importance if we explicitly mention that closing the deflater will release resources used by the deflater. Otherwise, the resource leak concequence of not closing the deflater is not made abundantly clear.
> 
> I tried rewording this with input from @vy in mind, and came up with this. Take whatever inspiration you find useful:
> 
> ```
>  * <p>Some of the constructors in this class allow passing a {@link Deflater} for
>  * compressing data. When a {@code DeflaterOutputStream} is constructed by passing
>  * it a {@code Deflater}, then closing the stream will not close the passed
>  * {@code Deflater}. In such cases, it is the responsibility of the caller to
>  * to release resources used by the {@code Deflater} by
>  * {@linkplain Deflater#close() closing} it as and when appropriate,
>  * after the {@code DeflaterOutputStream} has been closed.
> ```
> 
>  > > perhaps with an example snippet demonstrating a safe use of the API class
> 
> Yes, I agree there is too much variabilty in the potential uses of Deflater here, the important message is that the caller is responsible for releasing resources by closing.

I think we can simplify this  further to something like:

`When a compressor({@link Deflater}) is specified when creating  a {@link DeflaterOutputStream} instance, it is the responsibility of the  caller to  release  {@code Deflaters'} resources by calling  {@linkplain Deflater#close()} `

-------------

PR Comment: https://git.openjdk.org/jdk/pull/23655#issuecomment-2695709906