RFR: 8215788: Clarify JarInputStream Manifest access

[Weijun Wang]

On Fri, 26 Aug 2022 15:48:55 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

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

> 36:  * It provides support for reading an optional {@linkplain JarFile#MANIFEST_NAME Manifest}
> 37:  * entry. The {@linkplain JarFile#MANIFEST_NAME Manifest} can be used to store
> 38:  * meta-information about the JAR file and its entries.

No need to linkplain twice.

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

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.

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.

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

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