RFR: 8254935: Deprecate the PSSParameterSpec(int) constructor

[Weijun Wang]

On Thu, 24 Mar 2022 00:52:28 GMT, Valerie Peng <valeriep at openjdk.org> wrote:

>> src/java.base/share/classes/java/security/spec/PSSParameterSpec.java line 114:
>> 
>>> 112:      *         recommended to explicitly specify all desired parameter
>>> 113:      *         values with
>>> 114:      *         {@link #PSSParameterSpec(String, String, AlgorithmParameterSpec, int, int) PSSParameterSpec}.
>> 
>> We are deprecating a field so I would say "This field uses default values defined in ... which may become...".
>> 
>> Do we need to write "PKCS #1" with a blank inside? Same below.
>> 
>> Also, the "all desired parameter values" phrase is perfect for the constructor below but this is for a field not a method so "parameters" does not make sense to me. How about something like "Instead of using this field, user should create a new `PSSParameterSpec` object by calling..." or we can just not mention it. User would need to create one anyway.
>
> Well, I did a quick search, it seems both PKCS#X and PKCS #X are used interchangeably. I use PKCS#X to be consistent within this file. Maybe it does not matter much? I thought we tend to return without the space, e.g. PKCS8EncodedKeySpec.getFormat(). Other wording suggestions incorporated. Thanks~

My understanding is that if there is a "#" then there should be a " " before it. However, if the format without the space is already used elsewhere, we can keep using it.

>> src/java.base/share/classes/java/security/spec/PSSParameterSpec.java line 118:
>> 
>>> 116:      * @since 1.5
>>> 117:      */
>>> 118:     @Deprecated(since="19", forRemoval=true)
>> 
>> Do we really want to remove it in the future? It's awkward but probably not so harmful. Removing it may unnecessarily break existing codes. Same with the constructor below.
>
> Hmm, I am under the impression that we tend to use forRemoval=true when deprecating stuff, so users may pay more attention to it. This does not mean that we MUST remove it? Also, marking it for removal would give users more time in case something came up and removal become necessary?

You are right that there is no rule that an API deprecated for removal must be removed. OK, you decide what the best way is.

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

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