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 /**
20 * TextRandomProvider implementations are used by {@link RandomStringGenerator}
21 * as a source of randomness. It is highly recommended that the
22 * <a href="https://commons.apache.org/proper/commons-rng/">Apache Commons RNG</a>
23 * library be used to provide the random number generation.
24 *
25 * <p>
26 * When using Java 8 or later, TextRandomProvider is a functional interface and
27 * need not be explicitly implemented. For example:
28 * </p>
29 * <pre>
30 * {@code
31 * UniformRandomProvider rng = RandomSource.create(...);
32 * RandomStringGenerator gen = RandomStringGenerator.builder()
33 * .usingRandom(rng::nextInt)
34 * // additional builder calls as needed
35 * .build();
36 * }
37 * </pre>
38 * @since 1.1
39 */
40 public interface TextRandomProvider {
41
42 /**
43 * Generates an int value between 0 (inclusive) and the specified value
44 * (exclusive).
45 * @param max Bound on the random number to be returned. Must be positive.
46 * @return a random int value between 0 (inclusive) and n (exclusive).
47 */
48 int nextInt(int max);
49 }