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

[Lance Andersen]

On Tue, 7 Mar 2023 07:46:25 GMT, Eirik Bjorsnos <duke 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.

Hi Eirik,

Thank you for starting the review of your proposed clarification.  A couple of minor comments.  Also  the copyright should be changed to 2023 with your next update.

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

src/java.base/share/classes/java/util/zip/ZipOutputStream.java line 208:

> 206:      *
> 207:      * This ensures strict compliance with the ZIP specification and
> 208:      * allows optimal performance when processing directory entries.

I think we can remove at least the first part of the sentence regarding "strict compliance" as  "file data" can be interpreted as the contents of the file as 4.1.3 of the App.Note allows for the default compression method to be DEFAULT.  The intent of the apiNote is to remind developers that the use of the STORED compression method is preferred and may be more optimal

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

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