commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From pascalschumac...@apache.org
Subject [1/4] [text] TEXT-36: RandomStringGenerator: allow users to provide source of randomness (closes #25)
Date Fri, 28 Apr 2017 14:27:14 GMT
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 <ray@decampo.org>
Authored: Fri Jan 6 06:52:15 2017 -0500
Committer: Pascal Schumacher <pascalschumacher@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


Mime
View raw message