RFR: 8215788: Clarify JarInputStream Manifest access

[Lance Andersen]

On Tue, 13 Sep 2022 20:39:31 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 36:
> 
>> 34:  * The {@code JarInputStream} class, which extends {@linkplain ZipInputStream},
>> 35:  * is used to read the contents of a JAR file from an input stream.
>> 36:  * It provides support for reading an optional {@linkplain JarFile#MANIFEST_NAME Manifest}
> 
> `Manifest` above is the same as the one below. If the one below is in fixed-width, so should be the one above.

Could you please clarify what you are suggesting.  I am using the  `@linkplain` to provide a means to see the actual Manifest name.   I am happy to tweak, just need (perhaps an example) of what you would like

> src/java.base/share/classes/java/util/jar/JarInputStream.java line 67:
> 
>> 65:  *      </li>
>> 66:  *      <li>
>> 67:  *         All signature-related entries must immediately follow the {@code Manifest}
> 
> No need to say `must`. This is is one of the requirements.

addressed in the next update

> src/java.base/share/classes/java/util/jar/JarInputStream.java line 78:
> 
>> 76:  * <b>Note:</b>If a {@code JarEntry} is modified after the Jar file is signed,
>> 77:  * a {@linkplain SecurityException} will be thrown when an attempt is made to
>> 78:  * read the entry.
> 
> Not sure if the the `an attempt` word is precise. The exception is only thrown when the last byte is read.

Are you suggesting change:

"...will be thrown when an attempt is made to read the entry."

to

"...will be thrown when the entry has been read."

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

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