Package org.apache.commons.text

Class RandomStringGenerator.Builder

java.lang.Object
org.apache.commons.text.RandomStringGenerator.Builder
All Implemented Interfaces:
Supplier<RandomStringGenerator>, Builder<RandomStringGenerator>
Enclosing class:
RandomStringGenerator
public static class RandomStringGenerator.Builder extends Object implements Builder<RandomStringGenerator>
A builder for generating RandomStringGenerator instances.

The behavior of a generator is controlled by properties set by this builder. Each property has a default value, which can be overridden by calling the methods defined in this class, prior to calling build().

All the property setting methods return the Builder instance to allow for method chaining.

The minimum and maximum code point values are defined using withinRange(int, int). The default values are 0 and Character.MAX_CODE_POINT respectively.

The source of randomness can be set using usingRandom(TextRandomProvider), otherwise ThreadLocalRandom is used.

The type of code points returned can be filtered using filteredBy(CharacterPredicate...), which defines a collection of tests that are applied to the randomly generated code points. The code points will only be included in the result if they pass at least one of the tests. Some commonly used predicates are provided by the CharacterPredicates enum.

This class is not thread safe.

Since:
1.1

  • Field Details

  • Constructor Details

    • Builder

      public Builder()
      Creates a new instance.

  • Method Details

    • build

      @Deprecated public RandomStringGenerator build()
      Deprecated.
      Use get().
      Builds a new RandomStringGenerator.
      Specified by:
      build in interface Builder<RandomStringGenerator>
      Returns:
      A new RandomStringGenerator

    • filteredBy

      public RandomStringGenerator.Builder filteredBy(CharacterPredicate... predicates)
      Limits the characters in the generated string to those that match at least one of the predicates supplied.

      Passing null or an empty array to this method will revert to the default behavior of allowing any character. Multiple calls to this method will replace the previously stored predicates.

      Parameters:
      predicates - the predicates, may be null or empty.
      Returns:
      this instance.

    • get

      public RandomStringGenerator get()
      Builds a new RandomStringGenerator.
      Specified by:
      get in interface Supplier<RandomStringGenerator>
      Returns:
      A new RandomStringGenerator.
      Since:
      1.12.0

    • selectFrom

      public RandomStringGenerator.Builder selectFrom(char... chars)
      Limits the characters in the generated string to those who match at supplied list of Character.

      Passing null or an empty array to this method will revert to the default behavior of allowing any character. Multiple calls to this method will replace the previously stored Character.

      Parameters:
      chars - set of predefined Characters for random string generation the Character can be, may be null or empty
      Returns:
      this instance.
      Since:
      1.2

    • setAccumulate

      public RandomStringGenerator.Builder setAccumulate(boolean accumulate)
      Sets whether calls accumulates the source of provided characters. The default is false. 
       
     RandomStringGenerator gen = RandomStringGenerator.builder()
         .setAccumulate(true)
         .withinRange(new char[][] { { 'a', 'z' }, { 'A', 'Z' }, { '0', '9' } })
         .selectFrom('!', '"', '#', '$', '&', '\'', '(', ')', ',', '.', ':', ';', '?', '@', '[',
                     '\\', ']', '^', '_', '`', '{', '|', '}', '~') // punctuation
         // additional builder calls as needed
         .build();
      Parameters:
      accumulate - whether calls accumulates the source of provided characters. The default is false.
      Returns:
      this instance.
      Since:
      1.14.0

    • usingRandom

      public RandomStringGenerator.Builder usingRandom(IntUnaryOperator random)
      Overrides the default source of randomness. It is highly recommended that a random number generator library like Apache Commons RNG be used to provide the random number generation.

      TextRandomProvider is a functional interface and need not be explicitly implemented: 

       
     UniformRandomProvider rng = RandomSource.create(...);
     RandomStringGenerator gen = RandomStringGenerator.builder()
         .usingRandom(rng::nextInt)
         // additional builder calls as needed
         .build();

      Passing null to this method will revert to the default source of randomness.

      Parameters:
      random - the source of randomness, may be null.
      Returns:
      this instance.
      Since:
      1.14.0

    • usingRandom

      public RandomStringGenerator.Builder usingRandom(TextRandomProvider random)
      Overrides the default source of randomness. It is highly recommended that a random number generator library like Apache Commons RNG be used to provide the random number generation.

      TextRandomProvider is a functional interface and need not be explicitly implemented: 

       
     UniformRandomProvider rng = RandomSource.create(...);
     RandomStringGenerator gen = RandomStringGenerator.builder()
         .usingRandom(rng::nextInt)
         // additional builder calls as needed
         .build();

      Passing null to this method will revert to the default source of randomness.

      Parameters:
      random - the source of randomness, may be null.
      Returns:
      this instance.

    • withinRange

      public RandomStringGenerator.Builder withinRange(char[]... pairs)
      Sets the array of minimum and maximum char allowed in the generated string. For example: 
       
 char[][] pairs = { { '0', '9' } };
 char[][] pairs = { { 'a', 'z' } };
 char[][] pairs = { { 'a', 'z' }, { '0', '9' } };
      Parameters:
      pairs - array of characters array, expected is to pass min, max pairs through this arg.
      Returns:
      this instance.

    • withinRange

      public RandomStringGenerator.Builder withinRange(int minimumCodePoint, int maximumCodePoint)
      Sets the minimum and maximum code points allowed in the generated string.
      Parameters:
      minimumCodePoint - the smallest code point allowed (inclusive).
      maximumCodePoint - the largest code point allowed (inclusive).
      Returns:
      this instance.
      Throws:
      IllegalArgumentException - if maximumCodePoint > Character.MAX_CODE_POINT.
      IllegalArgumentException - if minimumCodePoint < 0.
      IllegalArgumentException - if minimumCodePoint > maximumCodePoint.