RFR: 8253176: Signature.getParameters should specify that it can throw UnsupportedOperationException [v2]

[Valerie Peng]

On Wed, 27 Apr 2022 23:15:41 GMT, Valerie Peng <valeriep at openjdk.org> wrote:

>> src/java.base/share/classes/java/security/Signature.java line 1014:
>> 
>>> 1012:      * {@code AlgorithmParameters}. If the required
>>> 1013:      * parameters were not supplied and the underlying signature implementation
>>> 1014:      * can generate the parameter values, it will be returned. Otherwise,
>> 
>>> If the required parameters were not supplied and the underlying signature implementation can generate the parameter values, it will be returned.
>> 
>> What does it refer to with 'it'? Is 'it' refer to the implementation generated parameter values?
>> 
>>> If the required parameters were not supplied and the underlying signature implementation can generate the parameter values, it will be returned. Otherwise, {@code null} is returned.
>> 
>> The logic looks like
>> 
>>     if (A & B) {
>>         // it will be returned
>>     } else {
>>         // {@code null} is returned.
>>     }
>> 
>> If I read it correctly, the behavior may look like:
>> 1. If the required parameters were supplied, {@code null} is returned; (if !A)
>> 2. if the underlying signature implementation cannot generate the parameter values, {@code null} is returned; (if !B)
>> 3. if not 1 and 2, ... (if A & B)
>> 
>> It does not look like right.  The expected behavior may be:
>> 
>>     if (A) {
>>         if (B) {
>>             // it will be returned
>>         } else {
>>             // {@code null} is returned.
>>         }
>>     }
>> 
>> 
>> Maybe, the confusion could be mitigated by re-org the logic:
>> 
>>      if (A & !B) {
>>             // {@code null} is returned.
>>      } // Otherwise, refer to 1st sentence.
>> 
>> 
>> "The returned parameters may be the same that were used to initialize this signature, or may contain additional default or random parameter values used by the underlying signature implementation.   {@code null} is returned if the required parameters were not supplied and the underlying signature implementation cannot generate the parameter values."
>> 
>> Similar comment to [PR 8117](https://github.com/openjdk/jdk/pull/8117), if you want to use similar description there as well.
>
>> What does it refer to with 'it'? Is 'it' refer to the implementation generated parameter values?
> 
> 'It' refers to the parameters containing all of the parameter values including the supplied ones and provider-generated ones if any.

Can you clarify what is the A and B that you are referring to? The way I read it, it has more than 2 conditions... So, best to clarify the conditions first.

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

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