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

[Xue-Lei Andrew Fan]

On Tue, 12 Apr 2022 03:27:59 GMT, Valerie Peng <valeriep at openjdk.org> wrote:

>> I read the following methods in com.sun.crypto.provider.CipherCore:
>> 
>>     void init(int opmode, Key key, AlgorithmParameterSpec params,
>>             SecureRandom random)
>> 
>> where the 'params' are converted to IV byte array for further processing. 
>> 
>> 
>>     void init(int opmode, Key key, AlgorithmParameters params,
>>               SecureRandom random)
>> 
>> where the spec is retrieved from the 'params', and then pass the call to the init() method above.
>> 
>> 
>>     AlgorithmParameters getParameters(String algName) {
>> 
>> where the returned parameters are re-constructed.
>> 
>> It may be fine to use a strict spec, but there is a chance to have compatibility impact unless we check the implementation carefully.  It may not worthy the risks as a behavioral update may be not necessary for developers.
>
> How about this then?
> 
>      * <p>The returned parameters may be the same that were used to initialize
>      * this cipher, or may contain additional default and random parameter
>      * values used by the underlying cipher implementation if this
>      * cipher can successfully generate the required parameter values when
>      * not supplied. Otherwise, {@code null} is returned.

I like the revised spec more. 

BTW, for "... contain additional default and random parameter values ...", is "or" more common than "and" in English?

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

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