RFR: 8347946: Add API note that caller should validate/trust signers to the getCertificates and getCodeSigners methods of JarEntry and JarURLConnection

[Jaikiran Pai]

On Wed, 19 Feb 2025 10:43:06 GMT, Marcono1234 <duke at openjdk.org> wrote:

>> This change adds an API note to these methods recommending that the caller should perform further validation steps on the code signers that signed the JAR file, such as validating the code signer's certificate chain, and determining if the signer should be trusted. There was already a similar warning in the `JarFile` and `JarInputStream` class descriptions, but this adds a similar and more direct warning at the methods that return the code signer's certificates.
>> 
>> 2 other smaller changes:
>>  - In `JarEntry.getCertificates`, added a recommendation to use the `getCodeSigners` method instead
>>  - Added details of the order of the returned certificates to `JarURLConnection.getCertificates` (copied from `JarEntry.getCertificates`)
>
> src/java.base/share/classes/java/util/jar/JarEntry.java line 100:
> 
>> 98:      * reached. Otherwise, this method will return {@code null}.
>> 99:      *
>> 100:      * <p>It is recommended to use the {@link getCodeSigners} method instead,
> 
> Isn't this missing a `#` to be a valid link?
> Suggestion:
> 
>      * <p>It is recommended to use the {@link #getCodeSigners} method instead,
> 
> 
> (Please don't use the "Commit suggestion" button to not include me as author)

I had a similar reaction when I first saw it. So I checked the javadoc specification the other day and it states https://docs.oracle.com/en/java/javase/23/docs/specs/javadoc/doc-comment-spec.html#references:


The most general form of a reference is:

    module/package.class#member

This form is used by the see, link and linkplain tags.

Leading components can be omitted when they can be inferred from the surrounding context. Trailing components can be omitted when they are not required.

... When the reference is to a member of the same class as that containing the documentation comment, all parts of the reference up to and including the # may be omitted, although the '#' may be retained for clarity.


So, syntactically, it's fine in the current form.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/23616#discussion_r1961450370