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
- * 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
- * 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
- * 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
- * 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