On Fri, 16 Sep 2022 18:33:46 GMT, Lance Andersen <lan...@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
