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

[Alan Bateman]

On Fri, 10 Nov 2023 15:44:19 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
>
> Yakov Shafranovich has updated the pull request incrementally with two additional commits since the last revision:
> 
>  - Fixed more line breaks
>  - fixed line breaks

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

> 308:  * considered duplicates, which can result in unexpected behavior such as wrong
> 309:  * metadata or content being returned when parsing archives containing
> 310:  * duplicate names.

The jdk.zipfs module is the JDK's ZIP file system provider, it allows the contents of a ZIP or JAR file be treated as a file system. I think what is missing from this module description is the mapping of file system concepts to ZIP files. If we added a section to the documentation for that then it would be a place to document the file separator, normalization, how directories and file tree are synthesized, and the limitation that a file system cannot be constructed when it leads to have several entries in a directory having equal names. There's a lot more that could be added but hopefully you can see that an implNote and warnings just doesn't work as a way to present the mapping.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16424#discussion_r1390232094