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

[Eirik Bjørsnøs]

On Tue, 20 Feb 2024 07:13:41 GMT, Jaikiran Pai <jpai at openjdk.org> wrote:

>> 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.

@jaikiran 

This PR has two (somewhat independent) goals:

1) Officially deprecate the methods by adding `@Deprecated` annotations and Javadoc tags, and cleaning up the deprecation notice including the recommendation to use getBytes[Read|Written].

2) Clarify what the method actually returns when the number of processed bytes is larger than `Integer.MAX_VALUE`. This is currently unspecified.

The need to clarify the return value was raised by @AlanBateman, here: 

https://mail.openjdk.org/pipermail/core-libs-dev/2024-February/119334.html


I'm surprised the spec for these methods wasn't clarified 
in Java 5 when the new methods to return long were added. Right not, 
it's not clear from the spec how the older methods behave when the 
number of bytes is greater than Integer.MAX_VALUE.


(I'll add that it isn't even possible for the caller to know whether the number of processed bytes was in fact larger than `Integer.MAX_VALUE` without some form of external heuristics.)

I added the verbiage in the leading sentence specificallty to address this "clarify the return value" concern. If we drop it like you suggest, I think that would leave return value when the number of bytes processed is larger than Integer.MAX_VALUE unspecified.

If we decide to leave the leading sentence as-is, then it would be misleading so I think it should be followed by a sentence with some form of clarification. 

Perhaps it would be better to specify the return value by the implementation? So adding a `{@snippet}` or similar showing `(int)getBytesRead()`? I'm guessing there should be some prior art to take inspiration from here?

@AlanBateman Do you have input on how to specify the return value of this method concisely?

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

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