24 */ |
24 */ |
25 |
25 |
26 package java.util.random; |
26 package java.util.random; |
27 |
27 |
28 import java.math.BigInteger; |
28 import java.math.BigInteger; |
|
29 import java.util.Objects; |
29 import java.util.stream.DoubleStream; |
30 import java.util.stream.DoubleStream; |
30 import java.util.stream.IntStream; |
31 import java.util.stream.IntStream; |
31 import java.util.stream.LongStream; |
32 import java.util.stream.LongStream; |
32 import java.util.stream.Stream; |
33 import java.util.stream.Stream; |
33 import java.util.stream.StreamSupport; |
|
34 |
34 |
35 /** |
35 /** |
36 * The {@link RandomGenerator} interface is designed to provide a common protocol for objects |
36 * The {@link RandomGenerator} interface is designed to provide a common protocol for objects |
37 * that generate random or (more typically) pseudorandom sequences of numbers (or Boolean values). |
37 * that generate random or (more typically) pseudorandom sequences of numbers (or Boolean values). |
38 * Such a sequence may be obtained by either repeatedly invoking a method that returns a single |
38 * Such a sequence may be obtained by either repeatedly invoking a method that returns a single |
88 * @since 14 |
88 * @since 14 |
89 */ |
89 */ |
90 public interface RandomGenerator { |
90 public interface RandomGenerator { |
91 |
91 |
92 /** |
92 /** |
|
93 * Supported randpm number Algorithms. |
|
94 */ |
|
95 public enum Algorithm { |
|
96 /** |
|
97 * L32X64MixRandom algorithm |
|
98 */ |
|
99 L32X64MixRandom("L32X64MixRandom"), |
|
100 /** |
|
101 * L64X1024MixRandom algorithm |
|
102 */ |
|
103 L64X1024MixRandom("L64X1024MixRandom"), |
|
104 /** |
|
105 * L64X1024Random algorithm |
|
106 */ |
|
107 L64X1024Random("L64X1024Random"), |
|
108 /** |
|
109 * L64X128MixRandom algorithm |
|
110 */ |
|
111 L64X128MixRandom("L64X128MixRandom"), |
|
112 /** |
|
113 * L64X128Random algorithm |
|
114 */ |
|
115 L64X128Random("L64X128Random"), |
|
116 /** |
|
117 * L64X256MixRandom algorithm |
|
118 */ |
|
119 L64X256MixRandom("L64X256MixRandom"), |
|
120 /** |
|
121 * L64X256Random algorithm |
|
122 */ |
|
123 L64X256Random("L64X256Random"), |
|
124 /** |
|
125 * L128X256MixRandom algorithm |
|
126 */ |
|
127 L128X256MixRandom("L128X256MixRandom"), |
|
128 /** |
|
129 * MRG32k3a algorithm |
|
130 */ |
|
131 MRG32k3a("MRG32k3a"), |
|
132 /** |
|
133 * Xoroshiro128Plus algorithm |
|
134 */ |
|
135 Xoroshiro128Plus("Xoroshiro128Plus"), |
|
136 /** |
|
137 * Xoroshiro128StarStar algorithm |
|
138 */ |
|
139 Xoroshiro128StarStar("Xoroshiro128StarStar"), |
|
140 /** |
|
141 * Xoshiro256StarStar algorithm |
|
142 */ |
|
143 Xoshiro256StarStar("Xoshiro256StarStar"); |
|
144 |
|
145 private String name; |
|
146 |
|
147 Algorithm(String name) { |
|
148 this.name = name; |
|
149 } |
|
150 |
|
151 public String toString() { |
|
152 return name; |
|
153 } |
|
154 } |
|
155 |
|
156 /** |
|
157 * Returns an instance of {@link RandomGenerator} that utilizes the |
|
158 * {@code name} algorithm. |
|
159 * |
|
160 * @param name Name of random number generator algorithm |
|
161 * |
|
162 * @return An instance of {@link RandomGenerator} |
|
163 */ |
|
164 public static RandomGenerator of(String name) { |
|
165 Objects.requireNonNull(name); |
|
166 return RandomGeneratorFactory.of(name, RandomGenerator.class); |
|
167 } |
|
168 |
|
169 /** |
|
170 * Returns an instance of {@link RandomGenerator} that utilizes the |
|
171 * specified {@code algorithm}. |
|
172 * |
|
173 * @param algorithm Random number generator algorithm |
|
174 * |
|
175 * @return An instance of {@link RandomGenerator} |
|
176 */ |
|
177 public static RandomGenerator of(Algorithm algorithm) { |
|
178 Objects.requireNonNull(algorithm); |
|
179 return RandomGeneratorFactory.of(algorithm.toString(), RandomGenerator.class); |
|
180 } |
|
181 |
|
182 /** |
|
183 * Returns a {@link RandomGeneratorFactory} that can produce instances |
|
184 * of {@link RandomGenerator} that utilizes the {@code name} algorithm. |
|
185 * |
|
186 * @param name Name of random number generator algorithm |
|
187 * |
|
188 * @return Factory of {@link RandomGenerator} |
|
189 */ |
|
190 public static RandomGeneratorFactory<RandomGenerator> factoryOf(String name) { |
|
191 Objects.requireNonNull(name); |
|
192 return RandomGeneratorFactory.factoryOf(name, RandomGenerator.class); |
|
193 } |
|
194 |
|
195 /** |
|
196 * Returns a {@link RandomGeneratorFactory} that can produce instances |
|
197 * of {@link RandomGenerator} that utilizes the specified {@code algorithm}. |
|
198 * |
|
199 * @param algorithm Random number generator algorithm |
|
200 * |
|
201 * @return Factory of {@link RandomGenerator} |
|
202 */ |
|
203 public static RandomGeneratorFactory<RandomGenerator> factoryOf(Algorithm algorithm) { |
|
204 Objects.requireNonNull(algorithm); |
|
205 return RandomGeneratorFactory.factoryOf(algorithm.toString(), RandomGenerator.class); |
|
206 } |
|
207 |
|
208 /** |
93 * Returns an effectively unlimited stream of pseudorandomly chosen |
209 * Returns an effectively unlimited stream of pseudorandomly chosen |
94 * {@code double} values. |
210 * {@code double} values. |
95 * |
211 * |
96 * @return a stream of pseudorandomly chosen {@code double} values |
212 * @return a stream of pseudorandomly chosen {@code double} values |
97 * |
213 * |
670 * security-sensitive applications. |
786 * security-sensitive applications. |
671 * |
787 * |
672 * @since 14 |
788 * @since 14 |
673 */ |
789 */ |
674 public interface StreamableGenerator extends RandomGenerator { |
790 public interface StreamableGenerator extends RandomGenerator { |
|
791 |
|
792 /** |
|
793 * Returns an instance of {@link StreamableGenerator} that utilizes the |
|
794 * {@code name} algorithm. |
|
795 * |
|
796 * @param name Name of random number generator algorithm |
|
797 * |
|
798 * @return An instance of {@link StreamableGenerator} |
|
799 */ |
|
800 public static StreamableGenerator of(String name) { |
|
801 Objects.requireNonNull(name); |
|
802 return RandomGeneratorFactory.of(name, StreamableGenerator.class); |
|
803 } |
|
804 |
|
805 /** |
|
806 * Returns an instance of {@link StreamableGenerator} that utilizes the |
|
807 * specified {@code algorithm}. |
|
808 * |
|
809 * @param algorithm Random number generator algorithm |
|
810 * |
|
811 * @return An instance of {@link StreamableGenerator} |
|
812 */ |
|
813 public static StreamableGenerator of(Algorithm algorithm) { |
|
814 Objects.requireNonNull(algorithm); |
|
815 return RandomGeneratorFactory.of(algorithm.toString(), StreamableGenerator.class); |
|
816 } |
|
817 |
|
818 /** |
|
819 * Returns a {@link RandomGeneratorFactory} that can produce instances |
|
820 * of {@link StreamableGenerator} that utilizes the {@code name} algorithm. |
|
821 * |
|
822 * @param name Name of random number generator algorithm |
|
823 * |
|
824 * @return Factory of {@link StreamableGenerator} |
|
825 */ |
|
826 public static RandomGeneratorFactory<StreamableGenerator> factoryOf(String name) { |
|
827 Objects.requireNonNull(name); |
|
828 return RandomGeneratorFactory.factoryOf(name, StreamableGenerator.class); |
|
829 } |
|
830 |
|
831 /** |
|
832 * Returns a {@link RandomGeneratorFactory} that can produce instances |
|
833 * of {@link StreamableGenerator} that utilizes the specified {@code algorithm}. |
|
834 * |
|
835 * @param algorithm Random number generator algorithm |
|
836 * |
|
837 * @return Factory of {@link StreamableGenerator} |
|
838 */ |
|
839 public static RandomGeneratorFactory<StreamableGenerator> factoryOf(Algorithm algorithm) { |
|
840 Objects.requireNonNull(algorithm); |
|
841 return RandomGeneratorFactory.factoryOf(algorithm.toString(), StreamableGenerator.class); |
|
842 } |
|
843 |
675 /** |
844 /** |
676 * Returns an effectively unlimited stream of objects, each of |
845 * Returns an effectively unlimited stream of objects, each of |
677 * which implements the {@link RandomGenerator} interface. Ideally the |
846 * which implements the {@link RandomGenerator} interface. Ideally the |
678 * generators in the stream will appear to be statistically |
847 * generators in the stream will appear to be statistically |
679 * independent. The new generators should be of the same kind |
848 * independent. The new generators should be of the same kind |
744 * security-sensitive applications. |
913 * security-sensitive applications. |
745 * |
914 * |
746 * @since 14 |
915 * @since 14 |
747 */ |
916 */ |
748 public interface SplittableGenerator extends StreamableGenerator { |
917 public interface SplittableGenerator extends StreamableGenerator { |
|
918 |
|
919 /** |
|
920 * Returns an instance of {@link SplittableGenerator} that utilizes the |
|
921 * {@code name} algorithm. |
|
922 * |
|
923 * @param name Name of random number generator algorithm |
|
924 * |
|
925 * @return An instance of {@link SplittableGenerator} |
|
926 */ |
|
927 public static SplittableGenerator of(String name) { |
|
928 Objects.requireNonNull(name); |
|
929 return RandomGeneratorFactory.of(name, SplittableGenerator.class); |
|
930 } |
|
931 |
|
932 /** |
|
933 * Returns an instance of {@link SplittableGenerator} that utilizes the |
|
934 * specified {@code algorithm}. |
|
935 * |
|
936 * @param algorithm Random number generator algorithm |
|
937 * |
|
938 * @return An instance of {@link SplittableGenerator} |
|
939 */ |
|
940 public static SplittableGenerator of(Algorithm algorithm) { |
|
941 Objects.requireNonNull(algorithm); |
|
942 return RandomGeneratorFactory.of(algorithm.toString(), SplittableGenerator.class); |
|
943 } |
|
944 |
|
945 /** |
|
946 * Returns a {@link RandomGeneratorFactory} that can produce instances |
|
947 * of {@link SplittableGenerator} that utilizes the {@code name} algorithm. |
|
948 * |
|
949 * @param name Name of random number generator algorithm |
|
950 * |
|
951 * @return Factory of {@link SplittableGenerator} |
|
952 */ |
|
953 public static RandomGeneratorFactory<SplittableGenerator> factoryOf(String name) { |
|
954 Objects.requireNonNull(name); |
|
955 return RandomGeneratorFactory.factoryOf(name, SplittableGenerator.class); |
|
956 } |
|
957 |
|
958 /** |
|
959 * Returns a {@link RandomGeneratorFactory} that can produce instances |
|
960 * of {@link SplittableGenerator} that utilizes the specified {@code algorithm}. |
|
961 * |
|
962 * @param algorithm Random number generator algorithm |
|
963 * |
|
964 * @return Factory of {@link SplittableGenerator} |
|
965 */ |
|
966 public static RandomGeneratorFactory<SplittableGenerator> factoryOf(Algorithm algorithm) { |
|
967 Objects.requireNonNull(algorithm); |
|
968 return RandomGeneratorFactory.factoryOf(algorithm.toString(), SplittableGenerator.class); |
|
969 } |
749 |
970 |
750 /** |
971 /** |
751 * Returns a new pseudorandom number generator, split off from |
972 * Returns a new pseudorandom number generator, split off from |
752 * this one, that implements the {@link RandomGenerator} and {@link SplittableGenerator} |
973 * this one, that implements the {@link RandomGenerator} and {@link SplittableGenerator} |
753 * interfaces. |
974 * interfaces. |
908 * number generator for use by security-sensitive applications. |
1129 * number generator for use by security-sensitive applications. |
909 * |
1130 * |
910 * @since 14 |
1131 * @since 14 |
911 */ |
1132 */ |
912 public interface JumpableGenerator extends StreamableGenerator { |
1133 public interface JumpableGenerator extends StreamableGenerator { |
|
1134 |
|
1135 /** |
|
1136 * Returns an instance of {@link JumpableGenerator} that utilizes the |
|
1137 * {@code name} algorithm. |
|
1138 * |
|
1139 * @param name Name of random number generator algorithm |
|
1140 * |
|
1141 * @return An instance of {@link JumpableGenerator} |
|
1142 */ |
|
1143 public static JumpableGenerator of(String name) { |
|
1144 Objects.requireNonNull(name); |
|
1145 return RandomGeneratorFactory.of(name, JumpableGenerator.class); |
|
1146 } |
|
1147 |
|
1148 /** |
|
1149 * Returns an instance of {@link JumpableGenerator} that utilizes the |
|
1150 * specified {@code algorithm}. |
|
1151 * |
|
1152 * @param algorithm Random number generator algorithm |
|
1153 * |
|
1154 * @return An instance of {@link JumpableGenerator} |
|
1155 */ |
|
1156 public static JumpableGenerator of(Algorithm algorithm) { |
|
1157 Objects.requireNonNull(algorithm); |
|
1158 return RandomGeneratorFactory.of(algorithm.toString(), JumpableGenerator.class); |
|
1159 } |
|
1160 |
|
1161 /** |
|
1162 * Returns a {@link RandomGeneratorFactory} that can produce instances |
|
1163 * of {@link JumpableGenerator} that utilizes the {@code name} algorithm. |
|
1164 * |
|
1165 * @param name Name of random number generator algorithm |
|
1166 * |
|
1167 * @return Factory of {@link JumpableGenerator} |
|
1168 */ |
|
1169 public static RandomGeneratorFactory<JumpableGenerator> factoryOf(String name) { |
|
1170 Objects.requireNonNull(name); |
|
1171 return RandomGeneratorFactory.factoryOf(name, JumpableGenerator.class); |
|
1172 } |
|
1173 |
|
1174 /** |
|
1175 * Returns a {@link RandomGeneratorFactory} that can produce instances |
|
1176 * of {@link JumpableGenerator} that utilizes the specified {@code algorithm}. |
|
1177 * |
|
1178 * @param algorithm Random number generator algorithm |
|
1179 * |
|
1180 * @return Factory of {@link JumpableGenerator} |
|
1181 */ |
|
1182 public static RandomGeneratorFactory<JumpableGenerator> factoryOf(Algorithm algorithm) { |
|
1183 Objects.requireNonNull(algorithm); |
|
1184 return RandomGeneratorFactory.factoryOf(algorithm.toString(), JumpableGenerator.class); |
|
1185 } |
|
1186 |
913 /** |
1187 /** |
914 * Returns a new generator whose internal state is an exact copy of this generator (therefore |
1188 * Returns a new generator whose internal state is an exact copy of this generator (therefore |
915 * their future behavior should be identical if subjected to the same series of operations). |
1189 * their future behavior should be identical if subjected to the same series of operations). |
916 * |
1190 * |
917 * @return a new object that is a copy of this generator |
1191 * @return a new object that is a copy of this generator |
1044 * number generator for use by security-sensitive applications. |
1318 * number generator for use by security-sensitive applications. |
1045 * |
1319 * |
1046 * @since 14 |
1320 * @since 14 |
1047 */ |
1321 */ |
1048 public interface LeapableGenerator extends JumpableGenerator { |
1322 public interface LeapableGenerator extends JumpableGenerator { |
|
1323 |
|
1324 /** |
|
1325 * Returns an instance of {@link LeapableGenerator} that utilizes the |
|
1326 * {@code name} algorithm. |
|
1327 * |
|
1328 * @param name Name of random number generator algorithm |
|
1329 * |
|
1330 * @return An instance of {@link LeapableGenerator} |
|
1331 */ |
|
1332 public static LeapableGenerator of(String name) { |
|
1333 Objects.requireNonNull(name); |
|
1334 return RandomGeneratorFactory.of(name, LeapableGenerator.class); |
|
1335 } |
|
1336 |
|
1337 /** |
|
1338 * Returns an instance of {@link LeapableGenerator} that utilizes the |
|
1339 * specified {@code algorithm}. |
|
1340 * |
|
1341 * @param algorithm Random number generator algorithm |
|
1342 * |
|
1343 * @return An instance of {@link LeapableGenerator} |
|
1344 */ |
|
1345 public static LeapableGenerator of(Algorithm algorithm) { |
|
1346 Objects.requireNonNull(algorithm); |
|
1347 return RandomGeneratorFactory.of(algorithm.toString(), LeapableGenerator.class); |
|
1348 } |
|
1349 |
|
1350 /** |
|
1351 * Returns a {@link RandomGeneratorFactory} that can produce instances |
|
1352 * of {@link LeapableGenerator} that utilizes the {@code name} algorithm. |
|
1353 * |
|
1354 * @param name Name of random number generator algorithm |
|
1355 * |
|
1356 * @return Factory of {@link LeapableGenerator} |
|
1357 */ |
|
1358 public static RandomGeneratorFactory<LeapableGenerator> factoryOf(String name) { |
|
1359 Objects.requireNonNull(name); |
|
1360 return RandomGeneratorFactory.factoryOf(name, LeapableGenerator.class); |
|
1361 } |
|
1362 |
|
1363 /** |
|
1364 * Returns a {@link RandomGeneratorFactory} that can produce instances |
|
1365 * of {@link LeapableGenerator} that utilizes the specified {@code algorithm}. |
|
1366 * |
|
1367 * @param algorithm Random number generator algorithm |
|
1368 * |
|
1369 * @return Factory of {@link LeapableGenerator} |
|
1370 */ |
|
1371 public static RandomGeneratorFactory<LeapableGenerator> factoryOf(Algorithm algorithm) { |
|
1372 Objects.requireNonNull(algorithm); |
|
1373 return RandomGeneratorFactory.factoryOf(algorithm.toString(), LeapableGenerator.class); |
|
1374 } |
|
1375 |
1049 /** |
1376 /** |
1050 * Returns a new generator whose internal state is an exact copy of this generator (therefore |
1377 * Returns a new generator whose internal state is an exact copy of this generator (therefore |
1051 * their future behavior should be identical if subjected to the same series of operations). |
1378 * their future behavior should be identical if subjected to the same series of operations). |
1052 * |
1379 * |
1053 * @return a new object that is a copy of this generator |
1380 * @return a new object that is a copy of this generator |
1153 * pseudo-random number generator for use by security-sensitive applications. |
1480 * pseudo-random number generator for use by security-sensitive applications. |
1154 * |
1481 * |
1155 * @since 14 |
1482 * @since 14 |
1156 */ |
1483 */ |
1157 public interface ArbitrarilyJumpableGenerator extends LeapableGenerator { |
1484 public interface ArbitrarilyJumpableGenerator extends LeapableGenerator { |
|
1485 |
|
1486 /** |
|
1487 * Returns an instance of {@link ArbitrarilyJumpableGenerator} that utilizes the |
|
1488 * {@code name} algorithm. |
|
1489 * |
|
1490 * @param name Name of random number generator algorithm |
|
1491 * |
|
1492 * @return An instance of {@link ArbitrarilyJumpableGenerator} |
|
1493 */ |
|
1494 public static ArbitrarilyJumpableGenerator of(String name) { |
|
1495 Objects.requireNonNull(name); |
|
1496 return RandomGeneratorFactory.of(name, ArbitrarilyJumpableGenerator.class); |
|
1497 } |
|
1498 |
|
1499 /** |
|
1500 * Returns an instance of {@link ArbitrarilyJumpableGenerator} that utilizes the |
|
1501 * specified {@code algorithm}. |
|
1502 * |
|
1503 * @param algorithm Random number generator algorithm |
|
1504 * |
|
1505 * @return An instance of {@link ArbitrarilyJumpableGenerator} |
|
1506 */ |
|
1507 public static ArbitrarilyJumpableGenerator of(Algorithm algorithm) { |
|
1508 Objects.requireNonNull(algorithm); |
|
1509 return RandomGeneratorFactory.of(algorithm.toString(), ArbitrarilyJumpableGenerator.class); |
|
1510 } |
|
1511 |
|
1512 /** |
|
1513 * Returns a {@link RandomGeneratorFactory} that can produce instances |
|
1514 * of {@link ArbitrarilyJumpableGenerator} that utilizes the {@code name} algorithm. |
|
1515 * |
|
1516 * @param name Name of random number generator algorithm |
|
1517 * |
|
1518 * @return Factory of {@link ArbitrarilyJumpableGenerator} |
|
1519 */ |
|
1520 public static RandomGeneratorFactory<ArbitrarilyJumpableGenerator> factoryOf(String name) { |
|
1521 Objects.requireNonNull(name); |
|
1522 return RandomGeneratorFactory.factoryOf(name, ArbitrarilyJumpableGenerator.class); |
|
1523 } |
|
1524 |
|
1525 /** |
|
1526 * Returns a {@link RandomGeneratorFactory} that can produce instances |
|
1527 * of {@link ArbitrarilyJumpableGenerator} that utilizes the specified {@code algorithm}. |
|
1528 * |
|
1529 * @param algorithm Random number generator algorithm |
|
1530 * |
|
1531 * @return Factory of {@link ArbitrarilyJumpableGenerator} |
|
1532 */ |
|
1533 public static RandomGeneratorFactory<ArbitrarilyJumpableGenerator> factoryOf(Algorithm algorithm) { |
|
1534 Objects.requireNonNull(algorithm); |
|
1535 return RandomGeneratorFactory.factoryOf(algorithm.toString(), ArbitrarilyJumpableGenerator.class); |
|
1536 } |
|
1537 |
1158 /** |
1538 /** |
1159 * Returns a new generator whose internal state is an exact copy of this generator (therefore |
1539 * Returns a new generator whose internal state is an exact copy of this generator (therefore |
1160 * their future behavior should be identical if subjected to the same series of operations). |
1540 * their future behavior should be identical if subjected to the same series of operations). |
1161 * |
1541 * |
1162 * @return a new object that is a copy of this generator |
1542 * @return a new object that is a copy of this generator |