RFR: 8279598: Provide adapter from RandomGenerator to Random [v19]

[Joe Darcy]

On Wed, 16 Mar 2022 14:54:41 GMT, Yasser Bazzi <duke at openjdk.java.net> wrote:

>> Hi, could i get a review on this implementation proposed by Stuart Marks, i decided to use the https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/random/RandomGenerator.html interface to create the default method `asRandom()` that wraps around the newer algorithms to be used on classes that do not accept the new interface.
>> 
>> Some things to note as proposed by the bug report, the protected method next(int bits) is not overrided and setSeed() method if left blank up to discussion on what to do with it.
>> 
>> Small test done on https://gist.github.com/YShow/da678561419cda8e32fccf3a27a649d4
>
> Yasser Bazzi has updated the pull request incrementally with one additional commit since the last revision:
> 
>   add since in javadoc

> The current API docs on `Random.setSeed` look like:
> 
> ```java
>     /**
>      * Sets the seed of this random number generator using a single
>      * {@code long} seed. The general contract of {@code setSeed} is
>      * that it alters the state of this random number generator object
>      * so as to be in exactly the same state as if it had just been
>      * created with the argument {@code seed} as a seed. The method
>      * {@code setSeed} is implemented by class {@code Random} by
>      * atomically updating the seed to
>      *  <pre>{@code (seed ^ 0x5DEECE66DL) & ((1L << 48) - 1)}</pre>
>      * and clearing the {@code haveNextNextGaussian} flag used by {@link
>      * #nextGaussian}.
>      *
>      * <p>The implementation of {@code setSeed} by class {@code Random}
>      * happens to use only 48 bits of the given seed. In general, however,
>      * an overriding method may use all 64 bits of the {@code long}
>      * argument as a seed value.
>      *
>      * @param seed the initial seed
>      */
> ```
> 
> An updated version would possibly look like:
> 
> ```java
>     /**
>      * Sets the seed of this random number generator using a single
>      * {@code long} seed (optional operation).
>      * 
>      * @implSpec The general contract of {@code setSeed} is
>      * that it alters the state of this random number generator object
>      * so as to be in exactly the same state as if it had just been
>      * created with the argument {@code seed} as a seed.
>      * 
>      * <p>The method {@code setSeed} is implemented by class
>      * {@code Random} by atomically updating the seed to
>      *  <pre>{@code (seed ^ 0x5DEECE66DL) & ((1L << 48) - 1)}</pre>
>      * and clearing the {@code haveNextNextGaussian} flag used by {@link
>      * #nextGaussian}.
>      *
>      * <p>The implementation of {@code setSeed} by class {@code Random}
>      * happens to use only 48 bits of the given seed. In general, however,
>      * an overriding method may use all 64 bits of the {@code long}
>      * argument as a seed value.
>      *
>      * @param seed the initial seed
>      * @throws UnsupportedOperationException if the {@code setSeed}
>      *         operation is not supported by this random number generator
>      */
> ```
> 
> This moves pretty much everything besides the first sentence to `@implSpec`, as they are only applicable to the `Random` class, but not its subclasses. The rest is an emulation of `List.add` javadoc on optional operations.

Please also update the Random.setSeed spec to accommodate the behavior of SecureRandom.setSeed:

"Reseeds this random object, using the eight bytes contained in the given long seed. The given seed supplements, rather than replaces, the existing seed. Thus, repeated calls are guaranteed never to reduce randomness.

This method is defined for compatibility with java.util.Random."

https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/security/SecureRandom.html#setSeed(long)

Thanks.

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

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