On Mon, 3 Mar 2025 11:59:36 GMT, Eirik Bjørsnøs <eir...@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
