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

[Jaikiran Pai]

On Mon, 19 Feb 2024 20:55:06 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 incrementally with one additional commit since the last revision:
> 
>   Fix {@link #getBytesRead}

src/java.base/share/classes/java/util/zip/Inflater.java line 642:

> 640:      * the 32 highest order bits, as if the {@link #getBytesRead()}
> 641:      * method was called followed by a narrowing conversion from <code>long</code>
> 642:      * to <code>int</code>.

I think we should leave this part of the javadoc comment as-is and not change it.

src/java.base/share/classes/java/util/zip/Inflater.java line 651:

> 649:      * the 32 highest order bits
> 650:      */
> 651:     @Deprecated

Hello Eirik, the `Deprecated` annotation allows for a `since` property. I think we should use it here `@Deprecated(since=23)`.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/17919#discussion_r1495336375
PR Review Comment: https://git.openjdk.org/jdk/pull/17919#discussion_r1495335607