RFR: JDK-8319122: Improve documentation of various Zip-file related APIs

[Kevin Driver]

On Mon, 30 Oct 2023 17:26:53 GMT, Yakov Shafranovich <duke at openjdk.org> wrote:

> The various Zip/Jar-file related Java APIs have some long-standing differences or peculiarities with respect to the ZIP-file specification or compared to other implementations which should be documented in the API-doc. This documents the following:
> - Cache of JAR files in JarURLConnection class
> - Cache of JAR/ZIP files in JarFile and ZipFile classes
> - Unexpected behavior when parsing ZIP files with duplicate entries in JarFile and ZipFile classes, as well as the zipfs provider
> - Directories and filenames with the same name considered to be the same in ZipFile class
> - Possible issues when local and central headers conflict in ZipInputStream class
> 
> Related JBS report:
> https://bugs.openjdk.org/browse/JDK-8319122

Marked as reviewed by kdriver (Committer).

src/java.base/share/classes/java/net/JarURLConnection.java line 129:

> 127:  * JAR files retrieved by this class might get cached for performance reasons which can result
> 128:  * in unexpected behavior if the JAR files are modified while being read using this class.
> 129:  * If such behavior is undesirable, please use the {@link URLConnection#setUseCaches(boolean)} method to disable caching.

consider a manual line wrap here, or is this ~80 chars?

src/java.base/share/classes/java/util/zip/ZipFile.java line 104:

> 102:  * being returned due to internal caching.
> 103:  *
> 104:  * Additionally, for compatibility with earlier versions of the JDK, files and directories with the same name (such as "foobar" and "foobar/")

consider a manual line wrap in these as well, or is this ~80 chars?

src/jdk.zipfs/share/classes/module-info.java line 303:

> 301:  * may occur such as metadata or content from the later entry being returned due to internal caching.
> 302:  *
> 303:  * Additionally, for compatibility with earlier versions of the JDK, files and directories with the same name (such as "foobar" and "foobar/")

consider a manual line wrap in these as well, or is this ~80 chars?

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

PR Review: https://git.openjdk.org/jdk/pull/16424#pullrequestreview-1723465685
PR Review Comment: https://git.openjdk.org/jdk/pull/16424#discussion_r1388560373
PR Review Comment: https://git.openjdk.org/jdk/pull/16424#discussion_r1388561727
PR Review Comment: https://git.openjdk.org/jdk/pull/16424#discussion_r1388562238