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  
18  package org.apache.commons.mail;
19  
20  import java.util.Random;
21  
22  /**
23   * Utility methods used by commons-email.
24   *
25   * <p>
26   * These methods are copied from other commons components (commons-lang) to avoid creating
27   * a dependency for such a small component.
28   * </p>
29   *
30   * <p>
31   * This is a package scoped class, and should not be used directly by users.
32   * </p>
33   *
34   * @author jakarta-commons
35   * @version $Id: EmailUtils.java 510809 2007-02-23 04:28:31Z dion $
36   *
37   * @since 1.0
38   */
39  final class EmailUtils
40  {
41      /**
42       * <p>
43       * Random object used by random method. This has to be not local to the random method
44       * so as to not return the same value in the same millisecond.
45       * </p>
46       */
47      private static final Random RANDOM = new Random();
48  
49      /**
50       * Constructs a new <code>EmailException</code> with no detail message.
51       */
52      private EmailUtils()
53      {
54          super();
55      }
56  
57      /**
58       * <p>
59       * Checks if a String is empty ("") or null.
60       * </p>
61       *
62       * @param str the String to check, may be null
63       *
64       * @return <code>true</code> if the String is empty or null
65       *
66       * @since Commons Lang v2.1, svn 240418
67       */
68      static boolean isEmpty(String str)
69      {
70          return (str == null) || (str.length() == 0);
71      }
72  
73      /**
74       * <p>
75       * Checks if a String is not empty ("") and not null.
76       * </p>
77       *
78       * @param str the String to check, may be null
79       *
80       * @return <code>true</code> if the String is not empty and not null
81       *
82       * @since Commons Lang v2.1, svn 240418
83       */
84      static boolean isNotEmpty(String str)
85      {
86          return (str != null) && (str.length() > 0);
87      }
88  
89      /**
90       * <p>
91       * Validate an argument, throwing <code>IllegalArgumentException</code> if the argument is <code>null</code>.
92       * </p>
93       *
94       * @param object the object to check is not <code>null</code>
95       * @param message the exception message you would like to see if the object is <code>null</code>
96       *
97       * @throws IllegalArgumentException if the object is <code>null</code>
98       *
99       * @since Commons Lang v2.1, svn 201930
100      */
101     static void notNull(Object object, String message)
102     {
103         if (object == null)
104         {
105             throw new IllegalArgumentException(message);
106         }
107     }
108 
109     /**
110      * <p>
111      * Creates a random string whose length is the number of characters specified.
112      * </p>
113      *
114      * <p>
115      * Characters will be chosen from the set of alphabetic characters.
116      * </p>
117      *
118      * @param count the length of random string to create
119      *
120      * @return the random string
121      *
122      * @since Commons Lang v2.1, svn 201930
123      */
124     static String randomAlphabetic(int count)
125     {
126         return random(count, 0, 0, true, false, null, RANDOM);
127     }
128 
129     /**
130      * <p>
131      * Creates a random string based on a variety of options, using supplied source of randomness.
132      * </p>
133      *
134      * <p>
135      * If start and end are both <code>0</code>, start and end are set to <code>' '</code> and <code>'z'</code>,
136      * the ASCII printable characters, will be used, unless letters and numbers are both <code>false</code>,
137      * in which case, start and end are set to <code>0</code> and <code>Integer.MAX_VALUE</code>.
138      * </p>
139      *
140      * <p>
141      * If set is not <code>null</code>, characters between start and end are chosen.
142      * </p>
143      *
144      * <p>
145      * This method accepts a user-supplied {@link Random} instance to use as a source of randomness. By seeding a
146      * single {@link Random} instance with a fixed seed and using it for each call, the same random sequence of strings
147      * can be generated repeatedly and predictably.
148      * </p>
149      *
150      * @param count the length of random string to create
151      * @param start the position in set of chars to start at
152      * @param end the position in set of chars to end before
153      * @param letters only allow letters?
154      * @param numbers only allow numbers?
155      * @param chars the set of chars to choose randoms from. If <code>null</code>,
156      *              then it will use the set of all chars.
157      * @param random a source of randomness.
158      *
159      * @return the random string
160      *
161      * @throws IllegalArgumentException if <code>count</code> &lt; 0.
162      *
163      * @since Commons Lang v2.1, svn 201930
164      */
165     private static String random(
166         int count,
167         int start,
168         int end,
169         boolean letters,
170         boolean numbers,
171         char [] chars,
172         Random random)
173     {
174         if (count == 0)
175         {
176             return "";
177         }
178         else if (count < 0)
179         {
180             throw new IllegalArgumentException("Requested random string length " + count + " is less than 0.");
181         }
182 
183         if ((start == 0) && (end == 0))
184         {
185             end = 'z' + 1;
186             start = ' ';
187 
188             if (!letters && !numbers)
189             {
190                 start = 0;
191                 end = Integer.MAX_VALUE;
192             }
193         }
194 
195         StringBuffer buffer = new StringBuffer();
196         int gap = end - start;
197 
198         while (count-- != 0)
199         {
200             char ch;
201 
202             if (chars == null)
203             {
204                 ch = (char) (random.nextInt(gap) + start);
205             }
206             else
207             {
208                 ch = chars[random.nextInt(gap) + start];
209             }
210 
211             if ((letters && numbers && Character.isLetterOrDigit(ch)) || (letters && Character.isLetter(ch))
212                             || (numbers && Character.isDigit(ch)) || (!letters && !numbers))
213             {
214                 buffer.append(ch);
215             }
216             else
217             {
218                 count++;
219             }
220         }
221 
222         return buffer.toString();
223     }
224 }