1 /**
2 * Copyright 2014 Internet2
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 /*
17 * Licensed to the Apache Software Foundation (ASF) under one or more
18 * contributor license agreements. See the NOTICE file distributed with
19 * this work for additional information regarding copyright ownership.
20 * The ASF licenses this file to You under the Apache License, Version 2.0
21 * (the "License"); you may not use this file except in compliance with
22 * the License. You may obtain a copy of the License at
23 *
24 * http://www.apache.org/licenses/LICENSE-2.0
25 *
26 * Unless required by applicable law or agreed to in writing, software
27 * distributed under the License is distributed on an "AS IS" BASIS,
28 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
29 * See the License for the specific language governing permissions and
30 * limitations under the License.
31 */
32 package edu.internet2.middleware.grouperClientExt.org.apache.commons.lang3;
33
34 import java.util.Random;
35
36 /**
37 * <p>Operations for random {@code String}s.</p>
38 * <p>Currently <em>private high surrogate</em> characters are ignored.
39 * These are Unicode characters that fall between the values 56192 (db80)
40 * and 56319 (dbff) as we don't know how to handle them.
41 * High and low surrogates are correctly dealt with - that is if a
42 * high surrogate is randomly chosen, 55296 (d800) to 56191 (db7f)
43 * then it is followed by a low surrogate. If a low surrogate is chosen,
44 * 56320 (dc00) to 57343 (dfff) then it is placed after a randomly
45 * chosen high surrogate. </p>
46 *
47 * <p>#ThreadSafe#</p>
48 * @since 1.0
49 * @version $Id: RandomStringUtils.java 1199894 2011-11-09 17:53:59Z ggregory $
50 */
51 public class RandomStringUtils {
52
53 /**
54 * <p>Random object used by random method. This has to be not local
55 * to the random method so as to not return the same value in the
56 * same millisecond.</p>
57 */
58 private static final Random RANDOM = new Random();
59
60 /**
61 * <p>{@code RandomStringUtils} instances should NOT be constructed in
62 * standard programming. Instead, the class should be used as
63 * {@code RandomStringUtils.random(5);}.</p>
64 *
65 * <p>This constructor is public to permit tools that require a JavaBean instance
66 * to operate.</p>
67 */
68 public RandomStringUtils() {
69 super();
70 }
71
72 // Random
73 //-----------------------------------------------------------------------
74 /**
75 * <p>Creates a random string whose length is the number of characters
76 * specified.</p>
77 *
78 * <p>Characters will be chosen from the set of all characters.</p>
79 *
80 * @param count the length of random string to create
81 * @return the random string
82 */
83 public static String random(int count) {
84 return random(count, false, false);
85 }
86
87 /**
88 * <p>Creates a random string whose length is the number of characters
89 * specified.</p>
90 *
91 * <p>Characters will be chosen from the set of characters whose
92 * ASCII value is between {@code 32} and {@code 126} (inclusive).</p>
93 *
94 * @param count the length of random string to create
95 * @return the random string
96 */
97 public static String randomAscii(int count) {
98 return random(count, 32, 127, false, false);
99 }
100
101 /**
102 * <p>Creates a random string whose length is the number of characters
103 * specified.</p>
104 *
105 * <p>Characters will be chosen from the set of alphabetic
106 * characters.</p>
107 *
108 * @param count the length of random string to create
109 * @return the random string
110 */
111 public static String randomAlphabetic(int count) {
112 return random(count, true, false);
113 }
114
115 /**
116 * <p>Creates a random string whose length is the number of characters
117 * specified.</p>
118 *
119 * <p>Characters will be chosen from the set of alpha-numeric
120 * characters.</p>
121 *
122 * @param count the length of random string to create
123 * @return the random string
124 */
125 public static String randomAlphanumeric(int count) {
126 return random(count, true, true);
127 }
128
129 /**
130 * <p>Creates a random string whose length is the number of characters
131 * specified.</p>
132 *
133 * <p>Characters will be chosen from the set of numeric
134 * characters.</p>
135 *
136 * @param count the length of random string to create
137 * @return the random string
138 */
139 public static String randomNumeric(int count) {
140 return random(count, false, true);
141 }
142
143 /**
144 * <p>Creates a random string whose length is the number of characters
145 * specified.</p>
146 *
147 * <p>Characters will be chosen from the set of alpha-numeric
148 * characters as indicated by the arguments.</p>
149 *
150 * @param count the length of random string to create
151 * @param letters if {@code true}, generated string will include
152 * alphabetic characters
153 * @param numbers if {@code true}, generated string will include
154 * numeric characters
155 * @return the random string
156 */
157 public static String random(int count, boolean letters, boolean numbers) {
158 return random(count, 0, 0, letters, numbers);
159 }
160
161 /**
162 * <p>Creates a random string whose length is the number of characters
163 * specified.</p>
164 *
165 * <p>Characters will be chosen from the set of alpha-numeric
166 * characters as indicated by the arguments.</p>
167 *
168 * @param count the length of random string to create
169 * @param start the position in set of chars to start at
170 * @param end the position in set of chars to end before
171 * @param letters if {@code true}, generated string will include
172 * alphabetic characters
173 * @param numbers if {@code true}, generated string will include
174 * numeric characters
175 * @return the random string
176 */
177 public static String random(int count, int start, int end, boolean letters, boolean numbers) {
178 return random(count, start, end, letters, numbers, null, RANDOM);
179 }
180
181 /**
182 * <p>Creates a random string based on a variety of options, using
183 * default source of randomness.</p>
184 *
185 * <p>This method has exactly the same semantics as
186 * {@link #random(int,int,int,boolean,boolean,char[],Random)}, but
187 * instead of using an externally supplied source of randomness, it uses
188 * the internal static {@link Random} instance.</p>
189 *
190 * @param count the length of random string to create
191 * @param start the position in set of chars to start at
192 * @param end the position in set of chars to end before
193 * @param letters only allow letters?
194 * @param numbers only allow numbers?
195 * @param chars the set of chars to choose randoms from.
196 * If {@code null}, then it will use the set of all chars.
197 * @return the random string
198 * @throws ArrayIndexOutOfBoundsException if there are not
199 * {@code (end - start) + 1} characters in the set array.
200 */
201 public static String random(int count, int start, int end, boolean letters, boolean numbers, char... chars) {
202 return random(count, start, end, letters, numbers, chars, RANDOM);
203 }
204
205 /**
206 * <p>Creates a random string based on a variety of options, using
207 * supplied source of randomness.</p>
208 *
209 * <p>If start and end are both {@code 0}, start and end are set
210 * to {@code ' '} and {@code 'z'}, the ASCII printable
211 * characters, will be used, unless letters and numbers are both
212 * {@code false}, in which case, start and end are set to
213 * {@code 0} and {@code Integer.MAX_VALUE}.
214 *
215 * <p>If set is not {@code null}, characters between start and
216 * end are chosen.</p>
217 *
218 * <p>This method accepts a user-supplied {@link Random}
219 * instance to use as a source of randomness. By seeding a single
220 * {@link Random} instance with a fixed seed and using it for each call,
221 * the same random sequence of strings can be generated repeatedly
222 * and predictably.</p>
223 *
224 * @param count the length of random string to create
225 * @param start the position in set of chars to start at
226 * @param end the position in set of chars to end before
227 * @param letters only allow letters?
228 * @param numbers only allow numbers?
229 * @param chars the set of chars to choose randoms from.
230 * If {@code null}, then it will use the set of all chars.
231 * @param random a source of randomness.
232 * @return the random string
233 * @throws ArrayIndexOutOfBoundsException if there are not
234 * {@code (end - start) + 1} characters in the set array.
235 * @throws IllegalArgumentException if {@code count} < 0.
236 * @since 2.0
237 */
238 public static String random(int count, int start, int end, boolean letters, boolean numbers,
239 char[] chars, Random random) {
240 if (count == 0) {
241 return "";
242 } else if (count < 0) {
243 throw new IllegalArgumentException("Requested random string length " + count + " is less than 0.");
244 }
245 if (start == 0 && end == 0) {
246 end = 'z' + 1;
247 start = ' ';
248 if (!letters && !numbers) {
249 start = 0;
250 end = Integer.MAX_VALUE;
251 }
252 }
253
254 char[] buffer = new char[count];
255 int gap = end - start;
256
257 while (count-- != 0) {
258 char ch;
259 if (chars == null) {
260 ch = (char) (random.nextInt(gap) + start);
261 } else {
262 ch = chars[random.nextInt(gap) + start];
263 }
264 if (letters && Character.isLetter(ch)
265 || numbers && Character.isDigit(ch)
266 || !letters && !numbers) {
267 if(ch >= 56320 && ch <= 57343) {
268 if(count == 0) {
269 count++;
270 } else {
271 // low surrogate, insert high surrogate after putting it in
272 buffer[count] = ch;
273 count--;
274 buffer[count] = (char) (55296 + random.nextInt(128));
275 }
276 } else if(ch >= 55296 && ch <= 56191) {
277 if(count == 0) {
278 count++;
279 } else {
280 // high surrogate, insert low surrogate before putting it in
281 buffer[count] = (char) (56320 + random.nextInt(128));
282 count--;
283 buffer[count] = ch;
284 }
285 } else if(ch >= 56192 && ch <= 56319) {
286 // private high surrogate, no effing clue, so skip it
287 count++;
288 } else {
289 buffer[count] = ch;
290 }
291 } else {
292 count++;
293 }
294 }
295 return new String(buffer);
296 }
297
298 /**
299 * <p>Creates a random string whose length is the number of characters
300 * specified.</p>
301 *
302 * <p>Characters will be chosen from the set of characters
303 * specified.</p>
304 *
305 * @param count the length of random string to create
306 * @param chars the String containing the set of characters to use,
307 * may be null
308 * @return the random string
309 * @throws IllegalArgumentException if {@code count} < 0.
310 */
311 public static String random(int count, String chars) {
312 if (chars == null) {
313 return random(count, 0, 0, false, false, null, RANDOM);
314 }
315 return random(count, chars.toCharArray());
316 }
317
318 /**
319 * <p>Creates a random string whose length is the number of characters
320 * specified.</p>
321 *
322 * <p>Characters will be chosen from the set of characters specified.</p>
323 *
324 * @param count the length of random string to create
325 * @param chars the character array containing the set of characters to use,
326 * may be null
327 * @return the random string
328 * @throws IllegalArgumentException if {@code count} < 0.
329 */
330 public static String random(int count, char... chars) {
331 if (chars == null) {
332 return random(count, 0, 0, false, false, null, RANDOM);
333 }
334 return random(count, 0, chars.length, false, false, chars, RANDOM);
335 }
336
337 }