RFR: 8303923: ZipOutStream::putEntry should include an apiNote to indicate that the STORED compression method should be used when writing directory entries

[Eirik Bjorsnos]

On Sun, 19 Mar 2023 13:50:40 GMT, Lance Andersen <lancea at openjdk.org> wrote:

>> ZipOutputStream currently writes directory entries using the DEFLATED compression method. This does not strictly comply with the APPNOTE.TXT specification and is also about 10x slower than using the STORED compression method.
>> 
>> Because of these concerns, `ZipOutputStream.putNextEntry` should be updated with an `@apiNote` recommending
>> the use of the STORED compression method for directory entries.
>> 
>> Suggested CSR in the first comment.
>
> src/java.base/share/classes/java/util/zip/ZipOutputStream.java line 198:
> 
>> 196:      *
>> 197:      * {@snippet lang="java" :
>> 198:      *     ZipEntry e = ...;
> 
> Please make this an actual value as the snippet should be valid code

I initially used a directory as an example: `ZipEntry e = new ZipEntry("dir/")`, but then @AlanBateman  suggested to make it more generic:

https://mail.openjdk.org/pipermail/core-libs-dev/2023-March/101686.html

> For the note then you might want to change it to "ZipEntry e = ..." because the reader see the trailing slash after dir so it is obviously a directory. 

I agree valid code would be preferrable. Not sure how to make it valid though, since the `isDirectory` part suggests the  path is unknown. Could an undefined local variable work?


ZipEntry e = new ZipEntry(name);


Or perhaps with a comment:


ZipEntry e = new ZipEntry(name); // name could be a file or directory

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

PR: https://git.openjdk.org/jdk/pull/12899