RFR: 8215788: Clarify JarInputStream Manifest access [v4]

[Lance Andersen]

On Sat, 17 Sep 2022 08:05:37 GMT, Alan Bateman <alanb at openjdk.org> wrote:

> It's a bit better but I think we can make it clearer and also link the JAR Manifest section of the JAR file spec. Can you try this:
> 
> ```
>  * <p> The {@link #getManifest() getManifest} method is used to read the
>  * <a href="{@docRoot}/../specs/jar/jar.html#jar-manifest">JAR Manifest</a>
>  * from the entry {@code META-INF/MANIFEST.MF} when it is the first entry
>  * in the stream (or the second entry in the case that the fist entry is
>  * {@code META-INF/} and the second entry {@code META-INF/MANIFEST.MF}).
>  *
>  * <p> The {@link #getNextJarEntry()} and {@link #getNextEntry()} methods are
>  * used to read JAR file entries from the stream. These methods skip over the
>  * manifest ({@code META-INF/MANIFEST.MF}) when it is at the beginning of the
>  * stream. In other words, these methods do not return an entry for the manifest
>  * when the manifest is the first entry in the stream. If the first entry is
>  * {@code META-INF/} and the second entry is the manifest then both are skipped
>  * over by these methods. Whether these methods skip over the manifest when it
>  * appears later in the stream is not specified.
> ```
> 
Revised using the above

> I think we also have to update getManifest method to align with the above as doesn't say anything about the manifest needing to be at the beginning of the stream.

Ok,  I added some verbiage similar to what I had originally before we decided to update the class description.  Please let me know if this is what you had in mind

Thank you again for your feedback

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

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