RFR: 8209038: Clarify the javadoc of Cipher.getParameters() [v2]

[Sean Mullan]

On Wed, 13 Apr 2022 22:04:03 GMT, Valerie Peng <valeriep at openjdk.org> wrote:

>> Anyone can help review this javadoc update? The main change is the wording for the method javadoc of Cipher.getParameters()/CipherSpi.engineGetParameters(). The original wording is somewhat restrictive and request is to broaden this to accommodate more scenarios such as when null can be returned.
>> The rest are minor things like add {@code } to class name and null, and remove redundant ".". 
>> 
>> Will file CSR after the review is close to being wrapped up.
>> Thanks~
>
> Valerie Peng has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Update w/ review feedbacks

src/java.base/share/classes/javax/crypto/Cipher.java line 1054:

> 1052:      * this cipher, or may contain additional default or random parameter
> 1053:      * values used by the underlying cipher implementation if this cipher can
> 1054:      * successfully generate the required parameter values when not supplied.

A few comments:

1. I don't think this new text covers the case where the cipher is not initialized with any parameters, but the provider returns parameters. I tried to think of how to say that all in one sentence, but I think it is best to have two sentences covering each case, ex:

"If this cipher was not initialized with parameters, the returned parameters may be null or may be ..."
"If this cipher was initialized with parameters, the returned parameters may be the same or may be ..."

2. Should `Signature.getParameters` be updated to be consistent? Are there any cases, or could there be, where a signature provider may return additional parameters other than what the user specified?

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

PR: https://git.openjdk.java.net/jdk/pull/8117