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

[Eirik Bjørsnøs]

On Mon, 26 Feb 2024 19:35:26 GMT, Lance Andersen <lancea at openjdk.org> wrote:

> This sentence to me seems a bit hard to digest and you basically get the point across in the `@deprecated` message

This new text was added after a discussion with Alan (see above) concluded that the method should specify its behavior when the number exceeds  Integer.MAX_VALUE.

Currently it's not possible for the reader to know if the value is clamped to Integer.MAX_VALUE or if bits are discareded. We found the simplest way to specifiy the long standing behavior would be "returns the equivalent of {@code (int) getBytesRead()}" 

As you note, there is a good bit of overlap with the `@deprecated` note. One way to solve that would be to move the specification part of the sentence into the deprecation note and just drop this added sentence in the method specification.

Are we allowed to have normative specification like this inside a deprecation note, or must this be specified in the outside the `@deprecated` note?

The suggested javadoc would look like this:


    /**
     * Returns the total number of compressed bytes input so far.
     *
     * @deprecated 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}.
     * Use {@link #getBytesRead()} instead.
     *
     * @return the total number of compressed bytes input so far
     */

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

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