diff -r 6a4be8bf8990 -r 7cb325557832 src/java.base/share/classes/java/util/random/RandomGenerator.java --- a/src/java.base/share/classes/java/util/random/RandomGenerator.java Wed Aug 07 15:35:55 2019 -0300 +++ b/src/java.base/share/classes/java/util/random/RandomGenerator.java Thu Aug 08 11:06:54 2019 -0300 @@ -33,9 +33,9 @@ import java.util.stream.Stream; /** - * The {@link RandomGenerator} interface is designed to provide a common protocol for objects - * that generate random or (more typically) pseudorandom sequences of numbers (or Boolean values). - * Such a sequence may be obtained by either repeatedly invoking a method that returns a single + * The {@link RandomGenerator} interface is designed to provide a common protocol for objects that + * generate random or (more typically) pseudorandom sequences of numbers (or Boolean values). Such a + * sequence may be obtained by either repeatedly invoking a method that returns a single * (pseudo)randomly chosen value, or by invoking a method that returns a stream of (pseudo)randomly * chosen values. *

@@ -53,37 +53,38 @@ *

* Each method that returns a stream produces a stream of values each of which is chosen in the same * manner as for a method that returns a single (pseudo)randomly chosen value. For example, if - * {@code r} implements {@link RandomGenerator}, then the method call {@code r.ints(100)} - * returns a stream of 100 {@code int} values. These are not necessarily the exact same values that - * would have been returned if instead {@code r.nextInt()} had been called 100 times; all that is + * {@code r} implements {@link RandomGenerator}, then the method call {@code r.ints(100)} returns a + * stream of 100 {@code int} values. These are not necessarily the exact same values that would + * have been returned if instead {@code r.nextInt()} had been called 100 times; all that is * guaranteed is that each value in the stream is chosen in a similar (pseudo)random manner from the * same range. *

- * Every object that implements the {@link RandomGenerator} interface is assumed to contain a - * finite amount of state. Using such an object to generate a pseudorandomly chosen value alters - * its state. The number of distinct possible states of such an object is called its + * Every object that implements the {@link RandomGenerator} interface is assumed to contain a finite + * amount of state. Using such an object to generate a pseudorandomly chosen value alters its + * state. The number of distinct possible states of such an object is called its * period. (Some implementations of the {@link RandomGenerator} interface * may be truly random rather than pseudorandom, for example relying on the statistical behavior of * a physical object to derive chosen values. Such implementations do not have a fixed period.) *

- * As a rule, objects that implement the {@link RandomGenerator} interface need not be - * thread-safe. It is recommended that multithreaded applications use either {@link - * ThreadLocalRandom} or (preferably) pseudorandom number generators that implement the {@link - * SplittableGenerator} or {@link JumpableGenerator} interface. + * As a rule, objects that implement the {@link RandomGenerator} interface need not be thread-safe. + * It is recommended that multithreaded applications use either {@link ThreadLocalRandom} or + * (preferably) pseudorandom number generators that implement the {@link SplittableGenerator} or + * {@link JumpableGenerator} interface. *

* To implement this interface, a class only needs to provide concrete definitions for the methods * {@code nextLong()} and {@code period()}. Default implementations are provided for all other * methods (but it may be desirable to override some of them, especially {@code nextInt()} if the * underlying algorithm is {@code int}-based). Moerover, it may be preferable instead to implement - * another interface such as {@link JumpableGenerator} or {@link LeapableGenerator}, or to extend an abstract - * class such as {@link AbstractSplittableGenerator} or {@link AbstractArbitrarilyJumpableGenerator}. + * another interface such as {@link JumpableGenerator} or {@link LeapableGenerator}, or to extend an + * abstract class such as {@link AbstractSplittableGenerator} or {@link + * AbstractArbitrarilyJumpableGenerator}. *

* Objects that implement {@link RandomGenerator} are typically not cryptographically secure. * Consider instead using {@link java.security.SecureRandom} to get a cryptographically secure * pseudorandom number generator for use by security-sensitive applications. Note, however, that - * {@code java.security.SecureRandom} does implement the {@link RandomGenerator} interface, so - * that instances of {@code java.security.SecureRandom} may be used interchangeably with other types - * of pseudorandom generators in applications that do not require a secure generator. + * {@code java.security.SecureRandom} does implement the {@link RandomGenerator} interface, so that + * instances of {@code java.security.SecureRandom} may be used interchangeably with other types of + * pseudorandom generators in applications that do not require a secure generator. * * @since 14 */ @@ -144,13 +145,32 @@ private String name; - Algorithm(String name) { + private Algorithm(String name) { this.name = name; } public String toString() { return name; } + + /** + * Returns an instance of {@link RandomGenerator} that utilizes this algorithm. + * + * @return An instance of {@link RandomGenerator} + */ + public RandomGenerator instance() { + return RandomGeneratorFactory.of(name, RandomGenerator.class); + } + + /** + * Returns a {@link RandomGeneratorFactory} that can produce instances + * of {@link RandomGenerator} that utilizes this algorithm. + * + * @return {@link RandomGeneratorFactory} of {@link RandomGenerator} + */ + public RandomGeneratorFactory factory() { + return RandomGeneratorFactory.factoryOf(name, RandomGenerator.class); + } } /** @@ -185,7 +205,7 @@ * * @param name Name of random number generator algorithm * - * @return Factory of {@link RandomGenerator} + * @return {@link RandomGeneratorFactory} of {@link RandomGenerator} */ public static RandomGeneratorFactory factoryOf(String name) { Objects.requireNonNull(name); @@ -198,7 +218,7 @@ * * @param algorithm Random number generator algorithm * - * @return Factory of {@link RandomGenerator} + * @return {@link RandomGeneratorFactory} of {@link RandomGenerator} */ public static RandomGeneratorFactory factoryOf(Algorithm algorithm) { Objects.requireNonNull(algorithm); @@ -821,7 +841,7 @@ * * @param name Name of random number generator algorithm * - * @return Factory of {@link StreamableGenerator} + * @return {@link RandomGeneratorFactory} of {@link StreamableGenerator} */ public static RandomGeneratorFactory factoryOf(String name) { Objects.requireNonNull(name); @@ -834,7 +854,7 @@ * * @param algorithm Random number generator algorithm * - * @return Factory of {@link StreamableGenerator} + * @return {@link RandomGeneratorFactory} of {@link StreamableGenerator} */ public static RandomGeneratorFactory factoryOf(Algorithm algorithm) { Objects.requireNonNull(algorithm); @@ -948,7 +968,7 @@ * * @param name Name of random number generator algorithm * - * @return Factory of {@link SplittableGenerator} + * @return {@link RandomGeneratorFactory} of {@link SplittableGenerator} */ public static RandomGeneratorFactory factoryOf(String name) { Objects.requireNonNull(name); @@ -961,7 +981,7 @@ * * @param algorithm Random number generator algorithm * - * @return Factory of {@link SplittableGenerator} + * @return {@link RandomGeneratorFactory} of {@link SplittableGenerator} */ public static RandomGeneratorFactory factoryOf(Algorithm algorithm) { Objects.requireNonNull(algorithm); @@ -1097,36 +1117,38 @@ } /** - * This interface is designed to provide a common protocol for objects that generate pseudorandom - * sequences of numbers (or Boolean values) and furthermore can easily jump forward (by a - * fixed amount) to a distant point in the state cycle. + * This interface is designed to provide a common protocol for objects that generate + * pseudorandom sequences of numbers (or Boolean values) and furthermore can easily jump + * forward (by a fixed amount) to a distant point in the state cycle. *

- * Ideally, all {@link JumpableGenerator} objects produced by iterative jumping from a single original - * {@link JumpableGenerator} object are statistically independent of one another and individually uniform. - * In practice, one must settle for some approximation to independence and uniformity. In - * particular, a specific implementation may assume that each generator in a stream produced by the - * {@code jumps} method is used to produce a number of values no larger than either 264 - * or the square root of its period. Implementors are advised to use algorithms whose period is at - * least 2127. + * Ideally, all {@link JumpableGenerator} objects produced by iterative jumping from a single + * original {@link JumpableGenerator} object are statistically independent of one another and + * individually uniform. In practice, one must settle for some approximation to independence and + * uniformity. In particular, a specific implementation may assume that each generator in a + * stream produced by the {@code jumps} method is used to produce a number of values no larger + * than either 264 or the square root of its period. Implementors are advised to use + * algorithms whose period is at least 2127. *

* Methods are provided to perform a single jump operation and also to produce a stream of * generators produced from the original by iterative copying and jumping of internal state. A - * typical strategy for a multithreaded application is to create a single {@link JumpableGenerator} - * object, calls its {@code jumps} method exactly once, and then parcel out generators from the - * resulting stream, one to each thread. It is generally not a good idea to call {@code jump} on a - * generator that was itself produced by the {@code jumps} method, because the result may be a - * generator identical to another generator already produce by that call to the {@code jumps} - * method. For this reason, the return type of the {@code jumps} method is {@code - * Stream} rather than {@code Stream}, even though the actual - * generator objects in that stream likely do also implement the {@link JumpableGenerator} interface. + * typical strategy for a multithreaded application is to create a single {@link + * JumpableGenerator} object, calls its {@code jumps} method exactly once, and then parcel out + * generators from the resulting stream, one to each thread. It is generally not a good idea to + * call {@code jump} on a generator that was itself produced by the {@code jumps} method, + * because the result may be a generator identical to another generator already produce by that + * call to the {@code jumps} method. For this reason, the return type of the {@code jumps} + * method is {@code Stream} rather than {@code Stream}, even + * though the actual generator objects in that stream likely do also implement the {@link + * JumpableGenerator} interface. *

- * An implementation of the {@link JumpableGenerator} interface must provide concrete definitions for the - * methods {@code nextInt()}, {@code nextLong}, {@code period()}, {@code copy()}, {@code jump()}, - * and {@code defaultJumpDistance()}. Default implementations are provided for all other methods. + * An implementation of the {@link JumpableGenerator} interface must provide concrete + * definitions for the methods {@code nextInt()}, {@code nextLong}, {@code period()}, {@code + * copy()}, {@code jump()}, and {@code defaultJumpDistance()}. Default implementations are + * provided for all other methods. *

- * Objects that implement {@link JumpableGenerator} are typically not cryptographically secure. Consider - * instead using {@link java.security.SecureRandom} to get a cryptographically secure pseudo-random - * number generator for use by security-sensitive applications. + * Objects that implement {@link JumpableGenerator} are typically not cryptographically secure. + * Consider instead using {@link java.security.SecureRandom} to get a cryptographically secure + * pseudo-random number generator for use by security-sensitive applications. * * @since 14 */ @@ -1164,7 +1186,7 @@ * * @param name Name of random number generator algorithm * - * @return Factory of {@link JumpableGenerator} + * @return {@link RandomGeneratorFactory} of {@link JumpableGenerator} */ public static RandomGeneratorFactory factoryOf(String name) { Objects.requireNonNull(name); @@ -1177,7 +1199,7 @@ * * @param algorithm Random number generator algorithm * - * @return Factory of {@link JumpableGenerator} + * @return {@link RandomGeneratorFactory} of {@link JumpableGenerator} */ public static RandomGeneratorFactory factoryOf(Algorithm algorithm) { Objects.requireNonNull(algorithm); @@ -1282,40 +1304,43 @@ } /** - * This interface is designed to provide a common protocol for objects that generate sequences of - * pseudorandom numbers (or Boolean values) and furthermore can easily not only jump but also + * This interface is designed to provide a common protocol for objects that generate sequences + * of pseudorandom numbers (or Boolean values) and furthermore can easily not only jump but + * also * leap to a very distant point in the state cycle. *

- * Typically one will construct a series of {@link LeapableGenerator} objects by iterative leaping from a - * single original {@link LeapableGenerator} object, and then for each such object produce a subseries of - * objects by iterative jumping. There is little conceptual difference between leaping and jumping, - * but typically a leap will be a very long jump in the state cycle (perhaps distance - * 2128 or so). + * Typically one will construct a series of {@link LeapableGenerator} objects by iterative + * leaping from a single original {@link LeapableGenerator} object, and then for each such + * object produce a subseries of objects by iterative jumping. There is little conceptual + * difference between leaping and jumping, but typically a leap will be a very long jump in the + * state cycle (perhaps distance 2128 or so). *

- * Ideally, all {@link LeapableGenerator} objects produced by iterative leaping and jumping from a single - * original {@link LeapableGenerator} object are statistically independent of one another and individually - * uniform. In practice, one must settle for some approximation to independence and uniformity. In - * particular, a specific implementation may assume that each generator in a stream produced by the - * {@code leaps} method is used to produce (by jumping) a number of objects no larger than - * 264. Implementors are advised to use algorithms whose period is at least - * 2191. + * Ideally, all {@link LeapableGenerator} objects produced by iterative leaping and jumping from + * a single original {@link LeapableGenerator} object are statistically independent of one + * another and individually uniform. In practice, one must settle for some approximation to + * independence and uniformity. In particular, a specific implementation may assume that each + * generator in a stream produced by the {@code leaps} method is used to produce (by jumping) a + * number of objects no larger than 264. Implementors are advised to use algorithms + * whose period is at least 2191. *

* Methods are provided to perform a single leap operation and also to produce a stream of - * generators produced from the original by iterative copying and leaping of internal state. The - * generators produced must implement the {@link JumpableGenerator} interface but need not also implement - * the {@link LeapableGenerator} interface. A typical strategy for a multithreaded application is to - * create a single {@link LeapableGenerator} object, calls its {@code leaps} method exactly once, and then - * parcel out generators from the resulting stream, one to each thread. Then the {@code jumps} - * method of each such generator be called to produce a substream of generator objects. + * generators produced from the original by iterative copying and leaping of internal state. + * The generators produced must implement the {@link JumpableGenerator} interface but need not + * also implement the {@link LeapableGenerator} interface. A typical strategy for a + * multithreaded application is to create a single {@link LeapableGenerator} object, calls its + * {@code leaps} method exactly once, and then parcel out generators from the resulting stream, + * one to each thread. Then the {@code jumps} method of each such generator be called to + * produce a substream of generator objects. *

- * An implementation of the {@link LeapableGenerator} interface must provide concrete definitions for the - * methods {@code nextInt()}, {@code nextLong}, {@code period()}, {@code copy()}, {@code jump()}, - * {@code defaultJumpDistance()}, {@code leap()}, and {@code defaultLeapDistance()}. Default - * implementations are provided for all other methods. + * An implementation of the {@link LeapableGenerator} interface must provide concrete + * definitions for the methods {@code nextInt()}, {@code nextLong}, {@code period()}, + * {@code copy()}, {@code jump()}, {@code defaultJumpDistance()}, {@code leap()}, + * and {@code defaultLeapDistance()}. Default implementations are provided for all other + * methods. *

- * Objects that implement {@link LeapableGenerator} are typically not cryptographically secure. Consider - * instead using {@link java.security.SecureRandom} to get a cryptographically secure pseudo-random - * number generator for use by security-sensitive applications. + * Objects that implement {@link LeapableGenerator} are typically not cryptographically secure. + * Consider instead using {@link java.security.SecureRandom} to get a cryptographically secure + * pseudo-random number generator for use by security-sensitive applications. * * @since 14 */ @@ -1353,7 +1378,7 @@ * * @param name Name of random number generator algorithm * - * @return Factory of {@link LeapableGenerator} + * @return {@link RandomGeneratorFactory} of {@link LeapableGenerator} */ public static RandomGeneratorFactory factoryOf(String name) { Objects.requireNonNull(name); @@ -1366,7 +1391,7 @@ * * @param algorithm Random number generator algorithm * - * @return Factory of {@link LeapableGenerator} + * @return {@link RandomGeneratorFactory} of {@link LeapableGenerator} */ public static RandomGeneratorFactory factoryOf(Algorithm algorithm) { Objects.requireNonNull(algorithm); @@ -1442,42 +1467,45 @@ } /** - * This interface is designed to provide a common protocol for objects that generate sequences of - * pseudorandom numbers (or Boolean values) and furthermore can easily jump to an arbitrarily - * specified distant point in the state cycle. + * This interface is designed to provide a common protocol for objects that generate sequences + * of pseudorandom numbers (or Boolean values) and furthermore can easily jump to an + * arbitrarily specified distant point in the state cycle. *

- * Ideally, all {@link ArbitrarilyJumpableGenerator} objects produced by iterative jumping from a single - * original {@link ArbitrarilyJumpableGenerator} object are statistically independent of one another and - * individually uniform, provided that they do not traverse overlapping portions of the state cycle. - * In practice, one must settle for some approximation to independence and uniformity. In - * particular, a specific implementation may assume that each generator in a stream produced by the - * {@code jumps} method is used to produce a number of values no larger than the jump distance - * specified. Implementors are advised to use algorithms whose period is at least 2127. + * Ideally, all {@link ArbitrarilyJumpableGenerator} objects produced by iterative jumping from + * a single original {@link ArbitrarilyJumpableGenerator} object are statistically independent + * of one another and individually uniform, provided that they do not traverse overlapping + * portions of the state cycle. In practice, one must settle for some approximation to + * independence and uniformity. In particular, a specific implementation may assume that each + * generator in a stream produced by the {@code jumps} method is used to produce a number of + * values no larger than the jump distance specified. Implementors are advised to use + * algorithms whose period is at least 2127. *

- * For many applications, it suffices to jump forward by a power of two or some small multiple of a - * power of two, but this power of two may not be representable as a {@code long} value. To avoid - * the use of {@link java.math.BigInteger} values as jump distances, {@code double} values are used - * instead. + * For many applications, it suffices to jump forward by a power of two or some small multiple + * of a power of two, but this power of two may not be representable as a {@code long} value. + * To avoid the use of {@link java.math.BigInteger} values as jump distances, {@code double} + * values are used instead. *

* Methods are provided to perform a single jump operation and also to produce a stream of * generators produced from the original by iterative copying and jumping of internal state. A - * typical strategy for a multithreaded application is to create a single {@link - * ArbitrarilyJumpableGenerator} object, call its {@code jumps} method exactly once, and then parcel out - * generators from the resulting stream, one to each thread. However, each generator produced also - * has type {@link ArbitrarilyJumpableGenerator}; with care, different jump distances can be used to - * traverse the entire state cycle in various ways. + * typical strategy for a multithreaded application is to create a single + * {@link ArbitrarilyJumpableGenerator} object, call its {@code jumps} method exactly once, and + * then parcel out generators from the resulting stream, one to each thread. However, each + * generator produced also has type {@link ArbitrarilyJumpableGenerator}; with care, different + * jump distances can be used to traverse the entire state cycle in various ways. *

* An implementation of the {@link ArbitrarilyJumpableGenerator} interface must provide concrete - * definitions for the methods {@code nextInt()}, {@code nextLong}, {@code period()}, {@code - * copy()}, {@code jump(double)}, {@code defaultJumpDistance()}, and {@code defaultLeapDistance()}. - * Default implementations are provided for all other methods. Perhaps the most convenient way to - * implement this interface is to extend the abstract class {@link ArbitrarilyJumpableGenerator}, which - * provides spliterator-based implementations of the methods {@code ints}, {@code longs}, {@code - * doubles}, {@code rngs}, {@code jumps}, and {@code leaps}. + * definitions for the methods {@code nextInt()}, {@code nextLong}, {@code period()}, + * {@code copy()}, {@code jump(double)}, {@code defaultJumpDistance()}, and + * {@code defaultLeapDistance()}. Default implementations are provided for all other methods. + * Perhaps the most convenient way to implement this interface is to extend the abstract class + * {@link ArbitrarilyJumpableGenerator}, which provides spliterator-based implementations of the + * methods {@code ints}, {@code longs}, {@code doubles}, {@code rngs}, {@code jumps}, and + * {@code leaps}. *

- * Objects that implement {@link ArbitrarilyJumpableGenerator} are typically not cryptographically secure. - * Consider instead using {@link java.security.SecureRandom} to get a cryptographically secure - * pseudo-random number generator for use by security-sensitive applications. + * Objects that implement {@link ArbitrarilyJumpableGenerator} are typically not + * cryptographically secure. Consider instead using {@link java.security.SecureRandom} to get a + * cryptographically secure pseudo-random number generator for use by security-sensitive + * applications. * * @since 14 */ @@ -1515,7 +1543,7 @@ * * @param name Name of random number generator algorithm * - * @return Factory of {@link ArbitrarilyJumpableGenerator} + * @return {@link RandomGeneratorFactory} of {@link ArbitrarilyJumpableGenerator} */ public static RandomGeneratorFactory factoryOf(String name) { Objects.requireNonNull(name); @@ -1528,7 +1556,7 @@ * * @param algorithm Random number generator algorithm * - * @return Factory of {@link ArbitrarilyJumpableGenerator} + * @return {@link RandomGeneratorFactory} of {@link ArbitrarilyJumpableGenerator} */ public static RandomGeneratorFactory factoryOf(Algorithm algorithm) { Objects.requireNonNull(algorithm); @@ -1575,9 +1603,9 @@ default void jump() { jump(defaultJumpDistance()); } /** - * Returns an effectively unlimited stream of new pseudorandom number generators, each of which - * implements the {@link ArbitrarilyJumpableGenerator} interface, produced by jumping copies of this - * generator by different integer multiples of the specified jump distance. + * Returns an effectively unlimited stream of new pseudorandom number generators, each of + * which implements the {@link ArbitrarilyJumpableGenerator} interface, produced by jumping + * copies of this generator by different integer multiples of the specified jump distance. * * @param distance a distance to jump forward within the state cycle * @@ -1591,9 +1619,9 @@ /** * Returns a stream producing the given {@code streamSize} number of new pseudorandom number - * generators, each of which implements the {@link ArbitrarilyJumpableGenerator} interface, produced - * by jumping copies of this generator by different integer multiples of the specified jump - * distance. + * generators, each of which implements the {@link ArbitrarilyJumpableGenerator} interface, + * produced by jumping copies of this generator by different integer multiples of the + * specified jump distance. * * @param streamSize the number of generators to generate * @param distance a distance to jump forward within the state cycle @@ -1608,8 +1636,8 @@ /** * Alter the state of this pseudorandom number generator so as to jump forward a very large, - * fixed distance (typically 2128 or more) within its state cycle. The distance used - * is that returned by method {@code defaultJLeapDistance()}. + * fixed distance (typically 2128 or more) within its state cycle. The distance + * used is that returned by method {@code defaultJLeapDistance()}. */ default void leap() { jump(defaultLeapDistance()); }