Summary

The methods create(long) and create(byte[]) on java.util.random.RandomGeneratorFactory will now throw java.lang.UnsupportedOperationException if the underlying java.util.RandomGenerator, for the algorithm, does not support instantiation using a long seed or a byte[] seed respectively.

Problem

RandomGeneratorFactory provides APIs to locate all or specific random number generators available in the Java runtime. Once located, the RandomGeneratorFactory provides the following 3 methods to construct instances of java.util.random.RandomGenerator for the corresponding algorithm:

public T create();
public T create(long seed);
public T create(byte[ ] seed);

create() can be used to construct an instance of RandomGenerator without a seed value. The create(long) and create(byte[]) methods allow applications to provide a seed value when constructing the RandomGenerator.

In their current form, the create(long) and create(byte[]) methods are specified to construct a RandomGenerator instance with the specified seed and if the RandomGenerator for that algorithm doesn't support a seed of that type, then these 2 create(...) methods will fallback to constructing the RandomGenerator instance without any seed value. This is problematic because the returned RandomGenerator instance from these 2 create(...) methods can end up being an unseeded RandomGenerator, when the application actually wanted the instances to be seeded with a specific seed. Morever, the calling application will not have any indication whether or not a seed value was successfully used to construct the RandomGenerator instance returned from these 2 create(...) methods.

Solution

The specification of create(long) and create(byte[]) will be changed to specify that if the RandomGenerator corresponding to a random generator algorithm doesn't support constructing the RandomGenerator instance with the provided seed type, then these 2 methods will throw an UnsupportedOperationException. These 2 methods will no longer fallback to constructing unseeded instances of RandomGenerator.

Moreover, a line for the algorithm SecureRandom, which is missing from the table in the java.util.random package documentation, has been added there.

Specification

src/java.base/share/classes/java/util/random/RandomGeneratorFactory.java

     /**
-     * Create an instance of {@link RandomGenerator} based on
+     * Create an instance of {@link RandomGenerator} based on the
      * <a href="package-summary.html#algorithms">algorithm</a> chosen.
      *
-     * @return new in instance of {@link RandomGenerator}.
-     *
+     * @return new instance of {@link RandomGenerator}.
      */
     public T create() {

     /**
-     * Create an instance of {@link RandomGenerator} based on
-     * <a href="package-summary.html#algorithms">algorithm</a> chosen
-     * providing a starting long seed. If long seed is not supported by an
-     * algorithm then the no argument form of create is used.
+     * Create an instance of {@link RandomGenerator} based on the
+     * <a href="package-summary.html#algorithms">algorithm</a> chosen,
+     * and the provided {@code seed}.
+     * If the {@link RandomGenerator} doesn't support instantiation through
+     * a {@code seed} of type {@code long} then this method throws
+     * an {@link UnsupportedOperationException}.
      *
      * @param seed long random seed value.
      *
-     * @return new in instance of {@link RandomGenerator}.
+     * @return new instance of {@link RandomGenerator}.
+     *
+     * @throws UnsupportedOperationException
+     *      if a {@code seed} of type {@code long} in not supported.
      */
     public T create(long seed) {

     /**
-     * Create an instance of {@link RandomGenerator} based on
-     * <a href="package-summary.html#algorithms">algorithm</a> chosen
-     * providing a starting byte[] seed. If byte[] seed is not supported by an
-     * <a href="package-summary.html#algorithms">algorithm</a> then the no
-     * argument form of create is used.
+     * Create an instance of {@link RandomGenerator} based on the
+     * <a href="package-summary.html#algorithms">algorithm</a> chosen,
+     * and the provided {@code seed}.
+     * If the {@link RandomGenerator} doesn't support instantiation through
+     * a {@code seed} of type {@code byte[ ]} then this method throws
+     * an {@link UnsupportedOperationException}.
      *
      * @param seed byte array random seed value.
      *
-     * @return new in instance of {@link RandomGenerator}.
+     * @return new instance of {@link RandomGenerator}.
+     *
+     * @throws UnsupportedOperationException
+     *      if a {@code seed} of type {@code byte[ ]} in not supported.
      *
      * @throws NullPointerException if seed is null.
      */
     public T create(byte[] seed) {

src/java.base/share/classes/java/util/random/package-info.java

  *      <td style="text-align:right">1</td>
  *  </tr>
  *  <tr>
+ *      <th scope="row" style="text-align:left">SecureRandom</th>
+ *      <td style="text-align:left">Legacy</td>
+ *      <td style="text-align:left">BigInteger.ZERO</td>
+ *      <td style="text-align:right">Integer.MAX_VALUE</td>
+ *      <td style="text-align:right">Integer.MAX_VALUE</td>
+ *  </tr>
+ *  <tr>
  *      <th scope="row" style="text-align:left">ThreadLocalRandom <sup>*</sup></th>
  *      <td style="text-align:left">Legacy</td>
  *      <td style="text-align:left">BigInteger.ONE.shiftLeft(64)</td>