View Javadoc

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