RFR: 8215788: Clarify JarInputStream Manifest access

[Weijun Wang]

On Wed, 31 Aug 2022 18:31:13 GMT, Lance Andersen <lancea at openjdk.org> wrote:

>> 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.

That's right. But I think we care about the MANIFEST more. It's not that important whether META-INF is there.

>> src/java.base/share/classes/java/util/jar/JarInputStream.java line 74:
>> 
>>> 72:  *  {@linkplain  JarEntry#getCertificates()} may be called to obtain the certificates
>>> 73:  *  for this entry and {@linkplain JarEntry#getCodeSigners()} may be called to obtain
>>> 74:  *  the verified signers.
>> 
>> Either say "verified" for both methods or none. Otherwise, it sounds like `getCertificates` might return unverified ones.
>> 
>> 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.
>> 2. These two methods return null if the file is not signed or the signature is not parseable.
>
>> 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

Fair enough.

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

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