RFR: 8350147: Replace example in KEM class with the one from JEP 452

[Bradford Wetmore]

On Sat, 15 Feb 2025 14:28:04 GMT, Weijun Wang <weijun at openjdk.org> wrote:

>> The example code in the JEP was much clearer than that in the current `KEM` class.  It's easier to keep the various nested classes straight, rather than using `var`s which require scrolling to see what the return types are. 
>> 
>> Added/tweaked example for clarity.
>> 
>> Generated/checked javadocs, but no regression/JCK tests is necessary.
>
> src/java.base/share/classes/javax/crypto/KEM.java line 76:
> 
>> 74:  *
>> 75:  *     // Sender side
>> 76:  *     KEM senderKEM = KEM.getInstance("ABC-KEM");
> 
> Maybe we should rename the `KEM` and `AlgorithmParameters` algorithms to "ABC". Modern KEM and signature algorithms are usually the same as the key algorithm names.

Even after all the checks, I still missed one!  ;)  Yes, will update.

> src/java.base/share/classes/javax/crypto/KEM.java line 78:
> 
>> 76:  *     KEM senderKEM = KEM.getInstance("ABC-KEM");
>> 77:  *     PublicKey receiverPublicKey = retrieveKey();
>> 78:  *     ABCKEMParameterSpec spec = new ABCKEMParameterSpec(...);
> 
> Maybe we can rename `spec` to `senderSpec`. We already have `senderKEM` and `senderSecret`.

Sure, I debated on this...will update.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/23652#discussion_r1957186884
PR Review Comment: https://git.openjdk.org/jdk/pull/23652#discussion_r1957186912