On Thu, 1 Apr 2021 13:29:42 GMT, Weijun Wang <wei...@openjdk.org> wrote:
>> I'm not sure if it's appropriate to specify the default value in this >> method. As long as there is an `RSAPSSParameterSpec` object, there must be a >> non-null `PSSParameterSpec` inside and it is the one that was used to >> construct this object. >> >> I am thinking if we can append the following to the `@implSpec` in the class >> spec: >> >> * One can obtain this default value using the following expression: >> * <pre><code> >> * XMLSignatureFactory.getInstance() >> * .newSignatureMethod(SignatureMethod.RSA_PSS, null) >> * .getParameterSpec() >> * </code></pre> >> >> >> but this makes it more like an `@implNote` instead of an `@implSpec`. > > I added the new lines as `@implNote` and kept the old `@implSpec` there > (since it's still a requirement for implementations). New commit pushed. CSR > updated as well. Ok, I understand now. I think `@implSpec` (and probably the `@implNote`) are in the wrong class. `@implSpec` means the implementation of this class. But this class is final and does not contain that logic. The logic of specifying/returning the defaults is in the JDK (XMLDSig provider) implementation of `SignatureMethod`. So I think it belongs there. In this class, you could add a sentence/link to `SignatureMethod`, something like "See SignatureMethod for how default values are determined when the parameters are not specified." Also, I think the `@implSpec` needs to be more specific, and also cover the cases where some, but not all of the parameters are specified and defaults are then used. For this, you will need to be more general, as the default salt length is based on what hash algorithm is being used. As for `@implNote`, this probably could use more discussion, but it might be better to make this part of the specification. If some implementations can return null, and others return defaults, it complicates the application's logic. The RFC has clearly specified what the defaults should be, so maybe the easiest thing to do is to make all implementations comply by also making it part of the API contract, and hiding the XML details as to whether the parameter was actually specified or not, which should not matter to applications. ------------- PR: https://git.openjdk.java.net/jdk/pull/3181
