RFR: 8215788: Clarify JarInputStream Manifest access [v6]

[Weijun Wang]

On Mon, 19 Sep 2022 17:53:51 GMT, Lance Andersen <lancea 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..
>
>> > 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>

Does this mean that the "Verifying a JarInputStream" should also avoid mentioning "getManifest method returns the manifest"? I understand precisely it should be "getManifest method is able to return the manifest if you call it".

It almost sounds like we should first define the concepts of "well-formed JAR file" and "well-formed signed JAR" and then specify what these methods behave.

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

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