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

[Xue-Lei Andrew Fan]

On Wed, 6 Apr 2022 00:14:04 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~

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

> 1049:      * Returns the parameters used with this cipher.
> 1050:      *
> 1051:      * <p>If this cipher has been previously initialized with parameters,

> If this cipher has been previously initialized with parameters, this method returns the same parameters.

Previously, "may" is used ("may be the same ...").  This change looks too strict for compatibility.  I had a look at the AES implementation, the parameters initialized with init() could be filtered and modified before saving the parameters related class fields.

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

> 1051:      * <p>If this cipher has been previously initialized with parameters,
> 1052:      * this method returns the same parameters. Otherwise, this method may
> 1053:      * return a combination of user-supplied, default and randomly generated

> ... a combination of user-supplied, default and randomly generated parameter values ...

Other than init(), which APIs could impact the user-supplied parameters?  Is it the getInstance()?

Is it OK to just use the provider-specific default values instead, by replacing the "a combination of user-supplied, default and randomly generated ..."?

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

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