RFR: 8215788: Clarify JarInputStream Manifest access [v6]

[Lance Andersen]

On Mon, 19 Sep 2022 06:34:00 GMT, Alan Bateman <alanb at openjdk.org> wrote:

> > I can remove, but I am not sure I agree we need to describe main vs attribute here given we are pointing to the Jar spec and if there is any discussion of Pre-entry attributes, it should be in JarEntry IMHO. I guess the clarification I was trying to make, apparently unsuccessfully is that `JarEntry` will not have access to the attributes if `getManifest` does not return the Manifest.
> 
> Wording it is hard. The draft wording made it look that must call getManifest, ignore the return value, and then subsequent calls to JarEntry::getAttributes will return attributes for the JAR file entry. I think to properly describe would require more setup to explain that a manifest can optionally include per entry attributes and these are read with JarEntry::getAttributes when the manifest is found at the beginning of the stream..

Thinking about this some more, would the following be any better:


 * <p>
 * The {@code Manifest} for a JAR file may include
 *  <a href="{@docRoot}/../specs/jar/jar.html#main-attributes">main</a> and
 *  <a href="{@docRoot}/../specs/jar/jar.html#per-entry-attributes">per entry</a>
 *  attributes. {@link JarEntry#getAttributes()} will return the per entry
 *  attributes for the current JAR file entry, if any, providing
 *  {@code getManifest()} returns the {@code Manifest} for the JAR file.
 *  </p>

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

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