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

[Eirik Bjørsnøs]

On Tue, 27 Feb 2024 19:59:08 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:
> 
>   Reduce the deprecation note to "Use {@link #getBytesRead()} instead"

After some offline discussion about the redundant text, we decided to keep to the new method description text, but reduce the `@deprecated` note to simply refer to the replacement method:


/**
 * Returns the total number of compressed bytes input so far.
 * <p>
 * This method returns the equivalent of {@code (int) getBytesRead()}
 * and therefore cannot return the correct value when it is greater
 * than {@link Integer#MAX_VALUE}.
 *
 * @deprecated Use {@link #getBytesRead()} instead
 *
 * @return the total number of compressed bytes input so far
 */


Barring any objections, I'll to go ahead with the update of the rest of the methods and update the CSR draft tomorrow.

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

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