src/java.base/share/classes/java/util/random/RandomGeneratorFactory.java - platform/libcore - Git at Google

 /*
  * Copyright (c) 2021, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
  * under the terms of the GNU General Public License version 2 only, as
  * published by the Free Software Foundation.  Oracle designates this
  * particular file as subject to the "Classpath" exception as provided
  * by Oracle in the LICENSE file that accompanied this code.
  *
  * This code is distributed in the hope that it will be useful, but WITHOUT
  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  * version 2 for more details (a copy is included in the LICENSE file that
  * accompanied this code).
  *
  * You should have received a copy of the GNU General Public License version
  * 2 along with this work; if not, write to the Free Software Foundation,
  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  *
  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  * or visit www.oracle.com if you need additional information or have any
  * questions.
  */

 package java.util.random;

 import java.lang.reflect.Constructor;
 import java.math.BigInteger;
 import java.security.AccessController;
 import java.security.PrivilegedActionException;
 import java.security.PrivilegedExceptionAction;
 import java.util.Objects;
 import java.util.function.Function;
 import java.util.Map;
 import java.util.random.RandomGenerator.ArbitrarilyJumpableGenerator;
 import java.util.random.RandomGenerator.JumpableGenerator;
 import java.util.random.RandomGenerator.LeapableGenerator;
 import java.util.random.RandomGenerator.SplittableGenerator;
 import java.util.random.RandomGenerator.StreamableGenerator;
 import java.util.ServiceLoader;
 import java.util.ServiceLoader.Provider;
 import java.util.stream.Collectors;
 import java.util.stream.Stream;
 import jdk.internal.util.random.RandomSupport.RandomGeneratorProperties;

 /**
  * This is a factory class for generating multiple random number generators
  * of a specific <a href="package-summary.html#algorithms">algorithm</a>.
  * {@link RandomGeneratorFactory} also provides
  * methods for selecting random number generator algorithms.
  *
  * A specific {@link RandomGeneratorFactory} can be located by using the
  * {@link RandomGeneratorFactory#of(String)} method, where the argument string
  * is the name of the <a href="package-summary.html#algorithms">algorithm</a>
  * required. The method
  * {@link RandomGeneratorFactory#all()} produces a non-empty {@link Stream} of all available
  * {@link RandomGeneratorFactory RandomGeneratorFactorys} that can be searched
  * to locate a {@link RandomGeneratorFactory} suitable to the task.
  *
  * There are three methods for constructing a RandomGenerator instance,
  * depending on the type of initial seed required.
  * {@link RandomGeneratorFactory#create(long)} is used for long
  * seed construction,
  * {@link RandomGeneratorFactory#create(byte[])} is used for byte[]
  * seed construction, and
  * {@link RandomGeneratorFactory#create()} is used for random seed
  * construction. Example;
  *
  * <pre>{@code
  *    RandomGeneratorFactory<RandomGenerator> factory = RandomGeneratorFactory.of("Random");
  *
  *     for (int i = 0; i < 10; i++) {
  *         new Thread(() -> {
  *             RandomGenerator random = factory.create(100L);
  *             System.out.println(random.nextDouble());
  *         }).start();
  *     }
  * }</pre>
  *
  * RandomGeneratorFactory also provides methods describing the attributes (or properties)
  * of a generator and can be used to select random number generator
  * <a href="package-summary.html#algorithms">algorithms</a>.
  * These methods are typically used in
  * conjunction with {@link RandomGeneratorFactory#all()}. In this example, the code
  * locates the {@link RandomGeneratorFactory} that produces
  * {@link RandomGenerator RandomGenerators}
  * with the highest number of state bits.
  *
  * <pre>{@code
  *     RandomGeneratorFactory<RandomGenerator> best = RandomGeneratorFactory.all()
  *         .sorted(Comparator.comparingInt(RandomGenerator::stateBits).reversed())
  *         .findFirst()
  *         .orElse(RandomGeneratorFactory.of("Random"));
  *     System.out.println(best.name() + " in " + best.group() + " was selected");
  *
  *     RandomGenerator rng = best.create();
  *     System.out.println(rng.nextLong());
  * }</pre>
  *
  * @since 17
  *
  * @see java.util.random
  *
  */
 public final class RandomGeneratorFactory<T extends RandomGenerator> {
     /**
      * Instance provider class of random number algorithm.
      */
     private final Provider<? extends RandomGenerator> provider;

     /**
      * Provider RandomGeneratorProperties annotation.
      */
     private volatile RandomGeneratorProperties properties;

     /**
      * Default provider constructor.
      */
     private volatile Constructor<T> ctor;

     /**
      * Provider constructor with long seed.
      */
     private Constructor<T> ctorLong;

     /**
      * Provider constructor with byte[] seed.
      */
     private Constructor<T> ctorBytes;


     private static class FactoryMapHolder {
         static final Map<String, Provider<? extends RandomGenerator>> FACTORY_MAP = createFactoryMap();

         /**
          * Returns the factory map, lazily constructing map on first use.
          *
          * @return Map of RandomGeneratorFactory classes.
          */
         private static Map<String, Provider<? extends RandomGenerator>> createFactoryMap() {
             return ServiceLoader
                 .load(RandomGenerator.class)
                 .stream()
                 .filter(p -> !p.type().isInterface())
                 .collect(Collectors.toMap(p -> p.type().getSimpleName(), Function.identity()));
         }
     }

     /**
      * Private constructor.
      *
      * @param provider  Provider class to wrap.
      */
     private RandomGeneratorFactory(Provider<? extends RandomGenerator> provider) {
         this.provider = provider;
     }

     /**
      * Returns the factory map, lazily constructing map on first call.
      *
      * @return Map of RandomGeneratorFactory classes.
      */
     private static Map<String, Provider<? extends RandomGenerator>> getFactoryMap() {
         return FactoryMapHolder.FACTORY_MAP;
     }

     /**
      * Return the annotation for the specified provider.
      *
      * @return RandomGeneratorProperties annotation for the specified provider.
      */
      private RandomGeneratorProperties getProperties() {
         if (properties == null) {
             synchronized (provider) {
                 if (properties == null) {
                     properties = provider.type().getDeclaredAnnotation(RandomGeneratorProperties.class);
                     Objects.requireNonNull(properties, provider.type() + " missing annotation");
                 }
             }
         }

         return properties;
     }

     /**
      * Return true if the provider is a subclass of the category.
      *
      * @param category Interface category, sub-interface of {@link RandomGenerator}.
      *
      * @return true if the provider is a subclass of the category.
      */
     private boolean isSubclass(Class<? extends RandomGenerator> category) {
         return isSubclass(category, provider);
     }

     /**
      * Return true if the provider is a subclass of the category.
      *
      * @param category Interface category, sub-interface of {@link RandomGenerator}.
      * @param provider Provider that is being filtered.
      *
      * @return true if the provider is a subclass of the category.
      */
     private static boolean isSubclass(Class<? extends RandomGenerator> category,
                                       Provider<? extends RandomGenerator> provider) {
         return provider != null && category.isAssignableFrom(provider.type());
     }

     /**
      * Returns the provider matching name and category.
      *
      * @param name      Name of RandomGenerator
      * @param category  Interface category, sub-interface of {@link RandomGenerator}.
      *
      * @return A provider matching name and category.
      *
      * @throws IllegalArgumentException if provider is not a subclass of category.
      */
     private static Provider<? extends RandomGenerator> findProvider(String name,
                                                                     Class<? extends RandomGenerator> category)
             throws IllegalArgumentException {
         Map<String, Provider<? extends RandomGenerator>> fm = getFactoryMap();
         Provider<? extends RandomGenerator> provider = fm.get(name);
         if (provider == null) {
             throw new IllegalArgumentException("No implementation of the random number generator algorithm \"" +
                                                 name +
                                                 "\" is available");
         } else if (!isSubclass(category, provider)) {
             throw new IllegalArgumentException("The random number generator algorithm \"" +
                                                 name +
                                                 "\" is not implemented with the interface \"" +
                                                 category.getSimpleName() +
                                                 "\"");
         }
         return provider;
     }

     /**
      * Returns a {@link RandomGenerator} that utilizes the {@code name}
      * <a href="package-summary.html#algorithms">algorithm</a>.
      *
      * @param name      Name of random number algorithm to use
      * @param category  Sub-interface of {@link RandomGenerator} to type check
      * @param <T>       Sub-interface of {@link RandomGenerator} to produce
      *
      * @return An instance of {@link RandomGenerator}
      *
      * @throws IllegalArgumentException when either the name or category is null
      */
     static <T extends RandomGenerator> T of(String name, Class<T> category)
             throws IllegalArgumentException {
         @SuppressWarnings("unchecked")
         T uncheckedRandomGenerator = (T)findProvider(name, category).get();
         return uncheckedRandomGenerator;
     }

     /**
      * Returns a {@link RandomGeneratorFactory} that will produce instances
      * of {@link RandomGenerator} that utilizes the named algorithm.
      *
      * @param name  Name of random number algorithm to use
      * @param category Sub-interface of {@link RandomGenerator} to type check
      * @param <T> Sub-interface of {@link RandomGenerator} to produce
      *
      * @return Factory of {@link RandomGenerator}
      *
      * @throws IllegalArgumentException when either the name or category is null
      */
     static <T extends RandomGenerator> RandomGeneratorFactory<T> factoryOf(String name, Class<T> category)
             throws IllegalArgumentException {
         Provider<? extends RandomGenerator> uncheckedProvider = findProvider(name, category);
         return new RandomGeneratorFactory<>(uncheckedProvider);
     }

     /**
      * Fetch the required constructors for class of random number algorithm.
      *
      * @param randomGeneratorClass class of random number algorithm (provider)
      */
     private void getConstructors(Class<? extends RandomGenerator> randomGeneratorClass) {
         if (ctor == null) {
             synchronized (provider) {
                 if (ctor == null) {
                     PrivilegedExceptionAction<Constructor<?>[]> ctorAction = randomGeneratorClass::getConstructors;
                     try {
                         @SuppressWarnings("removal")
                         Constructor<?>[] ctors = AccessController.doPrivileged(ctorAction);

                         Constructor<T> tmpCtor = null;
                         Constructor<T> tmpCtorLong = null;
                         Constructor<T> tmpCtorBytes = null;


                         for (Constructor<?> ctorGeneric : ctors) {
                             @SuppressWarnings("unchecked")
                             Constructor<T> ctorSpecific = (Constructor<T>) ctorGeneric;
                             final Class<?>[] parameterTypes = ctorSpecific.getParameterTypes();

                             if (parameterTypes.length == 0) {
                                 tmpCtor = ctorSpecific;
                             } else if (parameterTypes.length == 1) {
                                 Class<?> argType = parameterTypes[0];

                                 if (argType == long.class) {
                                     tmpCtorLong = ctorSpecific;
                                 } else if (argType == byte[].class) {
                                     tmpCtorBytes = ctorSpecific;
                                 }
                             }
                         }

                         if (tmpCtor == null) {
                             throw new IllegalStateException("Random algorithm " + name() + " is missing a default constructor");
                         }

                         // Store specialized constructors first, guarded by ctor
                         ctorBytes = tmpCtorBytes;
                         ctorLong = tmpCtorLong;
                         ctor = tmpCtor;
                     } catch (PrivilegedActionException ex) {
                         // Do nothing
                     }
                 }
             }
         }
     }

     /**
      * Ensure all the required constructors are fetched.
      */
     private void ensureConstructors() {
         getConstructors(provider.type());
     }

     /**
      * Returns a {@link RandomGeneratorFactory} that can produce instances of
      * {@link RandomGenerator} that utilize the {@code name}
      * <a href="package-summary.html#algorithms">algorithm</a>.
      *
      * @implSpec Availability is determined by RandomGeneratorFactory using the
      * service provider API to locate implementations of the RandomGenerator interface.
      *
      * @param name  Name of random number generator
      * <a href="package-summary.html#algorithms">algorithm</a>
      * @param <T> Sub-interface of {@link RandomGenerator} to produce
      *
      * @return {@link RandomGeneratorFactory} of {@link RandomGenerator}
      *
      * @throws NullPointerException if name is null
      * @throws IllegalArgumentException if the named algorithm is not found
      */
     public static <T extends RandomGenerator> RandomGeneratorFactory<T> of(String name) {
         Objects.requireNonNull(name);
         @SuppressWarnings("unchecked")
         RandomGeneratorFactory<T> factory =
                 (RandomGeneratorFactory<T>)factoryOf(name, RandomGenerator.class);
         return factory;
     }

     /**
      * Returns a {@link RandomGeneratorFactory} meeting the minimal requirement
      * of having an algorithm whose state bits are greater than or equal 64.
      *
      * @implSpec  Since algorithms will improve over time, there is no
      * guarantee that this method will return the same algorithm over time.
      *
      * @return a {@link RandomGeneratorFactory}
      */
     public static RandomGeneratorFactory<RandomGenerator> getDefault() {
         return factoryOf("L32X64MixRandom", RandomGenerator.class);
     }

     /**
      * Returns a non-empty stream of available {@link RandomGeneratorFactory RandomGeneratorFactory(s)}.
      *
      * RandomGenerators that are marked as deprecated or are not properly configured are not included in the result.
      *
      * @implSpec Availability is determined by RandomGeneratorFactory using the service provider API
      * to locate implementations of the RandomGenerator interface.
      *
      * @return a non-empty stream of all available {@link RandomGeneratorFactory RandomGeneratorFactory(s)}.
      */
     public static Stream<RandomGeneratorFactory<RandomGenerator>> all() {
         Map<String, Provider<? extends RandomGenerator>> fm = getFactoryMap();
         return fm.values()
                  .stream()
                  .filter(p -> !p.type().isAnnotationPresent(Deprecated.class) &&
                               p.type().isAnnotationPresent(RandomGeneratorProperties.class))
                  .map(RandomGeneratorFactory::new);
     }

     /**
      * Return the name of the <a href="package-summary.html#algorithms">algorithm</a>
      * used by the random number generator.
      *
      * @return Name of the <a href="package-summary.html#algorithms">algorithm</a>.
      */
     public String name() {
         return provider.type().getSimpleName();
     }

     /**
      * Return the group name of the <a href="package-summary.html#algorithms">algorithm</a>
      * used by the random number generator.
      *
      * @return Group name of the <a href="package-summary.html#algorithms">algorithm</a>.
      */
     public String group() {
         return getProperties().group();
     }

     /**
      * Returns number of bits used by the <a href="package-summary.html#algorithms">algorithm</a>
      * to maintain state of seed.
      *
      * @return number of bits used by the <a href="package-summary.html#algorithms">algorithm</a>
      *         to maintain state of seed.
      */
     public int stateBits() {
         RandomGeneratorProperties properties = getProperties();
         int i = properties.i();
         int k = properties.k();

         return i == 0 && k == 0 ? Integer.MAX_VALUE : i + k;
     }

     /**
      * Returns the equidistribution of the <a href="package-summary.html#algorithms">algorithm</a>.
      *
      * @return the equidistribution of the <a href="package-summary.html#algorithms">algorithm</a>.
      */
     public int equidistribution() {
         return getProperties().equidistribution();
     }

     /**
      * Return the period of the <a href="package-summary.html#algorithms">algorithm</a>
      * used by the random number generator.
      * Returns BigInteger.ZERO if period is not determinable.
      *
      * @return BigInteger period.
      */
     public BigInteger period() {
         RandomGeneratorProperties properties = getProperties();
         int i = properties.i();
         int j = properties.j();
         int k = properties.k();

         if (i == 0 && j == 0 && k == 0) {
             return BigInteger.ZERO;
         } else {
             return BigInteger.ONE.shiftLeft(i).subtract(BigInteger.valueOf(j)).shiftLeft(k);
         }
     }

     /**
      * Return true if random generator is computed using an arithmetic
      * <a href="package-summary.html#algorithms">algorithm</a>
      * and is statistically deterministic.
      *
      * @return true if random generator is statistical.
      */
     public boolean isStatistical() {
         return !getProperties().isStochastic();
     }

     /**
      * Return true if random generator is computed using external or entropic
      * sources as inputs.
      *
      * @return true if random generator is stochastic.
      */
     public boolean isStochastic() {
         return getProperties().isStochastic();
     }

     /**
      * Return true if random generator uses a hardware device (HRNG) to produce
      * entropic input.
      *
      * @return true if random generator is generated by hardware.
      */
     public boolean isHardware() {
         return getProperties().isHardware();
     }

     /**
      * Return true if random generator can jump an arbitrarily specified distant
      * point in the state cycle.
      *
      * @return true if random generator is arbitrarily jumpable.
      */
     public boolean isArbitrarilyJumpable() {
         return isSubclass(ArbitrarilyJumpableGenerator.class);
     }

     /**
      * Return true if random generator can jump a specified distant point in
      * the state cycle.
      *
      * @return true if random generator is jumpable.
      */
     public boolean isJumpable() {
         return isSubclass(JumpableGenerator.class);
     }

     /**
      * Return true if random generator is jumpable and can leap to a very distant
      * point in the state cycle.
      *
      * @return true if random generator is leapable.
      */
     public boolean isLeapable() {
         return isSubclass(LeapableGenerator.class);
     }

     /**
      * Return true if random generator can be cloned into a separate object with
      * the same properties but positioned further in the state cycle.
      *
      * @return true if random generator is splittable.
      */
     public boolean isSplittable() {
         return isSubclass(SplittableGenerator.class);
     }

     /**
      * Return true if random generator can be used to create
      * {@link java.util.stream.Stream Streams} of random numbers.
      *
      * @return true if random generator is streamable.
      */
     public boolean isStreamable() {
         return isSubclass(StreamableGenerator.class);
     }

     /**
      * Return true if the implementation of RandomGenerator (algorithm) has been
      * marked for deprecation.
      *
      * @implNote Random number generator algorithms evolve over time; new
      *           algorithms will be introduced and old algorithms will
      *           lose standing. If an older algorithm is deemed unsuitable
      *           for continued use, it will be marked as deprecated to indicate
      *           that it may be removed at some point in the future.
      *
      * @return true if the implementation of RandomGenerator (algorithm) has been
      *         marked for deprecation
      */
      public boolean isDeprecated() {
         return provider.type().isAnnotationPresent(Deprecated.class);
      }

     /**
      * Create an instance of {@link RandomGenerator} based on
      * <a href="package-summary.html#algorithms">algorithm</a> chosen.
      *
      * @return new in instance of {@link RandomGenerator}.
      *
      */
     public T create() {
         try {
             ensureConstructors();
             return ctor.newInstance();
         } catch (Exception ex) {
             // Should never happen.
             throw new IllegalStateException("Random algorithm " + name() + " is missing a default constructor", ex);
         }
     }

     /**
      * 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.
      *
      * @param seed long random seed value.
      *
      * @return new in instance of {@link RandomGenerator}.
      */
     public T create(long seed) {
         try {
             ensureConstructors();
             return ctorLong.newInstance(seed);
         } catch (Exception ex) {
             return create();
         }
     }

     /**
      * 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.
      *
      * @param seed byte array random seed value.
      *
      * @return new in instance of {@link RandomGenerator}.
      *
      * @throws NullPointerException if seed is null.
      */
     public T create(byte[] seed) {
         Objects.requireNonNull(seed, "seed must not be null");
         try {
             ensureConstructors();
             return ctorBytes.newInstance(seed);
         } catch (Exception ex) {
             return create();
         }
     }

 }
	/*
	* Copyright (c) 2021, Oracle and/or its affiliates. All rights reserved.
	* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
	*
	* This code is free software; you can redistribute it and/or modify it
	* under the terms of the GNU General Public License version 2 only, as
	* published by the Free Software Foundation. Oracle designates this
	* particular file as subject to the "Classpath" exception as provided
	* by Oracle in the LICENSE file that accompanied this code.
	*
	* This code is distributed in the hope that it will be useful, but WITHOUT
	* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
	* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
	* version 2 for more details (a copy is included in the LICENSE file that
	* accompanied this code).
	*
	* You should have received a copy of the GNU General Public License version
	* 2 along with this work; if not, write to the Free Software Foundation,
	* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
	*
	* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
	* or visit www.oracle.com if you need additional information or have any
	* questions.
	*/

	package java.util.random;

	import java.lang.reflect.Constructor;
	import java.math.BigInteger;
	import java.security.AccessController;
	import java.security.PrivilegedActionException;
	import java.security.PrivilegedExceptionAction;
	import java.util.Objects;
	import java.util.function.Function;
	import java.util.Map;
	import java.util.random.RandomGenerator.ArbitrarilyJumpableGenerator;
	import java.util.random.RandomGenerator.JumpableGenerator;
	import java.util.random.RandomGenerator.LeapableGenerator;
	import java.util.random.RandomGenerator.SplittableGenerator;
	import java.util.random.RandomGenerator.StreamableGenerator;
	import java.util.ServiceLoader;
	import java.util.ServiceLoader.Provider;
	import java.util.stream.Collectors;
	import java.util.stream.Stream;
	import jdk.internal.util.random.RandomSupport.RandomGeneratorProperties;

	/**
	* This is a factory class for generating multiple random number generators
	* of a specific <a href="package-summary.html#algorithms">algorithm</a>.
	* {@link RandomGeneratorFactory} also provides
	* methods for selecting random number generator algorithms.
	*
	* A specific {@link RandomGeneratorFactory} can be located by using the
	* {@link RandomGeneratorFactory#of(String)} method, where the argument string
	* is the name of the <a href="package-summary.html#algorithms">algorithm</a>
	* required. The method
	* {@link RandomGeneratorFactory#all()} produces a non-empty {@link Stream} of all available
	* {@link RandomGeneratorFactory RandomGeneratorFactorys} that can be searched
	* to locate a {@link RandomGeneratorFactory} suitable to the task.
	*
	* There are three methods for constructing a RandomGenerator instance,
	* depending on the type of initial seed required.
	* {@link RandomGeneratorFactory#create(long)} is used for long
	* seed construction,
	* {@link RandomGeneratorFactory#create(byte[])} is used for byte[]
	* seed construction, and
	* {@link RandomGeneratorFactory#create()} is used for random seed
	* construction. Example;
	*
	* <pre>{@code
	* RandomGeneratorFactory<RandomGenerator> factory = RandomGeneratorFactory.of("Random");
	*
	* for (int i = 0; i < 10; i++) {
	* new Thread(() -> {
	* RandomGenerator random = factory.create(100L);
	* System.out.println(random.nextDouble());
	* }).start();
	* }
	* }</pre>
	*
	* RandomGeneratorFactory also provides methods describing the attributes (or properties)
	* of a generator and can be used to select random number generator
	* <a href="package-summary.html#algorithms">algorithms</a>.
	* These methods are typically used in
	* conjunction with {@link RandomGeneratorFactory#all()}. In this example, the code
	* locates the {@link RandomGeneratorFactory} that produces
	* {@link RandomGenerator RandomGenerators}
	* with the highest number of state bits.
	*
	* <pre>{@code
	* RandomGeneratorFactory<RandomGenerator> best = RandomGeneratorFactory.all()
	* .sorted(Comparator.comparingInt(RandomGenerator::stateBits).reversed())
	* .findFirst()
	* .orElse(RandomGeneratorFactory.of("Random"));
	* System.out.println(best.name() + " in " + best.group() + " was selected");
	*
	* RandomGenerator rng = best.create();
	* System.out.println(rng.nextLong());
	* }</pre>
	*
	* @since 17
	*
	* @see java.util.random
	*
	*/
	public final class RandomGeneratorFactory<T extends RandomGenerator> {
	/**
	* Instance provider class of random number algorithm.
	*/
	private final Provider<? extends RandomGenerator> provider;

	/**
	* Provider RandomGeneratorProperties annotation.
	*/
	private volatile RandomGeneratorProperties properties;

	/**
	* Default provider constructor.
	*/
	private volatile Constructor<T> ctor;

	/**
	* Provider constructor with long seed.
	*/
	private Constructor<T> ctorLong;

	/**
	* Provider constructor with byte[] seed.
	*/
	private Constructor<T> ctorBytes;


	private static class FactoryMapHolder {
	static final Map<String, Provider<? extends RandomGenerator>> FACTORY_MAP = createFactoryMap();

	/**
	* Returns the factory map, lazily constructing map on first use.
	*
	* @return Map of RandomGeneratorFactory classes.
	*/
	private static Map<String, Provider<? extends RandomGenerator>> createFactoryMap() {
	return ServiceLoader
	.load(RandomGenerator.class)
	.stream()
	.filter(p -> !p.type().isInterface())
	.collect(Collectors.toMap(p -> p.type().getSimpleName(), Function.identity()));
	}
	}

	/**
	* Private constructor.
	*
	* @param provider Provider class to wrap.
	*/
	private RandomGeneratorFactory(Provider<? extends RandomGenerator> provider) {
	this.provider = provider;
	}

	/**
	* Returns the factory map, lazily constructing map on first call.
	*
	* @return Map of RandomGeneratorFactory classes.
	*/
	private static Map<String, Provider<? extends RandomGenerator>> getFactoryMap() {
	return FactoryMapHolder.FACTORY_MAP;
	}

	/**
	* Return the annotation for the specified provider.
	*
	* @return RandomGeneratorProperties annotation for the specified provider.
	*/
	private RandomGeneratorProperties getProperties() {
	if (properties == null) {
	synchronized (provider) {
	if (properties == null) {
	properties = provider.type().getDeclaredAnnotation(RandomGeneratorProperties.class);
	Objects.requireNonNull(properties, provider.type() + " missing annotation");
	}
	}
	}

	return properties;
	}

	/**
	* Return true if the provider is a subclass of the category.
	*
	* @param category Interface category, sub-interface of {@link RandomGenerator}.
	*
	* @return true if the provider is a subclass of the category.
	*/
	private boolean isSubclass(Class<? extends RandomGenerator> category) {
	return isSubclass(category, provider);
	}

	/**
	* Return true if the provider is a subclass of the category.
	*
	* @param category Interface category, sub-interface of {@link RandomGenerator}.
	* @param provider Provider that is being filtered.
	*
	* @return true if the provider is a subclass of the category.
	*/
	private static boolean isSubclass(Class<? extends RandomGenerator> category,
	Provider<? extends RandomGenerator> provider) {
	return provider != null && category.isAssignableFrom(provider.type());
	}

	/**
	* Returns the provider matching name and category.
	*
	* @param name Name of RandomGenerator
	* @param category Interface category, sub-interface of {@link RandomGenerator}.
	*
	* @return A provider matching name and category.
	*
	* @throws IllegalArgumentException if provider is not a subclass of category.
	*/
	private static Provider<? extends RandomGenerator> findProvider(String name,
	Class<? extends RandomGenerator> category)
	throws IllegalArgumentException {
	Map<String, Provider<? extends RandomGenerator>> fm = getFactoryMap();
	Provider<? extends RandomGenerator> provider = fm.get(name);
	if (provider == null) {
	throw new IllegalArgumentException("No implementation of the random number generator algorithm \"" +
	name +
	"\" is available");
	} else if (!isSubclass(category, provider)) {
	throw new IllegalArgumentException("The random number generator algorithm \"" +
	name +
	"\" is not implemented with the interface \"" +
	category.getSimpleName() +
	"\"");
	}
	return provider;
	}

	/**
	* Returns a {@link RandomGenerator} that utilizes the {@code name}
	* <a href="package-summary.html#algorithms">algorithm</a>.
	*
	* @param name Name of random number algorithm to use
	* @param category Sub-interface of {@link RandomGenerator} to type check
	* @param <T> Sub-interface of {@link RandomGenerator} to produce
	*
	* @return An instance of {@link RandomGenerator}
	*
	* @throws IllegalArgumentException when either the name or category is null
	*/
	static <T extends RandomGenerator> T of(String name, Class<T> category)
	throws IllegalArgumentException {
	@SuppressWarnings("unchecked")
	T uncheckedRandomGenerator = (T)findProvider(name, category).get();
	return uncheckedRandomGenerator;
	}

	/**
	* Returns a {@link RandomGeneratorFactory} that will produce instances
	* of {@link RandomGenerator} that utilizes the named algorithm.
	*
	* @param name Name of random number algorithm to use
	* @param category Sub-interface of {@link RandomGenerator} to type check
	* @param <T> Sub-interface of {@link RandomGenerator} to produce
	*
	* @return Factory of {@link RandomGenerator}
	*
	* @throws IllegalArgumentException when either the name or category is null
	*/
	static <T extends RandomGenerator> RandomGeneratorFactory<T> factoryOf(String name, Class<T> category)
	throws IllegalArgumentException {
	Provider<? extends RandomGenerator> uncheckedProvider = findProvider(name, category);
	return new RandomGeneratorFactory<>(uncheckedProvider);
	}

	/**
	* Fetch the required constructors for class of random number algorithm.
	*
	* @param randomGeneratorClass class of random number algorithm (provider)
	*/
	private void getConstructors(Class<? extends RandomGenerator> randomGeneratorClass) {
	if (ctor == null) {
	synchronized (provider) {
	if (ctor == null) {
	PrivilegedExceptionAction<Constructor<?>[]> ctorAction = randomGeneratorClass::getConstructors;
	try {
	@SuppressWarnings("removal")
	Constructor<?>[] ctors = AccessController.doPrivileged(ctorAction);

	Constructor<T> tmpCtor = null;
	Constructor<T> tmpCtorLong = null;
	Constructor<T> tmpCtorBytes = null;


	for (Constructor<?> ctorGeneric : ctors) {
	@SuppressWarnings("unchecked")
	Constructor<T> ctorSpecific = (Constructor<T>) ctorGeneric;
	final Class<?>[] parameterTypes = ctorSpecific.getParameterTypes();

	if (parameterTypes.length == 0) {
	tmpCtor = ctorSpecific;
	} else if (parameterTypes.length == 1) {
	Class<?> argType = parameterTypes[0];

	if (argType == long.class) {
	tmpCtorLong = ctorSpecific;
	} else if (argType == byte[].class) {
	tmpCtorBytes = ctorSpecific;
	}
	}
	}

	if (tmpCtor == null) {
	throw new IllegalStateException("Random algorithm " + name() + " is missing a default constructor");
	}

	// Store specialized constructors first, guarded by ctor
	ctorBytes = tmpCtorBytes;
	ctorLong = tmpCtorLong;
	ctor = tmpCtor;
	} catch (PrivilegedActionException ex) {
	// Do nothing
	}
	}
	}
	}
	}

	/**
	* Ensure all the required constructors are fetched.
	*/
	private void ensureConstructors() {
	getConstructors(provider.type());
	}

	/**
	* Returns a {@link RandomGeneratorFactory} that can produce instances of
	* {@link RandomGenerator} that utilize the {@code name}
	* <a href="package-summary.html#algorithms">algorithm</a>.
	*
	* @implSpec Availability is determined by RandomGeneratorFactory using the
	* service provider API to locate implementations of the RandomGenerator interface.
	*
	* @param name Name of random number generator
	* <a href="package-summary.html#algorithms">algorithm</a>
	* @param <T> Sub-interface of {@link RandomGenerator} to produce
	*
	* @return {@link RandomGeneratorFactory} of {@link RandomGenerator}
	*
	* @throws NullPointerException if name is null
	* @throws IllegalArgumentException if the named algorithm is not found
	*/
	public static <T extends RandomGenerator> RandomGeneratorFactory<T> of(String name) {
	Objects.requireNonNull(name);
	@SuppressWarnings("unchecked")
	RandomGeneratorFactory<T> factory =
	(RandomGeneratorFactory<T>)factoryOf(name, RandomGenerator.class);
	return factory;
	}

	/**
	* Returns a {@link RandomGeneratorFactory} meeting the minimal requirement
	* of having an algorithm whose state bits are greater than or equal 64.
	*
	* @implSpec Since algorithms will improve over time, there is no
	* guarantee that this method will return the same algorithm over time.
	*
	* @return a {@link RandomGeneratorFactory}
	*/
	public static RandomGeneratorFactory<RandomGenerator> getDefault() {
	return factoryOf("L32X64MixRandom", RandomGenerator.class);
	}

	/**
	* Returns a non-empty stream of available {@link RandomGeneratorFactory RandomGeneratorFactory(s)}.
	*
	* RandomGenerators that are marked as deprecated or are not properly configured are not included in the result.
	*
	* @implSpec Availability is determined by RandomGeneratorFactory using the service provider API
	* to locate implementations of the RandomGenerator interface.
	*
	* @return a non-empty stream of all available {@link RandomGeneratorFactory RandomGeneratorFactory(s)}.
	*/
	public static Stream<RandomGeneratorFactory<RandomGenerator>> all() {
	Map<String, Provider<? extends RandomGenerator>> fm = getFactoryMap();
	return fm.values()
	.stream()
	.filter(p -> !p.type().isAnnotationPresent(Deprecated.class) &&
	p.type().isAnnotationPresent(RandomGeneratorProperties.class))
	.map(RandomGeneratorFactory::new);
	}

	/**
	* Return the name of the <a href="package-summary.html#algorithms">algorithm</a>
	* used by the random number generator.
	*
	* @return Name of the <a href="package-summary.html#algorithms">algorithm</a>.
	*/
	public String name() {
	return provider.type().getSimpleName();
	}

	/**
	* Return the group name of the <a href="package-summary.html#algorithms">algorithm</a>
	* used by the random number generator.
	*
	* @return Group name of the <a href="package-summary.html#algorithms">algorithm</a>.
	*/
	public String group() {
	return getProperties().group();
	}

	/**
	* Returns number of bits used by the <a href="package-summary.html#algorithms">algorithm</a>
	* to maintain state of seed.
	*
	* @return number of bits used by the <a href="package-summary.html#algorithms">algorithm</a>
	* to maintain state of seed.
	*/
	public int stateBits() {
	RandomGeneratorProperties properties = getProperties();
	int i = properties.i();
	int k = properties.k();

	return i == 0 && k == 0 ? Integer.MAX_VALUE : i + k;
	}

	/**
	* Returns the equidistribution of the <a href="package-summary.html#algorithms">algorithm</a>.
	*
	* @return the equidistribution of the <a href="package-summary.html#algorithms">algorithm</a>.
	*/
	public int equidistribution() {
	return getProperties().equidistribution();
	}

	/**
	* Return the period of the <a href="package-summary.html#algorithms">algorithm</a>
	* used by the random number generator.
	* Returns BigInteger.ZERO if period is not determinable.
	*
	* @return BigInteger period.
	*/
	public BigInteger period() {
	RandomGeneratorProperties properties = getProperties();
	int i = properties.i();
	int j = properties.j();
	int k = properties.k();

	if (i == 0 && j == 0 && k == 0) {
	return BigInteger.ZERO;
	} else {
	return BigInteger.ONE.shiftLeft(i).subtract(BigInteger.valueOf(j)).shiftLeft(k);
	}
	}

	/**
	* Return true if random generator is computed using an arithmetic
	* <a href="package-summary.html#algorithms">algorithm</a>
	* and is statistically deterministic.
	*
	* @return true if random generator is statistical.
	*/
	public boolean isStatistical() {
	return !getProperties().isStochastic();
	}

	/**
	* Return true if random generator is computed using external or entropic
	* sources as inputs.
	*
	* @return true if random generator is stochastic.
	*/
	public boolean isStochastic() {
	return getProperties().isStochastic();
	}

	/**
	* Return true if random generator uses a hardware device (HRNG) to produce
	* entropic input.
	*
	* @return true if random generator is generated by hardware.
	*/
	public boolean isHardware() {
	return getProperties().isHardware();
	}

	/**
	* Return true if random generator can jump an arbitrarily specified distant
	* point in the state cycle.
	*
	* @return true if random generator is arbitrarily jumpable.
	*/
	public boolean isArbitrarilyJumpable() {
	return isSubclass(ArbitrarilyJumpableGenerator.class);
	}

	/**
	* Return true if random generator can jump a specified distant point in
	* the state cycle.
	*
	* @return true if random generator is jumpable.
	*/
	public boolean isJumpable() {
	return isSubclass(JumpableGenerator.class);
	}

	/**
	* Return true if random generator is jumpable and can leap to a very distant
	* point in the state cycle.
	*
	* @return true if random generator is leapable.
	*/
	public boolean isLeapable() {
	return isSubclass(LeapableGenerator.class);
	}

	/**
	* Return true if random generator can be cloned into a separate object with
	* the same properties but positioned further in the state cycle.
	*
	* @return true if random generator is splittable.
	*/
	public boolean isSplittable() {
	return isSubclass(SplittableGenerator.class);
	}

	/**
	* Return true if random generator can be used to create
	* {@link java.util.stream.Stream Streams} of random numbers.
	*
	* @return true if random generator is streamable.
	*/
	public boolean isStreamable() {
	return isSubclass(StreamableGenerator.class);
	}

	/**
	* Return true if the implementation of RandomGenerator (algorithm) has been
	* marked for deprecation.
	*
	* @implNote Random number generator algorithms evolve over time; new
	* algorithms will be introduced and old algorithms will
	* lose standing. If an older algorithm is deemed unsuitable
	* for continued use, it will be marked as deprecated to indicate
	* that it may be removed at some point in the future.
	*
	* @return true if the implementation of RandomGenerator (algorithm) has been
	* marked for deprecation
	*/
	public boolean isDeprecated() {
	return provider.type().isAnnotationPresent(Deprecated.class);
	}

	/**
	* Create an instance of {@link RandomGenerator} based on
	* <a href="package-summary.html#algorithms">algorithm</a> chosen.
	*
	* @return new in instance of {@link RandomGenerator}.
	*
	*/
	public T create() {
	try {
	ensureConstructors();
	return ctor.newInstance();
	} catch (Exception ex) {
	// Should never happen.
	throw new IllegalStateException("Random algorithm " + name() + " is missing a default constructor", ex);
	}
	}

	/**
	* 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.
	*
	* @param seed long random seed value.
	*
	* @return new in instance of {@link RandomGenerator}.
	*/
	public T create(long seed) {
	try {
	ensureConstructors();
	return ctorLong.newInstance(seed);
	} catch (Exception ex) {
	return create();
	}
	}

	/**
	* 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.
	*
	* @param seed byte array random seed value.
	*
	* @return new in instance of {@link RandomGenerator}.
	*
	* @throws NullPointerException if seed is null.
	*/
	public T create(byte[] seed) {
	Objects.requireNonNull(seed, "seed must not be null");
	try {
	ensureConstructors();
	return ctorBytes.newInstance(seed);
	} catch (Exception ex) {
	return create();
	}
	}

	}