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

[Sean Mullan]

On Wed, 27 Apr 2022 19:48:01 GMT, Valerie Peng <valeriep at openjdk.org> wrote:

>>> As for the 2nd sentence, it boils down whether we requires provider to generate default parameters and return it when parameter is required. Existing javadoc states that null is returned when parameter is not required. Given Cipher covers many algorithms, if a provider does not want to generate a default parameter when parameter is required, it can't return null when getParameters() is called.
>> 
>> Ok, maybe we need to reset the context. What was the main issue with the current specification that you were trying to fix? I read the associated bug report. It sounds like there were two issues:
>> 
>> - ProviderException can be thrown, but the method does not declare it in the throws clause. That doesn't seem to be addressed here - do you think it should be?
>> - cases when null may be returned as opposed to throwing a ProviderException
>> 
>> It could be that what is really just needed is an @throws ProviderException, ex:
>> 
>> "If this cipher implementation requires algorithm parameters to be passed in at initialization but was not initialized with any".
>> 
>> and a slight tweak to the description (changes in italics):
>> 
>> "... if this cipher _can generate required_ algorithm parameters but was not initialized with any."
>
> I don't see the ProviderException being mentioned?
> Per the description under JDK-8209038, the requests are:
> 1) describe the returned parameters following what's in Signature class, i.e. if this object has been initialized with parameters then ..., if this object has not been initialized with parameters, then ..... (<= Xuelei raises compatibility concern and trying to describe all this would make it very lengthy, so the proposed changes reverted back to the original syntax, e.g. describing the returned parameters but not including the scenarios) 
> 2) allow null to be returned if providers cannot generate default parameters. (<= this is addressed in the proposed changes)
> 3)  accommodate algorithm-specific/provider-specific implementation on how parameters is handled. (<= this is addressed in the proposed changes as well. However, this part in Signature class needs update since it states the the SAME parameters are returned but AlgorithmParameterSpec may not require all parameter values to be specified.)

Sorry, I should have been more specific. JDK-8209038 references JDK-8206171 which I think was filed by the TCK team. In that bug description, it says:

> This bug is filed for clarification of specification (see comment)
> Please clarify the specification to include a possible exception being thrown (ProviderException for RSASSA-PSS) or other possible exceptions for future Signature algorithms that require mandatory parameters by the user before any operations could be performed, and user did not set any parameters before using the Signature operations (sign, update, verify).
> Or
> null could be returned (as per specification)

I assumed the `ProviderException` case could potentially apply to a `Cipher` algorithm as well.

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

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