RFR: 8248862: Implement Enhanced Pseudo-Random Number Generators [v32]

[Joe Darcy]

On Thu, 18 Mar 2021 15:08:56 GMT, Jim Laskey <jlaskey at openjdk.org> wrote:

>> This PR is to introduce a new random number API for the JDK. The primary API is found in RandomGenerator and RandomGeneratorFactory. Further description can be found in the JEP https://openjdk.java.net/jeps/356 .
>> 
>> javadoc can be found at http://cr.openjdk.java.net/~jlaskey/prng/doc/api/java.base/java/util/random/package-summary.html
>> 
>> old PR:  https://github.com/openjdk/jdk/pull/1273
>
> Jim Laskey has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 67 commits:
> 
>  - Merge branch 'master' into 8248862
>  - Review revisions
>  - Missing @since
>  - Review revisions
>  - Review requested changes
>  - Merge branch 'master' into 8248862
>  - Remove conflicts
>  - Use isAnnotationPresent
>  - Introduce isDeprecated
>  - Update javadoc
>  - ... and 57 more: https://git.openjdk.java.net/jdk/compare/8c8d1b31...63094f9d

Changes requested by darcy (Reviewer).

src/java.base/share/classes/java/util/random/RandomGenerator.java line 1290:

> 1288:          * @return a new object that is a copy of this generator
> 1289:          */
> 1290:         LeapableGenerator copy();

Suggest adding an Override annotation here and possibly to inheritDoc the text from Jumpable.copy.

src/java.base/share/classes/java/util/random/RandomGenerator.java line 1455:

> 1453:          *                                  period of this generator
> 1454:          */
> 1455:         void jump(double distance);

Suggest Override and inheritDoc combo.

src/java.base/share/classes/java/util/random/RandomGenerator.java line 1465:

> 1463:          * @implSpec The default implementation invokes jump(jumpDistance()).
> 1464:          */
> 1465:         default void jump() { jump(jumpDistance()); }

Should be able to avoid defining the jump method in this subinterface.

src/java.base/share/classes/java/util/random/RandomGenerator.java line 1486:

> 1484:          * ({@link Long#MAX_VALUE Long.MAX_VALUE}).
> 1485:          */
> 1486:         default Stream<ArbitrarilyJumpableGenerator> jumps(double distance) {

Suggest adding an Override annotation.

src/java.base/share/classes/java/util/random/RandomGenerator.java line 1521:

> 1519:          * {@link ArbitrarilyJumpableGenerator#leapDistance() leapDistance}().
> 1520:          */
> 1521:         default void leap() { jump(leapDistance()); }

Should need to define this method in the subinterface of Leapable.

src/java.base/share/classes/java/util/random/RandomGenerator.java line 1538:

> 1536:          * returns the copy.
> 1537:          */
> 1538:         default ArbitrarilyJumpableGenerator copyAndJump(double distance) {

Suggest Override and inheritDoc.

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

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