001    /*
002     * Licensed to the Apache Software Foundation (ASF) under one or more
003     * contributor license agreements.  See the NOTICE file distributed with
004     * this work for additional information regarding copyright ownership.
005     * The ASF licenses this file to You under the Apache License, Version 2.0
006     * (the "License"); you may not use this file except in compliance with
007     * the License.  You may obtain a copy of the License at
008     * 
009     *      http://www.apache.org/licenses/LICENSE-2.0
010     * 
011     * Unless required by applicable law or agreed to in writing, software
012     * distributed under the License is distributed on an "AS IS" BASIS,
013     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014     * See the License for the specific language governing permissions and
015     * limitations under the License.
016     */
017    package org.apache.commons.lang;
018    
019    import java.util.Collection;
020    import java.util.Iterator;
021    import java.util.Map;
022    
023    /**
024     * <p>Assists in validating arguments.</p>
025     * 
026     * <p>The class is based along the lines of JUnit. If an argument value is 
027     * deemed invalid, an IllegalArgumentException is thrown. For example:</p>
028     * 
029     * <pre>
030     * Validate.isTrue( i > 0, "The value must be greater than zero: ", i);
031     * Validate.notNull( surname, "The surname must not be null");
032     * </pre>
033     *
034     * @author <a href="mailto:ola.berg@arkitema.se">Ola Berg</a>
035     * @author Stephen Colebourne
036     * @author Gary Gregory
037     * @author Norm Deane
038     * @since 2.0
039     * @version $Id: Validate.java 437554 2006-08-28 06:21:41Z bayard $
040     */
041    public class Validate {
042        // Validate has no dependencies on other classes in Commons Lang at present
043        
044        /**
045         * Constructor. This class should not normally be instantiated.
046         */
047        public Validate() {
048          super();
049        }
050        
051        // isTrue
052        //---------------------------------------------------------------------------------
053    
054        /**
055         * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
056         * if the test result is <code>false</code>.</p>
057         * 
058         * <p>This is used when validating according to an arbitrary boolean expression,
059         * such as validating a primitive number or using your own custom validation 
060         * expression.</p>
061         *
062         * <pre>
063         * Validate.isTrue( myObject.isOk(), "The object is not OK: ", myObject);
064         * </pre>
065         *
066         * <p>For performance reasons, the object is passed as a separate parameter and
067         * appended to the message string only in the case of an error.</p>
068         * 
069         * @param expression  a boolean expression
070         * @param message  the exception message you would like to see if the
071         *  expression is <code>false</code>
072         * @param value  the value to append to the message in case of error
073         * @throws IllegalArgumentException if expression is <code>false</code>
074         */
075        public static void isTrue(boolean expression, String message, Object value) {
076            if (expression == false) {
077                throw new IllegalArgumentException(message + value);
078            }
079        }
080    
081        /**
082         * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
083         * if the test result is <code>false</code>.</p>
084         * 
085         * <p>This is used when validating according to an arbitrary boolean expression,
086         * such as validating a primitive number or using your own custom validation 
087         * expression.</p>
088         *
089         * <pre>
090         * Validate.isTrue( i > 0, "The value must be greater than zero: ", i);
091         * </pre>
092         *
093         * <p>For performance reasons, the long value is passed as a separate parameter and
094         * appended to the message string only in the case of an error.</p>
095         * 
096         * @param expression  a boolean expression
097         * @param message  the exception message you would like to see if the expression is <code>false</code>
098         * @param value  the value to append to the message in case of error
099         * @throws IllegalArgumentException if expression is <code>false</code>
100         */
101        public static void isTrue(boolean expression, String message, long value) {
102            if (expression == false) {
103                throw new IllegalArgumentException(message + value);
104            }
105        }
106    
107        /**
108         * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
109         * if the test result is <code>false</code>.</p>
110         * 
111         * <p>This is used when validating according to an arbitrary boolean expression,
112         * such as validating a primitive number or using your own custom validation 
113         * expression.</p>
114         *
115         * <pre>
116         * Validate.isTrue( d > 0.0, "The value must be greater than zero: ", d);
117         * </pre>
118         *
119         * <p>For performance reasons, the double value is passed as a separate parameter and
120         * appended to the message string only in the case of an error.</p>
121         * 
122         * @param expression  a boolean expression
123         * @param message  the exception message you would like to see if the expression
124         *  is <code>false</code>
125         * @param value  the value to append to the message in case of error
126         * @throws IllegalArgumentException if expression is <code>false</code>
127         */
128        public static void isTrue(boolean expression, String message, double value) {
129            if (expression == false) {
130                throw new IllegalArgumentException(message + value);
131            }
132        }
133    
134        /**
135         * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
136         * if the test result is <code>false</code>.</p>
137         * 
138         * <p>This is used when validating according to an arbitrary boolean expression,
139         * such as validating a primitive number or using your own custom validation 
140         * expression.</p>
141         *
142         * <pre>
143         * Validate.isTrue( (i > 0), "The value must be greater than zero");
144         * Validate.isTrue( myObject.isOk(), "The object is not OK");
145         * </pre>
146         *
147         * <p>For performance reasons, the message string should not involve a string append,
148         * instead use the {@link #isTrue(boolean, String, Object)} method.</p>
149         * 
150         * @param expression  a boolean expression
151         * @param message  the exception message you would like to see if the expression
152         *  is <code>false</code>
153         * @throws IllegalArgumentException if expression is <code>false</code>
154         */
155        public static void isTrue(boolean expression, String message) {
156            if (expression == false) {
157                throw new IllegalArgumentException(message);
158            }
159        }
160    
161        /**
162         * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
163         * if the test result is <code>false</code>.</p>
164         * 
165         * <p>This is used when validating according to an arbitrary boolean expression,
166         * such as validating a primitive number or using your own custom validation 
167         * expression.</p>
168         *
169         * <pre>
170         * Validate.isTrue( i > 0 );
171         * Validate.isTrue( myObject.isOk() );
172         * </pre>
173         *
174         * <p>The message in the exception is 'The validated expression is false'.</p>
175         * 
176         * @param expression  a boolean expression
177         * @throws IllegalArgumentException if expression is <code>false</code>
178         */
179        public static void isTrue(boolean expression) {
180            if (expression == false) {
181                throw new IllegalArgumentException("The validated expression is false");
182            }
183        }
184    
185        // notNull
186        //---------------------------------------------------------------------------------
187    
188        /**
189         * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
190         * if the argument is <code>null</code>.</p>
191         *
192         * <pre>
193         * Validate.notNull(myObject, "The object must not be null");
194         * </pre>
195         * 
196         * @param object  the object to check is not <code>null</code>
197         * @param message  the exception message you would like to see
198         *  if the object is <code>null</code>
199         * @throws IllegalArgumentException if the object is <code>null</code>
200         */
201        public static void notNull(Object object, String message) {
202            if (object == null) {
203                throw new IllegalArgumentException(message);
204            }
205        }
206    
207        /**
208         * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
209         * if the argument is <code>null</code>.</p>
210         *
211         * <pre>
212         * Validate.notNull(myObject);
213         * </pre>
214         *
215         * <p>The message in the exception is 'The validated object is null'.</p>
216         * 
217         * @param object  the object to check is not <code>null</code>
218         * @throws IllegalArgumentException if the object is <code>null</code>
219         */
220        public static void notNull(Object object) {
221            if (object == null) {
222                throw new IllegalArgumentException("The validated object is null");
223            }
224        }
225    
226        // notEmpty array
227        //---------------------------------------------------------------------------------
228    
229        /**
230         * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
231         * if the argument array is empty (<code>null</code> or no elements).</p>
232         *
233         * <pre>
234         * Validate.notEmpty(myArray, "The array must not be empty");
235         * </pre>
236         * 
237         * @param array  the array to check is not empty
238         * @param message  the exception message you would like to see if the array is empty
239         * @throws IllegalArgumentException if the array is empty
240         */
241        public static void notEmpty(Object[] array, String message) {
242            if (array == null || array.length == 0) {
243                throw new IllegalArgumentException(message);
244            }
245        }
246    
247        /**
248         * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
249         * if the argument array is empty (<code>null</code> or no elements).</p>
250         *
251         * <pre>
252         * Validate.notEmpty(myArray);
253         * </pre>
254         *
255         * <p>The message in the exception is 'The validated array is empty'.
256         * 
257         * @param array  the array to check is not empty
258         * @throws IllegalArgumentException if the array is empty
259         */
260        public static void notEmpty(Object[] array) {
261            if (array == null || array.length == 0) {
262                throw new IllegalArgumentException("The validated array is empty");
263            }
264        }
265    
266        // notEmpty collection
267        //---------------------------------------------------------------------------------
268    
269        /**
270         * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
271         * if the argument Collection is empty (<code>null</code> or no elements).</p>
272         *
273         * <pre>
274         * Validate.notEmpty(myCollection, "The collection must not be empty");
275         * </pre>
276         * 
277         * @param collection  the collection to check is not empty
278         * @param message  the exception message you would like to see if the collection is empty
279         * @throws IllegalArgumentException if the collection is empty
280         */
281        public static void notEmpty(Collection collection, String message) {
282            if (collection == null || collection.size() == 0) {
283                throw new IllegalArgumentException(message);
284            }
285        }
286    
287        /**
288         * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
289         * if the argument Collection is empty (<code>null</code> or no elements).</p>
290         *
291         * <pre>
292         * Validate.notEmpty(myCollection);
293         * </pre>
294         *
295         * <p>The message in the exception is 'The validated collection is empty'.</p>
296         * 
297         * @param collection  the collection to check is not empty
298         * @throws IllegalArgumentException if the collection is empty
299         */
300        public static void notEmpty(Collection collection) {
301            if (collection == null || collection.size() == 0) {
302                throw new IllegalArgumentException("The validated collection is empty");
303            }
304        }
305    
306        // notEmpty map
307        //---------------------------------------------------------------------------------
308    
309        /**
310         * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
311         * if the argument Map is empty (<code>null</code> or no elements).</p>
312         *
313         * <pre>
314         * Validate.notEmpty(myMap, "The map must not be empty");
315         * </pre>
316         * 
317         * @param map  the map to check is not empty
318         * @param message  the exception message you would like to see if the map is empty
319         * @throws IllegalArgumentException if the map is empty
320         */
321        public static void notEmpty(Map map, String message) {
322            if (map == null || map.size() == 0) {
323                throw new IllegalArgumentException(message);
324            }
325        }
326    
327        /**
328         * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
329         * if the argument Map is empty (<code>null</code> or no elements).</p>
330         *
331         * <pre>
332         * Validate.notEmpty(myMap);
333         * </pre>
334         *
335         * <p>The message in the exception is 'The validated map is empty'.</p>
336         * 
337         * @param map  the map to check is not empty
338         * @throws IllegalArgumentException if the map is empty
339         */
340        public static void notEmpty(Map map) {
341            if (map == null || map.size() == 0) {
342                throw new IllegalArgumentException("The validated map is empty");
343            }
344        }
345    
346        // notEmpty string
347        //---------------------------------------------------------------------------------
348    
349        /**
350         * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
351         * if the argument String is empty (<code>null</code> or zero length).</p>
352         *
353         * <pre>
354         * Validate.notEmpty(myString, "The string must not be empty");
355         * </pre>
356         * 
357         * @param string  the string to check is not empty
358         * @param message  the exception message you would like to see if the string is empty
359         * @throws IllegalArgumentException if the string is empty
360         */
361        public static void notEmpty(String string, String message) {
362            if (string == null || string.length() == 0) {
363                throw new IllegalArgumentException(message);
364            }
365        }
366    
367        /**
368         * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
369         * if the argument String is empty (<code>null</code> or zero length).</p>
370         *
371         * <pre>
372         * Validate.notEmpty(myString);
373         * </pre>
374         *
375         * <p>The message in the exception is 'The validated string is empty'.</p>
376         * 
377         * @param string  the string to check is not empty
378         * @throws IllegalArgumentException if the string is empty
379         */
380        public static void notEmpty(String string) {
381            if (string == null || string.length() == 0) {
382                throw new IllegalArgumentException("The validated string is empty");
383            }
384        }
385    
386        // notNullElements array
387        //---------------------------------------------------------------------------------
388    
389        /**
390         * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
391         * if the argument array has <code>null</code> elements or is
392         * <code>null</code>.</p>
393         *
394         * <pre>
395         * Validate.noNullElements(myArray, "The array must not contain null elements");
396         * </pre>
397         * 
398         * <p>If the array is null then the message in the exception is 'The validated object is null'.</p>
399         *
400         * @param array  the array to check
401         * @param message  the exception message if the array has
402         *  <code>null</code> elements
403         * @throws IllegalArgumentException if the array has <code>null</code>
404         *  elements or is <code>null</code>
405         */
406        public static void noNullElements(Object[] array, String message) {
407            Validate.notNull(array);
408            for (int i = 0; i < array.length; i++) {
409                if (array[i] == null) {
410                    throw new IllegalArgumentException(message);
411                }
412            }
413        }
414    
415        /**
416         * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
417         * if the argument array has <code>null</code> elements or is
418         * <code>null</code>.</p>
419         *
420         * <pre>
421         * Validate.noNullElements(myArray);
422         * </pre>
423         *
424         * <p>If the array has a null element the message in the exception is
425         * 'The validated array contains null element at index: '.</p>
426         *
427         * <p>If the array is null then the message in the exception is 'The validated object is null'.</p>
428         * 
429         * @param array  the array to check
430         * @throws IllegalArgumentException if the array has <code>null</code>
431         *  elements or is <code>null</code>
432         */
433        public static void noNullElements(Object[] array) {
434            Validate.notNull(array);
435            for (int i = 0; i < array.length; i++) {
436                if (array[i] == null) {
437                    throw new IllegalArgumentException("The validated array contains null element at index: " + i);
438                }
439            }
440        }
441    
442        // notNullElements collection
443        //---------------------------------------------------------------------------------
444    
445        /**
446         * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
447         * if the argument Collection has <code>null</code> elements or is
448         * <code>null</code>.</p>
449         *
450         * <pre>
451         * Validate.noNullElements(myCollection, "The collection must not contain null elements");
452         * </pre>
453         *
454         * <p>If the collection is null then the message in the exception is 'The validated object is null'.</p>
455         * 
456         * @param collection  the collection to check
457         * @param message  the exception message if the collection has
458         *  <code>null</code> elements
459         * @throws IllegalArgumentException if the collection has
460         *  <code>null</code> elements or is <code>null</code>
461         */
462        public static void noNullElements(Collection collection, String message) {
463            Validate.notNull(collection);
464            for (Iterator it = collection.iterator(); it.hasNext();) {
465                if (it.next() == null) {
466                    throw new IllegalArgumentException(message);
467                }
468            }
469        }
470    
471        /**
472         * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
473         * if the argument Collection has <code>null</code> elements or is
474         * <code>null</code>.</p>
475         *
476         * <pre>
477         * Validate.noNullElements(myCollection);
478         * </pre>
479         *
480         * <p>The message in the exception is 'The validated collection contains null element at index: '.</p>
481         *
482         * <p>If the collection is null then the message in the exception is 'The validated object is null'.</p>
483         * 
484         * @param collection  the collection to check
485         * @throws IllegalArgumentException if the collection has
486         *  <code>null</code> elements or is <code>null</code>
487         */
488        public static void noNullElements(Collection collection) {
489            Validate.notNull(collection);
490            int i = 0;
491            for (Iterator it = collection.iterator(); it.hasNext(); i++) {
492                if (it.next() == null) {
493                    throw new IllegalArgumentException("The validated collection contains null element at index: " + i);
494                }
495            }
496        }
497    
498        /**
499         * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
500         * if the argument collection  is <code>null</code> or has elements that
501         * are not of type <code>clazz</code> or a subclass.</p>
502         *
503         * <pre>
504         * Validate.allElementsOfType(collection, String.class, "Collection has invalid elements");
505         * </pre>
506         *
507         * @param collection  the collection to check, not null
508         * @param clazz  the <code>Class</code> which the collection's elements are expected to be, not null
509         * @param message  the exception message if the <code>Collection</code> has elements not of type <code>clazz</code>
510         * @since 2.1
511         */
512        public static void allElementsOfType(Collection collection, Class clazz, String message) {
513            Validate.notNull(collection);
514            Validate.notNull(clazz);
515            for (Iterator it = collection.iterator(); it.hasNext(); ) {
516                if (clazz.isInstance(it.next()) == false) {
517                    throw new IllegalArgumentException(message);
518                }
519            }
520        }
521    
522        /**
523         * <p>
524         * Validate an argument, throwing <code>IllegalArgumentException</code> if the argument collection is
525         * <code>null</code> or has elements that are not of type <code>clazz</code> or a subclass.
526         * </p>
527         * 
528         * <pre>
529         * Validate.allElementsOfType(collection, String.class);
530         * </pre>
531         * 
532         * <p>
533         * The message in the exception is 'The validated collection contains an element not of type clazz at index: '.
534         * </p>
535         * 
536         * @param collection
537         *            the collection to check, not null
538         * @param clazz
539         *            the <code>Class</code> which the collection's elements are expected to be, not null
540         * @since 2.1
541         */
542        public static void allElementsOfType(Collection collection, Class clazz) {
543            Validate.notNull(collection);
544            Validate.notNull(clazz);
545            int i = 0;
546            for (Iterator it = collection.iterator(); it.hasNext(); i++) {
547                if (clazz.isInstance(it.next()) == false) {
548                    throw new IllegalArgumentException("The validated collection contains an element not of type "
549                        + clazz.getName() + " at index: " + i);
550                }
551            }
552        }
553    
554    }