RFR: 8215788: Clarify JarInputStream Manifest access

[Alan Bateman]

On Thu, 1 Sep 2022 17:56:03 GMT, Lance Andersen <lancea at openjdk.org> wrote:

>>> It's better. Do you need to explicitly say "For all other cases"?
>> 
>> I thought it is worth being specific,  but happy to leave it out if you and others prefer
>>> 
>>> My original comment was more about explaining `getManifest()` and `getNextEntry()` in the same if. It's still doable.
>> 
>> I think the challenge is there is not an exact match to the behavior between `getManifest()` and `getNext[Jar]Entry()`.    We also have the case if the manifest is the first entry and META-INF/ is the 2nd or later entry, then  META-INF/ will be returned by `JarInputStream`.  ` ZipInputStream` will return all entries which differs from `JarInputStream` so thought it made sense to be specific but perhaps I am overthinking it.
>
> I could do tweak further to say:
> 
> _`getManifest()` will return the Manifest if it is the first entry or META-INF/ is the first entry and the Manifest is the second entry within the Jar file.   When the Manifest is returned by `getManifest()`,  the `getNextEntry()` and `getNextJarEntry()` methods will not return the Manifest_
> 
> Is that more what you were thinking?

I read the current draft and it makes we wonder if it would be simpler to just replace the class description with something like this:


 * The JarInputStream class is used to read the contents of a JAR file from
 * an input stream. It extends ZipInputStream with support for reading an optional
 * manifest named "META-INF/MANIFEST.MF" when it is found at as the first entry in
 * the stream. If the first entry in the stream is "META-INF/" then it is skipped,
 * in which case the manifest is found if it is the second entry in the stream.
 *
 * JarInputStream defines the getNextJarEntry() method to iterate through the
 * JAR file entries in the stream. The method reads the metadata for the next JAR
 * file entry in the stream and positions the input stream to read the entry's
 * file data. The first entry found by getNextJarEntry() (or getNextEntry())
 * will follow the manifest when the manifest is the first entry in the JAR
 * file (or the second entry when the first entry is "META-INF/").

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

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