Demonstrate random number generation

Author: Nicolai Parlog

README.md

@@ -89,6 +89,7 @@ Check out the [jpms](http://blog.codefx.org/tag/jpms/) tag on my blog, [this dem
 
 ## New APIs
 
+* ⑰ [random generator](src/main/java/org/codefx/demo/java17/api/random) ([article](https://nipafx.dev/java-random-generator/), [JEP 356](https://openjdk.java.net/jeps/356), [very good Javadoc](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/random/package-summary.html))
 * ⑯ [Unix domain sockets](src/main/java/org/codefx/demo/java16/api/unix_sockets) ([article](https://nipafx.dev/java-unix-domain-sockets/), [JEP-380](https://openjdk.java.net/jeps/380))
 * ⑪ HTTP/2 client: [simple](src/main/java/org/codefx/demo/java11/api/http2/Http2Api.java), [more formal](src/main/java/org/codefx/demo/java11/api/http2/formalized) ([tutorial](https://blog.codefx.org/java/http-2-api-tutorial/), [reactive request/response bodies](https://blog.codefx.org/java/reactive-http-2-requests-responses/))
 * ⑩⑨ version API, [introduced in Java 9](src/main/java/org/codefx/demo/java9/api/version/VersionApi.java),

pom.xml

@@ -51,6 +51,8 @@
 					<compilerArgs>
 						<!-- get access to `@ReservedStackAccess` in `ReservedStackAccess` -->
 						<arg>--add-exports=java.base/jdk.internal.vm.annotation=org.codefx.demo.java_x</arg>
+						<!-- get access to `@RandomGeneratorProperties` in `Xkcd` -->
+						<arg>--add-exports=java.base/jdk.internal.util.random=org.codefx.demo.java_x</arg>
 					</compilerArgs>
 				</configuration>
 			</plugin>
@@ -104,6 +106,10 @@
 				<configuration>
 					<sourcepath>src/main/java</sourcepath>
 					<subpackages>org.codefx.demo.java18.jvm.javadoc</subpackages>
+					<additionalJOptions>
+						<!-- get access to `@RandomGeneratorProperties` in `Xkcd` -->
+						<additionalJOption>--add-exports=java.base/jdk.internal.util.random=org.codefx.demo.java_x</additionalJOption>
+					</additionalJOptions>
 				</configuration>
 				<executions>
 					<execution>

src/main/java/module-info.java

@@ -1,3 +1,7 @@
+import org.codefx.demo.java17.api.random.Xkcd;
+
+import java.util.random.RandomGenerator;
+
 /**
  * Project demonstrating various Java features introduced since Java 9.
  */
@@ -6,4 +10,6 @@
 
 	requires java.desktop;
 	requires java.net.http;
+
+	provides RandomGenerator with Xkcd;
 }

src/main/java/org/codefx/demo/java17/api/random/RandomGeneratorFactories.java

@@ -0,0 +1,53 @@
+package org.codefx.demo.java17.api.random;
+
+import java.util.random.RandomGenerator;
+import java.util.random.RandomGenerator.ArbitrarilyJumpableGenerator;
+import java.util.random.RandomGeneratorFactory;
+import java.util.stream.Stream;
+
+public class RandomGeneratorFactories {
+
+	// to run this, you need to add the following command line option:
+	// --add-exports=java.base/jdk.internal.util.random=org.codefx.demo.java_x
+	public static void main(String[] args) {
+		RandomGenerator with128StateBits = createWithAtLeastStateBits(128);
+
+		System.out.println("ARBITRARILY JUMPABLE GENERATORS:");
+		// if everything went well, this should show the custom XKCD generator,
+		// which is integrated with the generator factory API
+		createArbitrarilyJumpableGenerators()
+				.forEach(g -> System.out.println(" - " + g.getClass().getName()));
+
+		System.out.println("STOCHASTIC GENERATORS:");
+		createStochasticGenerators()
+				.forEach(g -> System.out.println(" - " + g.getClass().getName()));
+	}
+
+	/*
+	 * The casts aren't ideal. If you don't want to call the interface-specific
+	 * methods on the created instances, they're not needed.
+	 */
+
+	private static RandomGenerator createWithAtLeastStateBits(int stateBits) {
+		return RandomGeneratorFactory.all()
+				.filter(factory -> factory.stateBits() >= stateBits)
+				.findAny()
+				.map(RandomGeneratorFactory::create)
+				.orElseThrow();
+	}
+
+
+	private static Stream<ArbitrarilyJumpableGenerator> createArbitrarilyJumpableGenerators() {
+		return RandomGeneratorFactory.all()
+				.filter(RandomGeneratorFactory::isArbitrarilyJumpable)
+				.map(RandomGeneratorFactory::create)
+				.map(ArbitrarilyJumpableGenerator.class::cast);
+	}
+
+	private static Stream<RandomGenerator> createStochasticGenerators() {
+		return RandomGeneratorFactory.all()
+				.filter(RandomGeneratorFactory::isStochastic)
+				.map(RandomGeneratorFactory::create);
+	}
+
+}

src/main/java/org/codefx/demo/java17/api/random/RandomGenerators.java

@@ -0,0 +1,86 @@
+package org.codefx.demo.java17.api.random;
+
+import java.security.SecureRandom;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Random;
+import java.util.SplittableRandom;
+import java.util.concurrent.ThreadLocalRandom;
+import java.util.random.RandomGenerator;
+import java.util.random.RandomGenerator.JumpableGenerator;
+import java.util.random.RandomGenerator.LeapableGenerator;
+import java.util.random.RandomGenerator.SplittableGenerator;
+
+public class RandomGenerators {
+
+	public static void main(String[] args) {
+		newInterface();
+		simpleCreation();
+		moreInterfaces();
+	}
+
+	private static void newInterface() {
+		// `RandomGenerator` is a new interface that combines the APIs
+		// of pre-existing random classes, which all implement it
+		RandomGenerator random = new Random();
+		RandomGenerator threadLocal = ThreadLocalRandom.current();
+		RandomGenerator secure = new SecureRandom();
+		RandomGenerator splittable = new SplittableRandom();
+	}
+
+	private static void simpleCreation() {
+		// if you have no requirements
+		var generator = RandomGenerator.getDefault();
+		// if you know which algorithm you need
+		// (be careful, this is fragile as algorithms can be removed;
+		//  use RandomGeneratorFactory instead - see other demo class)
+		// (for implemented algorithms, see Javadoc of java.util.random)
+		var lxm = RandomGenerator.of("L128X128MixRandom");
+		var xoshiro = RandomGenerator.of("Xoshiro256PlusPlus");
+	}
+
+	private static void moreInterfaces() {
+		// There are many more new interfaces. They all extend `RandomGenerator`
+		// and only differ in how you can create a new instance from an existing one.
+
+		// The casts aren't ideal. If you don't want to call the interface-specific
+		// methods on the newly-created instances, they're not needed.
+		
+		JumpableGenerator jumpable = JumpableGenerator.of("Xoroshiro128PlusPlus");
+		JumpableGenerator newJumpable = (JumpableGenerator) jumpable.copyAndJump();
+
+		LeapableGenerator leapable = LeapableGenerator.of("Xoshiro256PlusPlus");
+		LeapableGenerator newLeapable = (LeapableGenerator) leapable.copyAndLeap();
+
+		// there's no `ArbitrarilyJumpableGenerator` (in JDK 18)
+//		ArbitrarilyJumpableGenerator arbitrarilyJumpable = ArbitrarilyJumpableGenerator.of("Xoshiro256PlusPlus");
+
+		SplittableGenerator splittable = SplittableGenerator.of("L128X1024MixRandom");
+		SplittableGenerator newSplittable = splittable.split();
+	}
+
+	private long randomPercentage(Random random) {
+		// compile error on JDK <17 :( because there,
+		// `nextLong(bound)` only exists on
+		// `SplittableRandom` and `ThreadLocalRandom`
+		return random.nextLong(101);
+	}
+
+	private record User() {
+
+		// nay (don't pass specific classes)
+		User randomUser(ArrayList<User> users, Random random) {
+			int index = random.nextInt(users.size());
+			return users.get(index);
+		}
+
+		// yay (instead pass the new interface)
+		User randomUser(List<User> users, RandomGenerator random) {
+			int index = random.nextInt(users.size());
+			return users.get(index);
+		}
+
+	}
+
+
+}

src/main/java/org/codefx/demo/java17/api/random/Xkcd.java

@@ -0,0 +1,55 @@
+package org.codefx.demo.java17.api.random;
+
+import jdk.internal.util.random.RandomSupport.RandomGeneratorProperties;
+
+import java.util.random.RandomGenerator.ArbitrarilyJumpableGenerator;
+
+/*
+ * It's possible to provide custom implementations of the generator interfaces that
+ * get picked up by the generator factory API (including the `.of("name")` methods),
+ * but that requires use of the JDK-internal annotation `@RandomGeneratorProperties`.
+ *
+ * While this works, the integration mechanism isn't meant for public use.
+ */
+
+@RandomGeneratorProperties(
+		name="xkcd",
+		group="fancypants",
+		equidistribution = 0,
+		i = 1,
+		k = -1
+)
+public class Xkcd implements ArbitrarilyJumpableGenerator {
+
+	@Override
+	public ArbitrarilyJumpableGenerator copy() {
+		return this;
+	}
+
+	@Override
+	public double jumpDistance() {
+		return Math.pow(2, 64);
+	}
+
+	@Override
+	public double leapDistance() {
+		return Math.pow(2, 128);
+	}
+
+	@Override
+	public void jumpPowerOfTwo(int logDistance) { }
+
+	@Override
+	public void jump(double distance) {	}
+
+	@Override
+	public long nextLong() {
+		return 4;
+	}
+
+	@Override
+	public String toString() {
+		return "XKCD Random Number Generator - chosen by fair dice roll";
+	}
+
+}