8282648: Weaken the InflaterInputStream specification in order to allow faster Zip implementations

Reviewed-by: lancea, alanb, jpai, mr, darcy

src/java.base/share/classes/java/util/jar/JarFile.java

@@ -822,6 +822,13 @@ public class JarFile extends ZipFile {
     /**
      * Returns an input stream for reading the contents of the specified
      * zip file entry.
+     *
+     * @apiNote The {@code InputStream} returned by this method can wrap an
+     * {@link java.util.zip.InflaterInputStream InflaterInputStream}, whose
+     * {@link java.util.zip.InflaterInputStream#read(byte[], int, int)
+     * read(byte[], int, int)} method can modify any element of the output
+     * buffer.
+     *
      * @param ze the zip file entry
      * @return an input stream for reading the contents of the specified
      *         zip file entry or null if the zip file entry does not exist

src/java.base/share/classes/java/util/jar/JarInputStream.java

@@ -167,10 +167,21 @@ public class JarInputStream extends ZipInputStream {
     }
 
     /**
-     * Reads from the current JAR file entry into an array of bytes.
-     * If {@code len} is not zero, the method
-     * blocks until some input is available; otherwise, no
-     * bytes are read and {@code 0} is returned.
+     * Reads from the current JAR entry into an array of bytes, returning the number of
+     * inflated bytes. If {@code len} is not zero, the method blocks until some input is
+     * available; otherwise, no bytes are read and {@code 0} is returned.
+     * <p>
+     * If the current entry is compressed and this method returns a nonzero
+     * integer <i>n</i> then {@code buf[off]}
+     * through {@code buf[off+}<i>n</i>{@code -1]} contain the uncompressed
+     * data.  The content of elements {@code buf[off+}<i>n</i>{@code ]} through
+     * {@code buf[off+}<i>len</i>{@code -1]} is undefined, contrary to the
+     * specification of the {@link java.io.InputStream InputStream} superclass,
+     * so an implementation is free to modify these elements during the inflate
+     * operation. If this method returns {@code -1} or throws an exception then
+     * the content of {@code buf[off]} through {@code buf[off+}<i>len</i>{@code
+     * -1]} is undefined.
+     * <p>
      * If verification has been enabled, any invalid signature
      * on the current entry will be reported at some point before the
      * end of the entry is reached.