RFR: 8215788: Clarify JarInputStream Manifest access [v4]

[Lance Andersen]

On Fri, 16 Sep 2022 18:01:40 GMT, Alan Bateman <alanb 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.

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>

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

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