RandomStringUtils


1   /*
2    * Copyright 2002-2005 The Apache Software Foundation.
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  package org.apache.commons.lang;
17  
18  import java.util.Random  ;
19  /**
20   * <p>Operations for random <code>String</code>s.</p>
21   *
22   * @author GenerationJava Core library
23   * @author <a HREF="mailto:bayard@generationjava.com">Henri Yandell</a>
24   * @author <a HREF="mailto:steven@caswell.name">Steven Caswell</a>
25   * @author Stephen Colebourne
26   * @author Gary Gregory
27   * @author Phil Steitz
28   * @since 1.0
29   * @version $Id: RandomStringUtils.java 161243 2005-04-14 04:30:28Z ggregory $
30   */
31  public class RandomStringUtils {
32  
33      /**
34       * <p>Random object used by random method. This has to be not local
35       * to the random method so as to not return the same value in the 
36       * same millisecond.</p>
37       */
38      private static final Random   RANDOM = new Random  ();
39  
40      /**
41       * <p><code>RandomStringUtils</code> instances should NOT be constructed in
42       * standard programming. Instead, the class should be used as
43       * <code>RandomStringUtils.random(5);</code>.</p>
44       *
45       * <p>This constructor is public to permit tools that require a JavaBean instance
46       * to operate.</p>
47       */
48      public RandomStringUtils() {
49      }
50  
51      // Random
52      //-----------------------------------------------------------------------
53      /**
54       * <p>Creates a random string whose length is the number of characters
55       * specified.</p>
56       *
57       * <p>Characters will be chosen from the set of all characters.</p>
58       *
59       * @param count  the length of random string to create
60       * @return the random string
61       */
62      public static String   random(int count) {
63          return random(count, false, false);
64      }
65  
66      /**
67       * <p>Creates a random string whose length is the number of characters
68       * specified.</p>
69       *
70       * <p>Characters will be chosen from the set of characters whose
71       * ASCII value is between <code>32</code> and <code>126</code> (inclusive).</p>
72       *
73       * @param count  the length of random string to create
74       * @return the random string
75       */
76      public static String   randomAscii(int count) {
77          return random(count, 32, 127, false, false);
78      }
79      
80      /**
81       * <p>Creates a random string whose length is the number of characters
82       * specified.</p>
83       *
84       * <p>Characters will be chosen from the set of alphabetic
85       * characters.</p>
86       *
87       * @param count  the length of random string to create
88       * @return the random string
89       */
90      public static String   randomAlphabetic(int count) {
91          return random(count, true, false);
92      }
93      
94      /**
95       * <p>Creates a random string whose length is the number of characters
96       * specified.</p>
97       *
98       * <p>Characters will be chosen from the set of alpha-numeric
99       * characters.</p>
100      *
101      * @param count  the length of random string to create
102      * @return the random string
103      */
104     public static String   randomAlphanumeric(int count) {
105         return random(count, true, true);
106     }
107     
108     /**
109      * <p>Creates a random string whose length is the number of characters
110      * specified.</p>
111      *
112      * <p>Characters will be chosen from the set of numeric
113      * characters.</p>
114      *
115      * @param count  the length of random string to create
116      * @return the random string
117      */
118     public static String   randomNumeric(int count) {
119         return random(count, false, true);
120     }
121 
122     /**
123      * <p>Creates a random string whose length is the number of characters
124      * specified.</p>
125      *
126      * <p>Characters will be chosen from the set of alpha-numeric
127      * characters as indicated by the arguments.</p>
128      *
129      * @param count  the length of random string to create
130      * @param letters  if <code>true</code>, generated string will include
131      *  alphabetic characters
132      * @param numbers  if <code>true</code>, generated string will include
133      *  numeric characters
134      * @return the random string
135      */
136     public static String   random(int count, boolean letters, boolean numbers) {
137         return random(count, 0, 0, letters, numbers);
138     }
139     
140     /**
141      * <p>Creates a random string whose length is the number of characters
142      * specified.</p>
143      *
144      * <p>Characters will be chosen from the set of alpha-numeric
145      * characters as indicated by the arguments.</p>
146      *
147      * @param count  the length of random string to create
148      * @param start  the position in set of chars to start at
149      * @param end  the position in set of chars to end before
150      * @param letters  if <code>true</code>, generated string will include
151      *  alphabetic characters
152      * @param numbers  if <code>true</code>, generated string will include
153      *  numeric characters
154      * @return the random string
155      */
156     public static String   random(int count, int start, int end, boolean letters, boolean numbers) {
157         return random(count, start, end, letters, numbers, null, RANDOM);
158     }
159 
160     /**
161      * <p>Creates a random string based on a variety of options, using
162      * default source of randomness.</p>
163      *
164      * <p>This method has exactly the same semantics as
165      * {@link #random(int,int,int,boolean,boolean,char[],Random)}, but
166      * instead of using an externally supplied source of randomness, it uses
167      * the internal static {@link Random} instance.</p>
168      *
169      * @param count  the length of random string to create
170      * @param start  the position in set of chars to start at
171      * @param end  the position in set of chars to end before
172      * @param letters  only allow letters?
173      * @param numbers  only allow numbers?
174      * @param chars  the set of chars to choose randoms from.
175      *  If <code>null</code>, then it will use the set of all chars.
176      * @return the random string
177      * @throws ArrayIndexOutOfBoundsException if there are not
178      *  <code>(end - start) + 1</code> characters in the set array.
179      */
180     public static String   random(int count, int start, int end, boolean letters, boolean numbers, char[] chars) {
181         return random(count, start, end, letters, numbers, chars, RANDOM);
182     }
183 
184     /**
185      * <p>Creates a random string based on a variety of options, using
186      * supplied source of randomness.</p>
187      *
188      * <p>If start and end are both <code>0</code>, start and end are set
189      * to <code>' '</code> and <code>'z'</code>, the ASCII printable
190      * characters, will be used, unless letters and numbers are both
191      * <code>false</code>, in which case, start and end are set to
192      * <code>0</code> and <code>Integer.MAX_VALUE</code>.
193      *
194      * <p>If set is not <code>null</code>, characters between start and
195      * end are chosen.</p>
196      *
197      * <p>This method accepts a user-supplied {@link Random}
198      * instance to use as a source of randomness. By seeding a single 
199      * {@link Random} instance with a fixed seed and using it for each call,
200      * the same random sequence of strings can be generated repeatedly
201      * and predictably.</p>
202      *
203      * @param count  the length of random string to create
204      * @param start  the position in set of chars to start at
205      * @param end  the position in set of chars to end before
206      * @param letters  only allow letters?
207      * @param numbers  only allow numbers?
208      * @param chars  the set of chars to choose randoms from.
209      *  If <code>null</code>, then it will use the set of all chars.
210      * @param random  a source of randomness.
211      * @return the random string
212      * @throws ArrayIndexOutOfBoundsException if there are not
213      *  <code>(end - start) + 1</code> characters in the set array.
214      * @throws IllegalArgumentException if <code>count</code> &lt; 0.
215      * @since 2.0
216      */
217     public static String   random(int count, int start, int end, boolean letters, boolean numbers,
218                                 char[] chars, Random   random) {
219         if (count == 0) {
220             return "";
221         } else if (count < 0) {
222             throw new IllegalArgumentException  ("Requested random string length " + count + " is less than 0.");
223         }
224         if ((start == 0) && (end == 0)) {
225             end = 'z' + 1;
226             start = ' ';
227             if (!letters && !numbers) {
228                 start = 0;
229                 end = Integer.MAX_VALUE;
230             }
231         }
232 
233         StringBuffer   buffer = new StringBuffer  ();
234         int gap = end - start;
235 
236         while (count-- != 0) {
237             char ch;
238             if (chars == null) {
239                 ch = (char) (random.nextInt(gap) + start);
240             } else {
241                 ch = chars[random.nextInt(gap) + start];
242             }
243             if ((letters && numbers && Character.isLetterOrDigit(ch))
244                 || (letters && Character.isLetter(ch))
245                 || (numbers && Character.isDigit(ch))
246                 || (!letters && !numbers)) {
247                 buffer.append(ch);
248             } else {
249                 count++;
250             }
251         }
252         return buffer.toString();
253     }
254 
255     /**
256      * <p>Creates a random string whose length is the number of characters
257      * specified.</p>
258      *
259      * <p>Characters will be chosen from the set of characters
260      * specified.</p>
261      *
262      * @param count  the length of random string to create
263      * @param chars  the String containing the set of characters to use,
264      *  may be null
265      * @return the random string
266      * @throws IllegalArgumentException if <code>count</code> &lt; 0.
267      */
268     public static String   random(int count, String   chars) {
269         if (chars == null) {
270             return random(count, 0, 0, false, false, null, RANDOM);
271         }
272         return random(count, chars.toCharArray());
273     }
274 
275     /**
276      * <p>Creates a random string whose length is the number of characters
277      * specified.</p>
278      *
279      * <p>Characters will be chosen from the set of characters specified.</p>
280      *
281      * @param count  the length of random string to create
282      * @param chars  the character array containing the set of characters to use,
283      *  may be null
284      * @return the random string
285      * @throws IllegalArgumentException if <code>count</code> &lt; 0.
286      */
287     public static String   random(int count, char[] chars) {
288         if (chars == null) {
289             return random(count, 0, 0, false, false, null, RANDOM);
290         }
291         return random(count, 0, chars.length, false, false, chars, RANDOM);
292     }
293     
294 }
295
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags