RFR: 8215788: Clarify JarInputStream Manifest access

[Lance Andersen]

On Tue, 30 Aug 2022 21:47:03 GMT, Weijun Wang <weijun 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
>
> src/java.base/share/classes/java/util/jar/JarInputStream.java line 62:
> 
>> 60:  *         is the second jar entry
>> 61:  *      </li>
>> 62:  * </ul>
> 
> I wonder if it's necessary to duplicate these lines. How about something like "If ...., then getManifest() returns the manifest and the first call to getNextEntry() returns the entry after it".

The challenge I had with the wording is due to the fact that if "META-INF/" is the first entry in the Zip file, it will not be returned regardless of whether there is a manifest.  So open to suggestions.

> Either say "verified" for both methods or none. Otherwise, it sounds like `getCertificates` might return unverified ones.
> 

Fixed
> Also, you might want to mention:
> 
>     1. If the content of an entry is modified after the file is signed, reading the entry will throw a SecurityException.
> 
Added a note
>     2. These two methods return null if the file is not signed or the signature is not parseable.
Given I link to the javadoc for these methods, this I hope is enough as my goal was not to replace the javadoc for the JarEntry methods.  If you feel the methods should be clarified, happy to work on that next

> src/java.base/share/classes/java/util/jar/JarInputStream.java line 75:
> 
>> 73:  *      </li>
>> 74:  *      <li>
>> 75:  *         All signature entries must immediately follow the {@code manifest}
> 
> We normally say "signature-related entries", which contains both the signature files (.SF) and the signature block files (.DSA/.RSA/.EC) files.

Updated in the next push

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

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