RFR: 8326096: Deprecate getTotalIn, getTotalOut methods of java.util.zip.Inflater, java.util.zip.Deflater [v9]

[Alan Bateman]

On Mon, 26 Feb 2024 20:46:01 GMT, Eirik Bjørsnøs <eirbjo at openjdk.org> wrote:

>> Please review this PR which proposes that we officially deprecate the following four methods in the `java.util.zip` package:
>> 
>> * `Inflater.getTotalIn()`
>> * `Inflater.getTotalOut()`
>> * `Deflater.getTotalIn()`
>> * `Deflater.getTotalOut()`
>> 
>> Since these legacy methods return `int`, they cannot safely return the number of bytes processed without the risk of losing information  about the magnitude or even sign of the returned value.
>> 
>> The corresponding methods `getBytesRead()` and `getBytesWritten()` methods introduced in Java 5 return `long`, and should be used instead when obtaining this information. 
>> 
>> Unrelated to the deprecation itself, the documentation currently does not specify what these methods are expected to return when the number of processed bytes is higher than `Integer.MAX_VALUE`. This PR aims to clarify this in the API specification.
>> 
>> Initally, this PR handles only `Inflater.getTotalIn()`. The other three methods will be updated once the wordsmithing for this method stabilizes.
>
> Eirik Bjørsnøs has updated the pull request with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains 12 additional commits since the last revision:
> 
>  - Use "value" instead of "number of compressed bytes input so far"
>  - Merge branch 'master' into deprecate-total-in-out
>  - Reduce new method description text to one sentence
>  - To align with the Java Language Specification, use "all but the 32 lowest order bits"
>  - Use "highest order bits" instead of "highest bits"
>  - Remove empty line
>  - Add back a note to specify the long-standing behavior of discarding the highest 32 bits of the return value
>  - Use "greater than" instead of "larger than"
>  - Leave first sentence as-is. Simplify the deprecation notice.
>  - Add since="23" to @Deprecated
>  - ... and 2 more: https://git.openjdk.org/jdk/compare/285554fe...8d80c776

The change in [8d80c776] looks fine. If Lance is okay with it then I think go ahead and update the other methods too.

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

PR Comment: https://git.openjdk.org/jdk/pull/17919#issuecomment-1966049658