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

[Valerie Peng]

On Tue, 26 Apr 2022 19:26:41 GMT, Sean Mullan <mullan at openjdk.org> wrote:

>> I have filed the PR for the Signature at: https://github.com/openjdk/jdk/pull/8396
>> Best to get it done along with this one.
>
>> 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.)

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

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