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

[Weijun Wang]

On Sat, 15 Feb 2025 05:02:44 GMT, Bradford Wetmore <wetmore 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.

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`.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/23652#discussion_r1957127490
PR Review Comment: https://git.openjdk.org/jdk/pull/23652#discussion_r1957127860