View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.commons.text;
18  
19  import java.util.ArrayList;
20  import java.util.Collections;
21  import java.util.HashSet;
22  import java.util.List;
23  import java.util.Set;
24  import java.util.concurrent.ThreadLocalRandom;
25  
26  import org.apache.commons.lang3.ArrayUtils;
27  import org.apache.commons.lang3.StringUtils;
28  import org.apache.commons.lang3.Validate;
29  
30  /**
31   * Generates random Unicode strings containing the specified number of code points.
32   * Instances are created using a builder class, which allows the
33   * callers to define the properties of the generator. See the documentation for the
34   * {@link Builder} class to see available properties.
35   *
36   * <pre>
37   * // Generates a 20 code point string, using only the letters a-z
38   * RandomStringGenerator generator = RandomStringGenerator.builder()
39   *     .withinRange('a', 'z').build();
40   * String randomLetters = generator.generate(20);
41   * </pre>
42   * <pre>
43   * // Using Apache Commons RNG for randomness
44   * UniformRandomProvider rng = RandomSource.create(...);
45   * // Generates a 20 code point string, using only the letters a-z
46   * RandomStringGenerator generator = RandomStringGenerator.builder()
47   *     .withinRange('a', 'z')
48   *     .usingRandom(rng::nextInt) // uses Java 8 syntax
49   *     .build();
50   * String randomLetters = generator.generate(20);
51   * </pre>
52   * <p>
53   * {@code RandomStringGenerator} instances are thread-safe when using the
54   * default random number generator (RNG). If a custom RNG is set by calling the method
55   * {@link Builder#usingRandom(TextRandomProvider) Builder.usingRandom(TextRandomProvider)}, thread-safety
56   * must be ensured externally.
57   * </p>
58   * @since 1.1
59   */
60  public final class RandomStringGenerator {
61  
62      /**
63       * A builder for generating {@code RandomStringGenerator} instances.
64       *
65       * <p>The behavior of a generator is controlled by properties set by this
66       * builder. Each property has a default value, which can be overridden by
67       * calling the methods defined in this class, prior to calling {@link #build()}.</p>
68       *
69       * <p>All the property setting methods return the {@code Builder} instance to allow for method chaining.</p>
70       *
71       * <p>The minimum and maximum code point values are defined using {@link #withinRange(int, int)}. The
72       * default values are {@code 0} and {@link Character#MAX_CODE_POINT} respectively.</p>
73       *
74       * <p>The source of randomness can be set using {@link #usingRandom(TextRandomProvider)},
75       * otherwise {@link ThreadLocalRandom} is used.</p>
76       *
77       * <p>The type of code points returned can be filtered using {@link #filteredBy(CharacterPredicate...)},
78       * which defines a collection of tests that are applied to the randomly generated code points.
79       * The code points will only be included in the result if they pass at least one of the tests.
80       * Some commonly used predicates are provided by the {@link CharacterPredicates} enum.</p>
81       *
82       * <p>This class is not thread safe.</p>
83       * @since 1.1
84       */
85      public static class Builder implements org.apache.commons.text.Builder<RandomStringGenerator> {
86  
87          /**
88           * The default maximum code point allowed: {@link Character#MAX_CODE_POINT}
89           * ({@value}).
90           */
91          public static final int DEFAULT_MAXIMUM_CODE_POINT = Character.MAX_CODE_POINT;
92  
93          /**
94           * The default string length produced by this builder: {@value}.
95           */
96          public static final int DEFAULT_LENGTH = 0;
97  
98          /**
99           * The default minimum code point allowed: {@value}.
100          */
101         public static final int DEFAULT_MINIMUM_CODE_POINT = 0;
102 
103         /**
104          * The minimum code point allowed.
105          */
106         private int minimumCodePoint = DEFAULT_MINIMUM_CODE_POINT;
107 
108         /**
109          * The maximum code point allowed.
110          */
111         private int maximumCodePoint = DEFAULT_MAXIMUM_CODE_POINT;
112 
113         /**
114          * Filters for code points.
115          */
116         private Set<CharacterPredicate> inclusivePredicates;
117 
118         /**
119          * The source of randomness.
120          */
121         private TextRandomProvider random;
122 
123         /**
124          * The source of provided characters.
125          */
126         private List<Character> characterList;
127 
128         /**
129          * Builds a new {@code RandomStringGenerator}.
130          *
131          * @return A new {@code RandomStringGenerator}
132          * @deprecated Use {@link #get()}.
133          */
134         @Deprecated
135         @Override
136         public RandomStringGenerator build() {
137             return get();
138         }
139 
140         /**
141          * Limits the characters in the generated string to those that match at
142          * least one of the predicates supplied.
143          *
144          * <p>
145          * Passing {@code null} or an empty array to this method will revert to the
146          * default behavior of allowing any character. Multiple calls to this
147          * method will replace the previously stored predicates.
148          * </p>
149          *
150          * @param predicates
151          *            the predicates, may be {@code null} or empty
152          * @return {@code this}, to allow method chaining
153          */
154         public Builder filteredBy(final CharacterPredicate... predicates) {
155             if (ArrayUtils.isEmpty(predicates)) {
156                 inclusivePredicates = null;
157                 return this;
158             }
159             if (inclusivePredicates == null) {
160                 inclusivePredicates = new HashSet<>();
161             } else {
162                 inclusivePredicates.clear();
163             }
164             Collections.addAll(inclusivePredicates, predicates);
165             return this;
166         }
167 
168         /**
169          * Builds a new {@code RandomStringGenerator}.
170          *
171          * @return A new {@code RandomStringGenerator}
172          * @since 1.12.0
173          */
174         @Override
175         public RandomStringGenerator get() {
176             return new RandomStringGenerator(minimumCodePoint, maximumCodePoint, inclusivePredicates,
177                     random, characterList);
178         }
179 
180         /**
181          * Limits the characters in the generated string to those who match at
182          * supplied list of Character.
183          *
184          * <p>
185          * Passing {@code null} or an empty array to this method will revert to the
186          * default behavior of allowing any character. Multiple calls to this
187          * method will replace the previously stored Character.
188          * </p>
189          *
190          * @param chars set of predefined Characters for random string generation
191          *            the Character can be, may be {@code null} or empty
192          * @return {@code this}, to allow method chaining
193          * @since 1.2
194          */
195         public Builder selectFrom(final char... chars) {
196             characterList = new ArrayList<>();
197             if (chars != null) {
198                 for (final char c : chars) {
199                     characterList.add(c);
200                 }
201             }
202             return this;
203         }
204 
205         /**
206          * Overrides the default source of randomness.  It is highly
207          * recommended that a random number generator library like
208          * <a href="https://commons.apache.org/proper/commons-rng/">Apache Commons RNG</a>
209          * be used to provide the random number generation.
210          *
211          * <p>
212          * When using Java 8 or later, {@link TextRandomProvider} is a
213          * functional interface and need not be explicitly implemented:
214          * </p>
215          * <pre>
216          * {@code
217          *     UniformRandomProvider rng = RandomSource.create(...);
218          *     RandomStringGenerator gen = RandomStringGenerator.builder()
219          *         .usingRandom(rng::nextInt)
220          *         // additional builder calls as needed
221          *         .build();
222          * }
223          * </pre>
224          *
225          * <p>
226          * Passing {@code null} to this method will revert to the default source of
227          * randomness.
228          * </p>
229          *
230          * @param random
231          *            the source of randomness, may be {@code null}
232          * @return {@code this}, to allow method chaining
233          */
234         public Builder usingRandom(final TextRandomProvider random) {
235             this.random = random;
236             return this;
237         }
238 
239         /**
240          * Sets the array of minimum and maximum char allowed in the
241          * generated string.
242          *
243          * For example:
244          * <pre>
245          * {@code
246          *     char [][] pairs = {{'0','9'}};
247          *     char [][] pairs = {{'a','z'}};
248          *     char [][] pairs = {{'a','z'},{'0','9'}};
249          * }
250          * </pre>
251          *
252          * @param pairs array of characters array, expected is to pass min, max pairs through this arg.
253          * @return {@code this}, to allow method chaining.
254          */
255         public Builder withinRange(final char[]... pairs) {
256             characterList = new ArrayList<>();
257             if (pairs != null) {
258                 for (final char[] pair : pairs) {
259                     Validate.isTrue(pair.length == 2, "Each pair must contain minimum and maximum code point");
260                     final int minimumCodePoint = pair[0];
261                     final int maximumCodePoint = pair[1];
262                     Validate.isTrue(minimumCodePoint <= maximumCodePoint, "Minimum code point %d is larger than maximum code point %d", minimumCodePoint,
263                             maximumCodePoint);
264 
265                     for (int index = minimumCodePoint; index <= maximumCodePoint; index++) {
266                         characterList.add((char) index);
267                     }
268                 }
269             }
270             return this;
271 
272         }
273 
274         /**
275          * Sets the minimum and maximum code points allowed in the
276          * generated string.
277          *
278          * @param minimumCodePoint
279          *            the smallest code point allowed (inclusive)
280          * @param maximumCodePoint
281          *            the largest code point allowed (inclusive)
282          * @return {@code this}, to allow method chaining
283          * @throws IllegalArgumentException
284          *             if {@code maximumCodePoint >}
285          *             {@link Character#MAX_CODE_POINT}
286          * @throws IllegalArgumentException
287          *             if {@code minimumCodePoint < 0}
288          * @throws IllegalArgumentException
289          *             if {@code minimumCodePoint > maximumCodePoint}
290          */
291         public Builder withinRange(final int minimumCodePoint, final int maximumCodePoint) {
292             Validate.isTrue(minimumCodePoint <= maximumCodePoint,
293                     "Minimum code point %d is larger than maximum code point %d", minimumCodePoint, maximumCodePoint);
294             Validate.isTrue(minimumCodePoint >= 0, "Minimum code point %d is negative", minimumCodePoint);
295             Validate.isTrue(maximumCodePoint <= Character.MAX_CODE_POINT,
296                     "Value %d is larger than Character.MAX_CODE_POINT.", maximumCodePoint);
297             this.minimumCodePoint = minimumCodePoint;
298             this.maximumCodePoint = maximumCodePoint;
299             return this;
300         }
301     }
302 
303     /**
304      * Constructs a new builder.
305      * @return a new builder.
306      * @since 1.11.0
307      */
308     public static Builder builder() {
309         return new Builder();
310     }
311 
312     /**
313      * The smallest allowed code point (inclusive).
314      */
315     private final int minimumCodePoint;
316 
317     /**
318      * The largest allowed code point (inclusive).
319      */
320     private final int maximumCodePoint;
321 
322     /**
323      * Filters for code points.
324      */
325     private final Set<CharacterPredicate> inclusivePredicates;
326 
327     /**
328      * The source of randomness for this generator.
329      */
330     private final TextRandomProvider random;
331 
332     /**
333      * The source of provided characters.
334      */
335     private final List<Character> characterList;
336 
337     /**
338      * Constructs the generator.
339      *
340      * @param minimumCodePoint
341      *            smallest allowed code point (inclusive)
342      * @param maximumCodePoint
343      *            largest allowed code point (inclusive)
344      * @param inclusivePredicates
345      *            filters for code points
346      * @param random
347      *            source of randomness
348      * @param characterList list of predefined set of characters.
349      */
350     private RandomStringGenerator(final int minimumCodePoint, final int maximumCodePoint,
351                                   final Set<CharacterPredicate> inclusivePredicates, final TextRandomProvider random,
352                                   final List<Character> characterList) {
353         this.minimumCodePoint = minimumCodePoint;
354         this.maximumCodePoint = maximumCodePoint;
355         this.inclusivePredicates = inclusivePredicates;
356         this.random = random;
357         this.characterList = characterList;
358     }
359 
360     /**
361      * Generates a random string, containing the specified number of code points.
362      *
363      * <p>
364      * Code points are randomly selected between the minimum and maximum values defined
365      * in the generator.
366      * Surrogate and private use characters are not returned, although the
367      * resulting string may contain pairs of surrogates that together encode a
368      * supplementary character.
369      * </p>
370      * <p>
371      * Note: the number of {@code char} code units generated will exceed
372      * {@code length} if the string contains supplementary characters. See the
373      * {@link Character} documentation to understand how Java stores Unicode
374      * values.
375      * </p>
376      *
377      * @param length
378      *            the number of code points to generate
379      * @return The generated string
380      * @throws IllegalArgumentException
381      *             if {@code length < 0}
382      */
383     public String generate(final int length) {
384         if (length == 0) {
385             return StringUtils.EMPTY;
386         }
387         Validate.isTrue(length > 0, "Length %d is smaller than zero.", length);
388         final StringBuilder builder = new StringBuilder(length);
389         long remaining = length;
390         do {
391             final int codePoint;
392             if (characterList != null && !characterList.isEmpty()) {
393                 codePoint = generateRandomNumber(characterList);
394             } else {
395                 codePoint = generateRandomNumber(minimumCodePoint, maximumCodePoint);
396             }
397             switch (Character.getType(codePoint)) {
398             case Character.UNASSIGNED:
399             case Character.PRIVATE_USE:
400             case Character.SURROGATE:
401                 continue;
402             default:
403             }
404             if (inclusivePredicates != null) {
405                 boolean matchedFilter = false;
406                 for (final CharacterPredicate predicate : inclusivePredicates) {
407                     if (predicate.test(codePoint)) {
408                         matchedFilter = true;
409                         break;
410                     }
411                 }
412                 if (!matchedFilter) {
413                     continue;
414                 }
415             }
416             builder.appendCodePoint(codePoint);
417             remaining--;
418         } while (remaining != 0);
419         return builder.toString();
420     }
421 
422     /**
423      * Generates a random string, containing between the minimum (inclusive) and the maximum (inclusive)
424      * number of code points.
425      *
426      * @param minLengthInclusive
427      *            the minimum (inclusive) number of code points to generate
428      * @param maxLengthInclusive
429      *            the maximum (inclusive) number of code points to generate
430      * @return The generated string
431      * @throws IllegalArgumentException
432      *             if {@code minLengthInclusive < 0}, or {@code maxLengthInclusive < minLengthInclusive}
433      * @see RandomStringGenerator#generate(int)
434      * @since 1.2
435      */
436     public String generate(final int minLengthInclusive, final int maxLengthInclusive) {
437         Validate.isTrue(minLengthInclusive >= 0, "Minimum length %d is smaller than zero.", minLengthInclusive);
438         Validate.isTrue(minLengthInclusive <= maxLengthInclusive,
439                 "Maximum length %d is smaller than minimum length %d.", maxLengthInclusive, minLengthInclusive);
440         return generate(generateRandomNumber(minLengthInclusive, maxLengthInclusive));
441     }
442 
443     /**
444      * Generates a random number within a range, using a {@link ThreadLocalRandom} instance
445      * or the user-supplied source of randomness.
446      *
447      * @param minInclusive
448      *            the minimum value allowed
449      * @param maxInclusive
450      *            the maximum value allowed
451      * @return The random number.
452      */
453     private int generateRandomNumber(final int minInclusive, final int maxInclusive) {
454         if (random != null) {
455             return random.nextInt(maxInclusive - minInclusive + 1) + minInclusive;
456         }
457         return ThreadLocalRandom.current().nextInt(minInclusive, maxInclusive + 1);
458     }
459 
460     /**
461      * Generates a random number within a range, using a {@link ThreadLocalRandom} instance
462      * or the user-supplied source of randomness.
463      *
464      * @param characterList predefined char list.
465      * @return The random number.
466      */
467     private int generateRandomNumber(final List<Character> characterList) {
468         final int listSize = characterList.size();
469         if (random != null) {
470             return String.valueOf(characterList.get(random.nextInt(listSize))).codePointAt(0);
471         }
472         return String.valueOf(characterList.get(ThreadLocalRandom.current().nextInt(0, listSize))).codePointAt(0);
473     }
474 }