View Javadoc

1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one
3    * or more contributor license agreements.  See the NOTICE file
4    * distributed with this work for additional information
5    * regarding copyright ownership.  The ASF licenses this file
6    * to you under the Apache License, Version 2.0 (the
7    * "License"); you may not use this file except in compliance
8    * with the License.  You may obtain a copy of the License at
9    *
10   *   http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing,
13   * software distributed under the License is distributed on an
14   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15   * KIND, either express or implied.  See the License for the
16   * specific language governing permissions and limitations
17   * under the License.
18   */
19  package org.apache.fulcrum.yaafi.framework.util;
20  
21  import java.util.Collection;
22  import java.util.Iterator;
23  import java.util.Map;
24  
25  /**
26   * <p>Assists in validating arguments.</p>
27   *
28   * <p>The class is based along the lines of JUnit. If an argument value is
29   * deemed invalid, an IllegalArgumentException is thrown. For example:</p>
30   *
31   * <pre>
32   * Validate.isTrue( i > 0, "The value must be greater than zero: ", i);
33   * Validate.notNull( surname, "The surname must not be null");
34   * </pre>
35   *
36   * @author <a href="mailto:ola.berg@arkitema.se">Ola Berg</a>
37   * @author Stephen Colebourne
38   * @author Gary Gregory
39   * @author Norm Deane
40   * @since 2.0
41   * @version $Id: Validate.java 535465 2007-05-05 06:58:06Z tv $
42   */
43  public class Validate
44  {
45      // Validate has no dependencies on other classes in Commons Lang at present
46  
47      /**
48       * Constructor. This class should not normally be instantiated.
49       */
50      public Validate()
51      {
52          // nothing to do
53      }
54  
55      // isTrue
56      //---------------------------------------------------------------------------------
57  
58      /**
59       * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
60       * if the test result is <code>false</code>.</p>
61       *
62       * <p>This is used when validating according to an arbitrary boolean expression,
63       * such as validating a primitive number or using your own custom validation
64       * expression.</p>
65       *
66       * <pre>
67       * Validate.isTrue( myObject.isOk(), "The object is not OK: ", myObject);
68       * </pre>
69       *
70       * <p>For performance reasons, the object is passed as a separate parameter and
71       * appended to the message string only in the case of an error.</p>
72       *
73       * @param expression  a boolean expression
74       * @param message  the exception message you would like to see if the
75       *  expression is <code>false</code>
76       * @param value  the value to append to the message in case of error
77       * @throws IllegalArgumentException if expression is <code>false</code>
78       */
79      public static void isTrue(boolean expression, String message, Object value)
80      {
81          if (expression == false)
82          {
83              throw new IllegalArgumentException( message + value );
84          }
85      }
86  
87      /**
88       * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
89       * if the test result is <code>false</code>.</p>
90       *
91       * <p>This is used when validating according to an arbitrary boolean expression,
92       * such as validating a primitive number or using your own custom validation
93       * expression.</p>
94       *
95       * <pre>
96       * Validate.isTrue( i > 0, "The value must be greater than zero: ", i);
97       * </pre>
98       *
99       * <p>For performance reasons, the long value is passed as a separate parameter and
100      * appended to the message string only in the case of an error.</p>
101      *
102      * @param expression  a boolean expression
103      * @param message  the exception message you would like to see if the expression is <code>false</code>
104      * @param value  the value to append to the message in case of error
105      * @throws IllegalArgumentException if expression is <code>false</code>
106      */
107     public static void isTrue(boolean expression, String message, long value)
108     {
109         if (expression == false)
110         {
111             throw new IllegalArgumentException( message + value );
112         }
113     }
114 
115     /**
116      * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
117      * if the test result is <code>false</code>.</p>
118      *
119      * <p>This is used when validating according to an arbitrary boolean expression,
120      * such as validating a primitive number or using your own custom validation
121      * expression.</p>
122      *
123      * <pre>
124      * Validate.isTrue( d > 0.0, "The value must be greater than zero: ", d);
125      * </pre>
126      *
127      * <p>For performance reasons, the double value is passed as a separate parameter and
128      * appended to the message string only in the case of an error.</p>
129      *
130      * @param expression  a boolean expression
131      * @param message  the exception message you would like to see if the expression
132      *  is <code>false</code>
133      * @param value  the value to append to the message in case of error
134      * @throws IllegalArgumentException if expression is <code>false</code>
135      */
136     public static void isTrue(boolean expression, String message, double value)
137     {
138         if (expression == false)
139         {
140             throw new IllegalArgumentException( message + value );
141         }
142     }
143 
144     /**
145      * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
146      * if the test result is <code>false</code>.</p>
147      *
148      * <p>This is used when validating according to an arbitrary boolean expression,
149      * such as validating a primitive number or using your own custom validation
150      * expression.</p>
151      *
152      * <pre>
153      * Validate.isTrue( (i > 0), "The value must be greater than zero");
154      * Validate.isTrue( myObject.isOk(), "The object is not OK");
155      * </pre>
156      *
157      * <p>For performance reasons, the message string should not involve a string append,
158      * instead use the {@link #isTrue(boolean, String, Object)} method.</p>
159      *
160      * @param expression  a boolean expression
161      * @param message  the exception message you would like to see if the expression
162      *  is <code>false</code>
163      * @throws IllegalArgumentException if expression is <code>false</code>
164      */
165     public static void isTrue(boolean expression, String message)
166     {
167         if (expression == false)
168         {
169             throw new IllegalArgumentException( message );
170         }
171     }
172 
173     /**
174      * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
175      * if the test result is <code>false</code>.</p>
176      *
177      * <p>This is used when validating according to an arbitrary boolean expression,
178      * such as validating a primitive number or using your own custom validation
179      * expression.</p>
180      *
181      * <pre>
182      * Validate.isTrue( i > 0 );
183      * Validate.isTrue( myObject.isOk() );
184      * </pre>
185      *
186      * <p>The message in the exception is 'The validated expression is false'.</p>
187      *
188      * @param expression  a boolean expression
189      * @throws IllegalArgumentException if expression is <code>false</code>
190      */
191     public static void isTrue(boolean expression)
192     {
193         if (expression == false)
194         {
195             throw new IllegalArgumentException(
196                             "The validated expression is false" );
197         }
198     }
199 
200     // notNull
201     //---------------------------------------------------------------------------------
202 
203     /**
204      * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
205      * if the argument is <code>null</code>.</p>
206      *
207      * <pre>
208      * Validate.notNull(myObject, "The object must not be null");
209      * </pre>
210      *
211      * @param object  the object to check is not <code>null</code>
212      * @param message  the exception message you would like to see
213      *  if the object is <code>null</code>
214      * @throws IllegalArgumentException if the object is <code>null</code>
215      */
216     public static void notNull(Object object, String message)
217     {
218         if (object == null)
219         {
220             throw new IllegalArgumentException( message );
221         }
222     }
223 
224     /**
225      * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
226      * if the argument is <code>null</code>.</p>
227      *
228      * <pre>
229      * Validate.notNull(myObject);
230      * </pre>
231      *
232      * <p>The message in the exception is 'The validated object is null'.</p>
233      *
234      * @param object  the object to check is not <code>null</code>
235      * @throws IllegalArgumentException if the object is <code>null</code>
236      */
237     public static void notNull(Object object)
238     {
239         if (object == null)
240         {
241             throw new IllegalArgumentException( "The validated object is null" );
242         }
243     }
244 
245     // notEmpty array
246     //---------------------------------------------------------------------------------
247 
248     /**
249      * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
250      * if the argument array is empty (<code>null</code> or no elements).</p>
251      *
252      * <pre>
253      * Validate.notEmpty(myArray, "The array must not be empty");
254      * </pre>
255      *
256      * @param array  the array to check is not empty
257      * @param message  the exception message you would like to see if the array is empty
258      * @throws IllegalArgumentException if the array is empty
259      */
260     public static void notEmpty(Object [] array, String message)
261     {
262         if (array == null || array.length == 0)
263         {
264             throw new IllegalArgumentException( message );
265         }
266     }
267 
268     /**
269      * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
270      * if the argument array is empty (<code>null</code> or no elements).</p>
271      *
272      * <pre>
273      * Validate.notEmpty(myArray);
274      * </pre>
275      *
276      * <p>The message in the exception is 'The validated array is empty'.
277      *
278      * @param array  the array to check is not empty
279      * @throws IllegalArgumentException if the array is empty
280      */
281     public static void notEmpty(Object [] array)
282     {
283         if (array == null || array.length == 0)
284         {
285             throw new IllegalArgumentException( "The validated array is empty" );
286         }
287     }
288 
289     // notEmpty collection
290     //---------------------------------------------------------------------------------
291 
292     /**
293      * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
294      * if the argument Collection is empty (<code>null</code> or no elements).</p>
295      *
296      * <pre>
297      * Validate.notEmpty(myCollection, "The collection must not be empty");
298      * </pre>
299      *
300      * @param collection  the collection to check is not empty
301      * @param message  the exception message you would like to see if the collection is empty
302      * @throws IllegalArgumentException if the collection is empty
303      */
304     public static void notEmpty(Collection collection, String message)
305     {
306         if (collection == null || collection.size() == 0)
307         {
308             throw new IllegalArgumentException( message );
309         }
310     }
311 
312     /**
313      * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
314      * if the argument Collection is empty (<code>null</code> or no elements).</p>
315      *
316      * <pre>
317      * Validate.notEmpty(myCollection);
318      * </pre>
319      *
320      * <p>The message in the exception is 'The validated collection is empty'.</p>
321      *
322      * @param collection  the collection to check is not empty
323      * @throws IllegalArgumentException if the collection is empty
324      */
325     public static void notEmpty(Collection collection)
326     {
327         if (collection == null || collection.size() == 0)
328         {
329             throw new IllegalArgumentException(
330                             "The validated collection is empty" );
331         }
332     }
333 
334     // notEmpty map
335     //---------------------------------------------------------------------------------
336 
337     /**
338      * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
339      * if the argument Map is empty (<code>null</code> or no elements).</p>
340      *
341      * <pre>
342      * Validate.notEmpty(myMap, "The map must not be empty");
343      * </pre>
344      *
345      * @param map  the map to check is not empty
346      * @param message  the exception message you would like to see if the map is empty
347      * @throws IllegalArgumentException if the map is empty
348      */
349     public static void notEmpty(Map map, String message)
350     {
351         if (map == null || map.size() == 0)
352         {
353             throw new IllegalArgumentException( message );
354         }
355     }
356 
357     /**
358      * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
359      * if the argument Map is empty (<code>null</code> or no elements).</p>
360      *
361      * <pre>
362      * Validate.notEmpty(myMap);
363      * </pre>
364      *
365      * <p>The message in the exception is 'The validated map is empty'.</p>
366      *
367      * @param map  the map to check is not empty
368      * @throws IllegalArgumentException if the map is empty
369      */
370     public static void notEmpty(Map map)
371     {
372         if (map == null || map.size() == 0)
373         {
374             throw new IllegalArgumentException( "The validated map is empty" );
375         }
376     }
377 
378     // notEmpty string
379     //---------------------------------------------------------------------------------
380 
381     /**
382      * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
383      * if the argument String is empty (<code>null</code> or zero length).</p>
384      *
385      * <pre>
386      * Validate.notEmpty(myString, "The string must not be empty");
387      * </pre>
388      *
389      * @param string  the string to check is not empty
390      * @param message  the exception message you would like to see if the string is empty
391      * @throws IllegalArgumentException if the string is empty
392      */
393     public static void notEmpty(String string, String message)
394     {
395         if (string == null || string.length() == 0)
396         {
397             throw new IllegalArgumentException( message );
398         }
399     }
400 
401     /**
402      * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
403      * if the argument String is empty (<code>null</code> or zero length).</p>
404      *
405      * <pre>
406      * Validate.notEmpty(myString);
407      * </pre>
408      *
409      * <p>The message in the exception is 'The validated string is empty'.</p>
410      *
411      * @param string  the string to check is not empty
412      * @throws IllegalArgumentException if the string is empty
413      */
414     public static void notEmpty(String string)
415     {
416         if (string == null || string.length() == 0)
417         {
418             throw new IllegalArgumentException( "The validated string is empty" );
419         }
420     }
421 
422     // notNullElements array
423     //---------------------------------------------------------------------------------
424 
425     /**
426      * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
427      * if the argument array has <code>null</code> elements or is
428      * <code>null</code>.</p>
429      *
430      * <pre>
431      * Validate.noNullElements(myArray, "The array must not contain null elements");
432      * </pre>
433      *
434      * <p>If the array is null then the message in the exception is 'The validated object is null'.</p>
435      *
436      * @param array  the array to check
437      * @param message  the exception message if the array has
438      *  <code>null</code> elements
439      * @throws IllegalArgumentException if the array has <code>null</code>
440      *  elements or is <code>null</code>
441      */
442     public static void noNullElements(Object [] array, String message)
443     {
444         Validate.notNull( array );
445         for (int i = 0; i < array.length; i++)
446         {
447             if (array[i] == null)
448             {
449                 throw new IllegalArgumentException( message );
450             }
451         }
452     }
453 
454     /**
455      * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
456      * if the argument array has <code>null</code> elements or is
457      * <code>null</code>.</p>
458      *
459      * <pre>
460      * Validate.noNullElements(myArray);
461      * </pre>
462      *
463      * <p>If the array has a null element the message in the exception is
464      * 'The validated array contains null element at index: '.</p>
465      *
466      * <p>If the array is null then the message in the exception is 'The validated object is null'.</p>
467      *
468      * @param array  the array to check
469      * @throws IllegalArgumentException if the array has <code>null</code>
470      *  elements or is <code>null</code>
471      */
472     public static void noNullElements(Object [] array)
473     {
474         Validate.notNull( array );
475         for (int i = 0; i < array.length; i++)
476         {
477             if (array[i] == null)
478             {
479                 throw new IllegalArgumentException(
480                                 "The validated array contains null element at index: "
481                                                 + i );
482             }
483         }
484     }
485 
486     // notNullElements collection
487     //---------------------------------------------------------------------------------
488 
489     /**
490      * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
491      * if the argument Collection has <code>null</code> elements or is
492      * <code>null</code>.</p>
493      *
494      * <pre>
495      * Validate.noNullElements(myCollection, "The collection must not contain null elements");
496      * </pre>
497      *
498      * <p>If the collection is null then the message in the exception is 'The validated object is null'.</p>
499      *
500      * @param collection  the collection to check
501      * @param message  the exception message if the collection has
502      *  <code>null</code> elements
503      * @throws IllegalArgumentException if the collection has
504      *  <code>null</code> elements or is <code>null</code>
505      */
506     public static void noNullElements(Collection collection, String message)
507     {
508         Validate.notNull( collection );
509         for (Iterator it = collection.iterator(); it.hasNext();)
510         {
511             if (it.next() == null)
512             {
513                 throw new IllegalArgumentException( message );
514             }
515         }
516     }
517 
518     /**
519      * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
520      * if the argument Collection has <code>null</code> elements or is
521      * <code>null</code>.</p>
522      *
523      * <pre>
524      * Validate.noNullElements(myCollection);
525      * </pre>
526      *
527      * <p>The message in the exception is 'The validated collection contains null element at index: '.</p>
528      *
529      * <p>If the collection is null then the message in the exception is 'The validated object is null'.</p>
530      *
531      * @param collection  the collection to check
532      * @throws IllegalArgumentException if the collection has
533      *  <code>null</code> elements or is <code>null</code>
534      */
535     public static void noNullElements(Collection collection)
536     {
537         Validate.notNull( collection );
538         int i = 0;
539         for (Iterator it = collection.iterator(); it.hasNext(); i++)
540         {
541             if (it.next() == null)
542             {
543                 throw new IllegalArgumentException(
544                                 "The validated collection contains null element at index: "
545                                                 + i );
546             }
547         }
548     }
549 
550     /**
551      * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
552      * if the argument collection  is <code>null</code> or has elements that
553      * are not of type <code>clazz</code> or a subclass.</p>
554      *
555      * <pre>
556      * Validate.allElementsOfType(collection, String.class, "Collection has invalid elements");
557      * </pre>
558      *
559      * @param collection  the collection to check, not null
560      * @param clazz  the <code>Class</code> which the collection's elements are expected to be, not null
561      * @param message  the exception message if the <code>Collection</code> has elements not of type <code>clazz</code>
562      * @since 2.1
563      */
564     public static void allElementsOfType(Collection collection, Class clazz,
565         String message)
566     {
567         Validate.notNull( collection );
568         Validate.notNull( clazz );
569         for (Iterator it = collection.iterator(); it.hasNext();)
570         {
571             if (clazz.isInstance( it.next() ) == false)
572             {
573                 throw new IllegalArgumentException( message );
574             }
575         }
576     }
577 
578     /**
579      * <p>
580      * Validate an argument, throwing <code>IllegalArgumentException</code> if the argument collection is
581      * <code>null</code> or has elements that are not of type <code>clazz</code> or a subclass.
582      * </p>
583      *
584      * <pre>
585      * Validate.allElementsOfType(collection, String.class);
586      * </pre>
587      *
588      * <p>
589      * The message in the exception is 'The validated collection contains an element not of type clazz at index: '.
590      * </p>
591      *
592      * @param collection
593      *            the collection to check, not null
594      * @param clazz
595      *            the <code>Class</code> which the collection's elements are expected to be, not null
596      * @since 2.1
597      */
598     public static void allElementsOfType(Collection collection, Class clazz)
599     {
600         Validate.notNull( collection );
601         Validate.notNull( clazz );
602         int i = 0;
603         for (Iterator it = collection.iterator(); it.hasNext(); i++)
604         {
605             if (clazz.isInstance( it.next() ) == false)
606             {
607                 throw new IllegalArgumentException(
608                                 "The validated collection contains an element not of type "
609                                                 + clazz.getName()
610                                                 + " at index: " + i );
611             }
612         }
613     }
614 }