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

[Yakov Shafranovich]

On Thu, 9 Nov 2023 20:41:22 GMT, Kevin Driver <kdriver 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
>
> 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?

will fix

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

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