Summary

Officially mark methods getTotalIn() and getTotalOut() of classes java.util.zip.Inflater and java.util.zip.Deflater as deprecated. Augment the method descriptions to clearly specify behavior when their return value exceeds Integer.MAX_VALUE.

Problem

The classes java.util.zip.Inflater and java.util.zip.Deflater each have a pair of methods getTotalIn() and getTotalOut(), returning the number of compressed/uncompressed bytes processed so far.

Since these methods have an int return type, they cannot return correct values when the number of processed bytes exceeds Integer.MAX_VALUE. Long standing behavior is to discards all but the lowest 32 bits with a narrowing conversion to int, but this behavior is currently not specified in the method descriptions.

Replacements methods with a long return type were introduced in Java 5, along with notes in the legacy methods recommending the use of the new methods. However, the old methods were never officially marked as deprecated.

Solution

(a) Officially annotate the following methods as deprecated, not for removal, since Java 23:

• java.util.zip.Inflater.getTotalIn()
• java.util.zip.Inflater.getTotalOut()
• java.util.zip.Deflater.getTotalIn()
• java.util.zip.Deflater.getTotalOut()

(b) Add deprecation notes recommending the use of the replacement methods introduced in Java 5.

(c) Augment the method descriptions to specify the long-standing behavior for return values greater than Integer.MAX_VALUE and clarify that the method cannot return correct values in such cases.

Specification

diff --git a/src/java.base/share/classes/java/util/zip/Deflater.java b/src/java.base/share/classes/java/util/zip/Deflater.java
index 6d00a45742b..ca123bd36da 100644
--- a/src/java.base/share/classes/java/util/zip/Deflater.java
+++ b/src/java.base/share/classes/java/util/zip/Deflater.java
@@ -822,12 +822,16 @@ public int getAdler() {
     /**
      * Returns the total number of uncompressed bytes input so far.
      *
-     * <p>Since the number of bytes may be greater than
-     * Integer.MAX_VALUE, the {@link #getBytesRead()} method is now
-     * the preferred means of obtaining this information.</p>
+     * @implSpec
+     * 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 uncompressed bytes input so far
      */
+    @Deprecated(since = "23")
     public int getTotalIn() {
         return (int) getBytesRead();
     }
@@ -848,12 +852,16 @@ public long getBytesRead() {
     /**
      * Returns the total number of compressed bytes output so far.
      *
-     * <p>Since the number of bytes may be greater than
-     * Integer.MAX_VALUE, the {@link #getBytesWritten()} method is now
-     * the preferred means of obtaining this information.</p>
+     * @implSpec
+     * This method returns the equivalent of {@code (int) getBytesWritten()}
+     * and therefore cannot return the correct value when it is greater
+     * than {@link Integer#MAX_VALUE}.
+     *
+     * @deprecated Use {@link #getBytesWritten()} instead
      *
      * @return the total number of compressed bytes output so far
      */
+    @Deprecated(since = "23")
     public int getTotalOut() {
         return (int) getBytesWritten();
     }
diff --git a/src/java.base/share/classes/java/util/zip/Inflater.java b/src/java.base/share/classes/java/util/zip/Inflater.java
index 3c54efc2b2f..4b106fd39ec 100644
--- a/src/java.base/share/classes/java/util/zip/Inflater.java
+++ b/src/java.base/share/classes/java/util/zip/Inflater.java
@@ -643,12 +643,16 @@ public int getAdler() {
     /**
      * Returns the total number of compressed bytes input so far.
      *
-     * <p>Since the number of bytes may be greater than
-     * Integer.MAX_VALUE, the {@link #getBytesRead()} method is now
-     * the preferred means of obtaining this information.</p>
+     * @implSpec
+     * 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
      */
+    @Deprecated(since = "23")
     public int getTotalIn() {
         return (int) getBytesRead();
     }
@@ -669,12 +673,16 @@ public long getBytesRead() {
     /**
      * Returns the total number of uncompressed bytes output so far.
      *
-     * <p>Since the number of bytes may be greater than
-     * Integer.MAX_VALUE, the {@link #getBytesWritten()} method is now
-     * the preferred means of obtaining this information.</p>
+     * @implSpec
+     * This method returns the equivalent of {@code (int) getBytesWritten()}
+     * and therefore cannot return the correct value when it is greater
+     * than {@link Integer#MAX_VALUE}.
+     *
+     * @deprecated Use {@link #getBytesWritten()} instead
      *
      * @return the total number of uncompressed bytes output so far
      */
+    @Deprecated(since = "23")
     public int getTotalOut() {
         return (int) getBytesWritten();
     }