Userguide.
Project: http://git-wip-us.apache.org/repos/asf/commons-rng/repo Commit: http://git-wip-us.apache.org/repos/asf/commons-rng/commit/6b8bbc0a Tree: http://git-wip-us.apache.org/repos/asf/commons-rng/tree/6b8bbc0a Diff: http://git-wip-us.apache.org/repos/asf/commons-rng/diff/6b8bbc0a Branch: refs/heads/master Commit: 6b8bbc0a2ac8c40c570619e820d589c78021cfad Parents: 5cd88b1 Author: Gilles <er...@apache.org> Authored: Mon Nov 21 14:56:09 2016 +0100 Committer: Gilles <er...@apache.org> Committed: Mon Nov 21 14:56:09 2016 +0100 ---------------------------------------------------------------------- src/site/apt/userguide/rng.apt | 21 +++-- src/site/apt/userguide/why_not_java_random.apt | 96 ++++++++++++--------- src/site/xdoc/userguide/index.xml | 12 +-- 3 files changed, 74 insertions(+), 55 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/commons-rng/blob/6b8bbc0a/src/site/apt/userguide/rng.apt ---------------------------------------------------------------------- diff --git a/src/site/apt/userguide/rng.apt b/src/site/apt/userguide/rng.apt index eb88e05..201e691 100644 --- a/src/site/apt/userguide/rng.apt +++ b/src/site/apt/userguide/rng.apt @@ -29,8 +29,10 @@ The goal was to provide an API that is simple and unencumbered with old design decisions. - The design is clean and its rationale is explained extensively in the code - and Javadoc. + The design is clean and its rationale is explained in the code and Javadoc + (as well as in the extensive discussions on the "Apache Commons" project's + mailing list). + The code evolved during several months in order to accommodate the requirements gathered from the design issues identified in the <<<org.apache.commons.math3.random>>> package and the explicit design @@ -252,7 +254,8 @@ rngNew.restoreState(stateNew); +--------------------------+ - * Generation of random deviates for various distributions. + * Generation of random deviates for various + {{{../commons-rng-sampling/apidocs/org/apache/commons/rng/sampling/distribution/package-summary.html}distributions}}. +--------------------------+ import org.apache.commons.rng.sampling.distribution.ContinuousSampler; @@ -272,7 +275,9 @@ DiscreteSampler sampler = new RejectionInversionZipfSampler(RandomSource.create( int random = sampler.sample(); +--------------------------+ - * Permutation, sampling from a <<<Collection>>> and shuffling utilities. + * {{{../commons-rng-sampling/apidocs/org/apache/commons/rng/sampling/PermutationSampler.html}Permutation}}, + {{{../commons-rng-sampling/apidocs/org/apache/commons/rng/sampling/CollectionSampler.html}sampling from a <<<Collection>>>}} + and shuffling utilities. +--------------------------+ import org.apache.commons.rng.sampling.PermutationSampler; @@ -288,13 +293,13 @@ int[] random = sampler.sample(); import java.util.ArrayList; import org.apache.commons.rng.sampling.CollectionSampler; -ArrayList<String> list = new ArrayList<>(); -list.add("Apache") +ArrayList<String> list = new ArrayList<String>(); +list.add("Apache"); list.add("Commons"); list.add("RNG"); -CollectionSampler sampler = new CollectionSampler(RandomSource.create(RandomSource.MWC_256), - list, 1); +CollectionSampler<String> sampler = new CollectionSampler<String>(RandomSource.create(RandomSource.MWC_256), + list, 1); String word = sampler.sample().get(0); +--------------------------+ http://git-wip-us.apache.org/repos/asf/commons-rng/blob/6b8bbc0a/src/site/apt/userguide/why_not_java_random.apt ---------------------------------------------------------------------- diff --git a/src/site/apt/userguide/why_not_java_random.apt b/src/site/apt/userguide/why_not_java_random.apt index 5f2b190..5e82e34 100644 --- a/src/site/apt/userguide/why_not_java_random.apt +++ b/src/site/apt/userguide/why_not_java_random.apt @@ -19,68 +19,82 @@ Why not <<<java.util.Random>>> ? ----------------------------- -The "Apache Commons RNG" project started off from code originally in the -"Apache Commons Math" project; there, the code in package -{{{http://commons.apache.org/proper/commons-math/javadocs/api-3.6.1/org/apache/commons/math3/random/package-summary.html}org.apache.commons.math3.random}} -had its design prominently based on the JDK's -{{{https://docs.oracle.com/javase/7/docs/api/java/util/Random.html}Random}} -class. + The "Apache Commons RNG" project started off from code originally in the + "Apache Commons Math" project; there, the code in package + {{{http://commons.apache.org/proper/commons-math/javadocs/api-3.6.1/org/apache/commons/math3/random/package-summary.html}org.apache.commons.math3.random}} + had its design prominently based on the JDK's + {{{https://docs.oracle.com/javase/7/docs/api/java/util/Random.html}Random}} + class. -Although it is often a good idea to rely on the language's standard library, -sometimes it is not. -And, in this case, there are numerous reasons for avoiding <<<java.util.Random>>>. + Although it is often a good idea to rely on the language's standard library, + sometimes it is not. -1. The {{{https://en.wikipedia.org/wiki/Linear_congruential_generator}LCG}} - algorithm used by <<<java.util.Random>>> + * The {{{https://en.wikipedia.org/wiki/Linear_congruential_generator}LCG}} + algorithm used by <<<java.util.Random>>> - * has a serious {{{http://www.ics.uci.edu/~fowlkes/class/cs177/marsaglia.pdf}defect}}, and + ** has a serious {{{http://www.ics.uci.edu/~fowlkes/class/cs177/marsaglia.pdf}defect}}, and - * is not as efficient as some of the alternatives that do not suffer from this problem. + ** is not as efficient as some of the alternatives that do not suffer from this problem. - [] + [] -2. Although the {{{https://docs.oracle.com/javase/7/docs/api/java/util/Random.html#next(int)}next}} - method seems to imply that it is designed for inheritance, it is not quite so: + * Although the {{{https://docs.oracle.com/javase/7/docs/api/java/util/Random.html#next(int)}next}} + method seems to imply that it is designed for inheritance, it is not quite so: - * {{{https://docs.oracle.com/javase/7/docs/api/java/util/Random.html#setSeed(long)}setSeed}} - is tied to the assumption that the state of the generator is entirely - defined by a single <<<long>>> value. + ** {{{https://docs.oracle.com/javase/7/docs/api/java/util/Random.html#setSeed(long)}setSeed}} + is tied to the assumption that the state of the generator is entirely + defined by a single <<<long>>> value. - * {{{https://docs.oracle.com/javase/7/docs/api/java/util/Random.html#next(int)}next}} - implies that an implementation must produce a 32-bits value. + ** {{{https://docs.oracle.com/javase/7/docs/api/java/util/Random.html#next(int)}next}} + implies that an implementation must produce a 32-bits value. - * <<<Random>>> is {{{http://docs.oracle.com/javase/7/docs/api/java/io/Serializable.html}Serializable}} - and thus imposes it on subclasses even though the issue of persistent - storage is application-dependent. + ** <<<Random>>> is {{{http://docs.oracle.com/javase/7/docs/api/java/io/Serializable.html}Serializable}} + and thus imposes it on subclasses even though the issue of persistent + storage is application-dependent. - [] + [] As a side note, the newer {{{https://docs.oracle.com/javase/8/docs/api/java/util/SplittableRandom.html}SplittableRandom}} - * is <<<final>>> (hence, there is no temptation to mistake it as an interface), and + ** is <<<final>>> (hence, there is no temptation to mistake it as an interface), and - * does not inherit from <<<Random>>> (which is a clear hint that the - JDK's developers themselves do not consider <<<Random>>> as the - best option for new code). + ** does not inherit from <<<Random>>> (which is a clear hint that the + JDK's developers themselves do not consider <<<Random>>> as the + best option for new code). - [] + [] -3. Thus, <<<java.util.Random>>> _should_ have been an implementation of a - more general interface (without a <<<setSeed>>> method that is bound to - be implementation-specific, or a {{{https://docs.oracle.com/javase/7/docs/api/java/util/Random.html#nextGaussian()}nextGaussian}} - that singles out just one of many types of random deviates). + * Thus, <<<java.util.Random>>> _should_ have been an implementation of a + more general interface (without a <<<setSeed>>> method that is bound to + be implementation-specific, or a {{{https://docs.oracle.com/javase/7/docs/api/java/util/Random.html#nextGaussian()}nextGaussian}} + that singles out just one of many types of random deviates). -4. As a concrete class, <<<java.util.Random>>> contains code tied to - "implementation details"; it is hard to modify it without changing - long-established behaviour, even if it would be to fix a - {{{https://bugs.openjdk.java.net/browse/JDK-8154225}bug}}. + * As a concrete class, <<<java.util.Random>>> contains code tied to + "implementation details"; it is hard to modify it without changing + long-established behaviour, even if it would be to fix a + {{{https://bugs.openjdk.java.net/browse/JDK-8154225}bug}}. -5. Methods are <<<synchronized>>>, incurring an unnecessary performance - impact for single-threaded applications, while multi-threaded ones will - be subject to contention. + * Methods are <<<synchronized>>>, incurring an unnecessary performance + impact for single-threaded applications, while multi-threaded ones will + be subject to contention. + + [] + + + Unless unfazed by the above, it is clear that application developers should + avoid <<<java.util.Random>>>, as a generator, and as a base class. + + For new applications, it is recommended to switch to any of the better + alternatives provided in "Commons RNG". + + For legacy applications where the <<<java.util.Random>>> type is part of + an API that cannot be changed, developers can wrap any of the generators + implemented in this library within an instance of the + {{{../commons-rng-simple/apidocs/org/apache/commons/rng/simple/JDKRandomBridge.html}JDKRandomBridge}} + adapter class. http://git-wip-us.apache.org/repos/asf/commons-rng/blob/6b8bbc0a/src/site/xdoc/userguide/index.xml ---------------------------------------------------------------------- diff --git a/src/site/xdoc/userguide/index.xml b/src/site/xdoc/userguide/index.xml index 027abbb..ef0f9be 100644 --- a/src/site/xdoc/userguide/index.xml +++ b/src/site/xdoc/userguide/index.xml @@ -30,27 +30,27 @@ <li> <a href="rng.html#a1._Purpose"> - 1. Usage overview (for users)</a> + 1. Purpose of the library</a> </li> <li> <a href="rng.html#a2._Usage_overview"> - 1. Usage overview (for users)</a> + 2. Usage overview (for users)</a> </li> <li> <a href="rng.html#a3._Library_layout"> - 2. Library layout (for developers)</a> + 3. Library layout (for developers)</a> </li> <li> <a href="rng.html#a4._Performance"> - 3. Performance</a> + 4. Performance</a> </li> <li> <a href="rng.html#a5._Quality"> - 4. Quality</a> + 5. Quality</a> </li> <li> <a href="rng.html#a6._Dependencies"> - 5. Dependencies</a> + 6. Dependencies</a> </li> </ul>
