RFR: 8215788: Clarify JarInputStream Manifest access [v7]

[Alan Bateman]

On Sun, 18 Sep 2022 20:43:25 GMT, Lance Andersen <lancea at openjdk.org> wrote:

>> Please review this PR which updates  the JarInputStream class description to clarify when the Manifest is accessible via JarInputStream::getManifest and JarInputStream::get[Jar]Entry.
>> 
>> It is worth noting that with this update, we are finally documenting  behavior that dates back to when this class was added to JDK 1.2
>> 
>> 
>> Best,
>> Lance
>
> Lance Andersen has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Updated to address latest feedback

src/java.base/share/classes/java/util/jar/JarInputStream.java line 60:

> 58:  *
> 59:  *  <h2>Verifying a JarInputStream</h2>
> 60:  *  {@link #JarInputStream(InputStream, boolean)} may be used to

I realise you've had a few iterations with Max on this section but I'm concerned that the text is telling the reader that they should use the 2-arg constructor to verify the signatures when a JAR is signed. The default is to verify and the a reason to use the 2-arg constructor is when you want to opt out, not opt-in.

I think the intro to this section will need to start with a sentence to say that JAR files can be signed (link to specs/jar/jar.html#signed-jar-file) and that JarInputStream can read a signed JAR from the input stream. As per the description further up, the manifest must be at the start of the stream.

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

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