Repository: commons-text Updated Branches: refs/heads/master 66cf58776 -> 1f5171efc
TEXT-36: RandomStringGenerator: allow users to provide source of randomness (closes #25) Create functional interface to provide randomness for RandomStringGenerator Project: http://git-wip-us.apache.org/repos/asf/commons-text/repo Commit: http://git-wip-us.apache.org/repos/asf/commons-text/commit/8d14206b Tree: http://git-wip-us.apache.org/repos/asf/commons-text/tree/8d14206b Diff: http://git-wip-us.apache.org/repos/asf/commons-text/diff/8d14206b Branch: refs/heads/master Commit: 8d14206b94631e5c78a51e1a319c7e7ad06e890a Parents: edb0676 Author: Ray DeCampo <r...@decampo.org> Authored: Fri Jan 6 06:52:15 2017 -0500 Committer: Pascal Schumacher <pascalschumac...@gmx.net> Committed: Fri Apr 28 16:25:34 2017 +0200 ---------------------------------------------------------------------- .../commons/text/RandomStringGenerator.java | 37 +++++++++++--- .../apache/commons/text/TextRandomProvider.java | 51 ++++++++++++++++++++ .../commons/text/RandomStringGeneratorTest.java | 8 ++- 3 files changed, 83 insertions(+), 13 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/commons-text/blob/8d14206b/src/main/java/org/apache/commons/text/RandomStringGenerator.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/text/RandomStringGenerator.java b/src/main/java/org/apache/commons/text/RandomStringGenerator.java index c4411a2..7eb45d9 100644 --- a/src/main/java/org/apache/commons/text/RandomStringGenerator.java +++ b/src/main/java/org/apache/commons/text/RandomStringGenerator.java @@ -17,7 +17,6 @@ package org.apache.commons.text; import java.util.HashSet; -import java.util.Random; import java.util.Set; import java.util.concurrent.ThreadLocalRandom; @@ -30,8 +29,13 @@ import java.util.concurrent.ThreadLocalRandom; * </p> * * <pre> + * // Using Apache Commons RNG for randomness + * UniformRandomProvider rng = RandomSource.create(...); * // Generates a 20 code point string, using only the letters a-z - * RandomStringGenerator generator = new RandomStringGenerator.Builder().withinRange('a', 'z').build(); + * RandomStringGenerator generator = new RandomStringGenerator.Builder() + * .withinRange('a', 'z') + * .usingRandom(rng::nextInt) // uses Java 8 syntax + * .build(); * String random = generator.generate(20); * </pre> * @@ -46,7 +50,7 @@ public final class RandomStringGenerator { private final int minimumCodePoint; private final int maximumCodePoint; private final Set<CharacterPredicate> inclusivePredicates; - private final Random random; + private final TextRandomProvider random; /** @@ -62,7 +66,7 @@ public final class RandomStringGenerator { * source of randomness */ private RandomStringGenerator(int minimumCodePoint, int maximumCodePoint, - Set<CharacterPredicate> inclusivePredicates, Random random) { + Set<CharacterPredicate> inclusivePredicates, TextRandomProvider random) { this.minimumCodePoint = minimumCodePoint; this.maximumCodePoint = maximumCodePoint; this.inclusivePredicates = inclusivePredicates; @@ -168,7 +172,7 @@ public final class RandomStringGenerator { * <p>The minimum and maximum code point values are defined using {@link #withinRange(int, int)}. The * default values are {@code 0} and {@link Character#MAX_CODE_POINT} respectively.</p> * - * <p>The source of randomness can be set using {@link #usingRandom(Random)}, otherwise {@link ThreadLocalRandom} + * <p>The source of randomness can be set using {@link #usingRandom(TextRandomProvider) }, otherwise {@link ThreadLocalRandom} * is used.</p> * * <p>The type of code points returned can be filtered using {@link #filteredBy(CharacterPredicate...)}, @@ -207,7 +211,7 @@ public final class RandomStringGenerator { private int minimumCodePoint = DEFAULT_MINIMUM_CODE_POINT; private int maximumCodePoint = DEFAULT_MAXIMUM_CODE_POINT; private Set<CharacterPredicate> inclusivePredicates; - private Random random; + private TextRandomProvider random; /** @@ -286,8 +290,25 @@ public final class RandomStringGenerator { /** * <p> - * Overrides the default source of randomness. + * Overrides the default source of randomness. It is highly + * recommended that a random number generator library like + * <a href="http://commons.apache.org/proper/commons-rng/";>Apache Commons RNG</a> + * be used to provide the random number generation. * </p> + * + * <p> + * When using Java 8 or later, {@link TextRandomProvider} is a + * functional interface and need not be explicitly implemented: + * </p> + * <pre> + * {@code + * UniformRandomProvider rng = RandomSource.create(...); + * RandomStringGenerator gen = new RandomStringGenerator.Builder() + * .usingRandom(rng::nextInt) + * // additional builder calls as needed + * .build(); + * } + * </pre> * * <p> * Passing {@code null} to this method will revert to the default source of @@ -299,7 +320,7 @@ public final class RandomStringGenerator { * @return {@code this}, to allow method chaining * @since 1.0 */ - public Builder usingRandom(final Random random) { + public Builder usingRandom(final TextRandomProvider random) { this.random = random; return this; } http://git-wip-us.apache.org/repos/asf/commons-text/blob/8d14206b/src/main/java/org/apache/commons/text/TextRandomProvider.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/text/TextRandomProvider.java b/src/main/java/org/apache/commons/text/TextRandomProvider.java new file mode 100644 index 0000000..4aecd72 --- /dev/null +++ b/src/main/java/org/apache/commons/text/TextRandomProvider.java @@ -0,0 +1,51 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.apache.commons.text; + +/** + * <p> + * TextRandomProvider implementations are used by {@link RandomStringGenerator} + * as a source of randomness. It is highly recommended that the + * <a href="http://commons.apache.org/proper/commons-rng/";>Apache Commons RNG</a> + * library be used to provide the random number generation. + * </p> + * + * <p> + * When using Java 8 or later, TextRandomProvider is a functional interface and + * need not be explicitly implemented. For example: + * </p> + * <pre> + * {@code + * UniformRandomProvider rng = RandomSource.create(...); + * RandomStringGenerator gen = new RandomStringGenerator.Builder() + * .usingRandom(rng::nextInt) + * // additional builder calls as needed + * .build(); + * } + * </pre> + */ +public interface TextRandomProvider { + + /** + * Generates an int value between 0 (inclusive) and the specified value + * (exclusive). + * @param max Bound on the random number to be returned. Must be positive. + * @return a random int value between 0 (inclusive) and n (exclusive). + * @throws IllegalArgumentException - if max is negative + */ + int nextInt(int max); +} http://git-wip-us.apache.org/repos/asf/commons-text/blob/8d14206b/src/test/java/org/apache/commons/text/RandomStringGeneratorTest.java ---------------------------------------------------------------------- diff --git a/src/test/java/org/apache/commons/text/RandomStringGeneratorTest.java b/src/test/java/org/apache/commons/text/RandomStringGeneratorTest.java index 36ce5e0..0da2072 100644 --- a/src/test/java/org/apache/commons/text/RandomStringGeneratorTest.java +++ b/src/test/java/org/apache/commons/text/RandomStringGeneratorTest.java @@ -16,12 +16,10 @@ */ package org.apache.commons.text; -import static org.junit.Assert.*; - -import java.util.Random; - import org.junit.Test; +import static org.junit.Assert.*; + /** * Tests for {@link RandomStringGenerator} */ @@ -115,7 +113,7 @@ public class RandomStringGeneratorTest { @Test public void testUsingRandom() throws Exception { final char testChar = 'a'; - final Random testRandom = new Random() { + final TextRandomProvider testRandom = new TextRandomProvider() { private static final long serialVersionUID = 1L; @Override
