RFR: 8215788: Clarify JarInputStream Manifest access [v4]

[Alan Bateman]

On Fri, 16 Sep 2022 18:33:46 GMT, Lance Andersen <lancea at openjdk.org> wrote:

>> Okay, in which case what would you think about just saying that the getNextEntry/getNextJarEntry method do not return the Manifest when it's at the start of the stream, and it's unspecified whether they return the Manifest when it located later in the stream. I think this would give us wriggle room to change it in the future.
>
>> Okay, in which case what would you think about just saying that the getNextEntry/getNextJarEntry method do not return the Manifest when it's at the start of the stream, and it's unspecified whether they return the Manifest when it located later in the stream. I think this would give us wriggle room to change it in the future.
> 
> Is this any better:
> 
> 
> 
>  * <p>
>  * When the {@code Manifest} is returned by {@code getManifest()}, the {@link #getNextEntry()}
>  * and {@link #getNextJarEntry()} methods will not return the {@code Manifest}.
>  * If {@code META-INF/} is the first entry in the input stream it will be
>  * also not be returned by {@link #getNextEntry()} and {@link #getNextJarEntry()}. 
>  * </p>
>  * @apiNote 
>  * It is unspecified whether {@link #getNextEntry()} and
>  * {@link #getNextJarEntry()} will return the {@code Manifest}
>  * when the {@code Manifest} occurs later in the input stream.
>  * <p>
>  * {@link JarEntry#getAttributes()} will return the {@code Manifest}'s
>  *  attributes for the current JAR file entry, if any, providing
>  *  {@code getManifest()} returns a {@code Manifest} for the JAR file.
>  * </p>

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.


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.

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

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