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>This class 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 Apache Software Foundation
035     * @author <a href="mailto:ola.berg@arkitema.se">Ola Berg</a>
036     * @author Gary Gregory
037     * @author Norm Deane
038     * @since 2.0
039     * @version $Id: Validate.java 905636 2010-02-02 14:03:32Z niallp $
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         * <p>Validate that the argument condition is <code>true</code>; otherwise 
055         * throwing an exception with the specified message. This method is useful when
056         * validating according to an arbitrary boolean expression, such as validating an 
057         * object or using your own custom validation expression.</p>
058         *
059         * <pre>Validate.isTrue( myObject.isOk(), "The object is not OK: ", myObject);</pre>
060         *
061         * <p>For performance reasons, the object value is passed as a separate parameter and
062         * appended to the exception message only in the case of an error.</p>
063         * 
064         * @param expression the boolean expression to check 
065         * @param message the exception message if invalid
066         * @param value the value to append to the message when invalid
067         * @throws IllegalArgumentException if expression is <code>false</code>
068         */
069        public static void isTrue(boolean expression, String message, Object value) {
070            if (expression == false) {
071                throw new IllegalArgumentException(message + value);
072            }
073        }
074    
075        /**
076         * <p>Validate that the argument condition is <code>true</code>; otherwise 
077         * throwing an exception with the specified message. This method is useful when
078         * validating according to an arbitrary boolean expression, such as validating a 
079         * primitive number or using your own custom validation expression.</p>
080         *
081         * <pre>Validate.isTrue(i > 0.0, "The value must be greater than zero: ", i);</pre>
082         *
083         * <p>For performance reasons, the long value is passed as a separate parameter and
084         * appended to the exception message only in the case of an error.</p>
085         * 
086         * @param expression the boolean expression to check 
087         * @param message the exception message if invalid
088         * @param value the value to append to the message when invalid
089         * @throws IllegalArgumentException if expression is <code>false</code>
090         */
091        public static void isTrue(boolean expression, String message, long value) {
092            if (expression == false) {
093                throw new IllegalArgumentException(message + value);
094            }
095        }
096    
097        /**
098         * <p>Validate that the argument condition is <code>true</code>; otherwise 
099         * throwing an exception with the specified message. This method is useful when
100         * validating according to an arbitrary boolean expression, such as validating a 
101         * primitive number or using your own custom validation expression.</p>
102         *
103         * <pre>Validate.isTrue(d > 0.0, "The value must be greater than zero: ", d);</pre>
104         *
105         * <p>For performance reasons, the double value is passed as a separate parameter and
106         * appended to the exception message only in the case of an error.</p>
107         * 
108         * @param expression the boolean expression to check 
109         * @param message the exception message if invalid
110         * @param value the value to append to the message when invalid
111         * @throws IllegalArgumentException if expression is <code>false</code>
112         */
113        public static void isTrue(boolean expression, String message, double value) {
114            if (expression == false) {
115                throw new IllegalArgumentException(message + value);
116            }
117        }
118    
119        /**
120         * <p>Validate that the argument condition is <code>true</code>; otherwise 
121         * throwing an exception with the specified message. This method is useful when
122         * validating according to an arbitrary boolean expression, such as validating a 
123         * primitive number or using your own custom validation expression.</p>
124         *
125         * <pre>
126         * Validate.isTrue( (i > 0), "The value must be greater than zero");
127         * Validate.isTrue( myObject.isOk(), "The object is not OK");
128         * </pre>
129         *
130         * @param expression the boolean expression to check 
131         * @param message the exception message if invalid
132         * @throws IllegalArgumentException if expression is <code>false</code>
133         */
134        public static void isTrue(boolean expression, String message) {
135            if (expression == false) {
136                throw new IllegalArgumentException(message);
137            }
138        }
139    
140        /**
141         * <p>Validate that the argument condition is <code>true</code>; otherwise 
142         * throwing an exception. This method is useful when validating according 
143         * to an arbitrary boolean expression, such as validating a 
144         * primitive number or using your own custom validation expression.</p>
145         *
146         * <pre>
147         * Validate.isTrue(i > 0);
148         * Validate.isTrue(myObject.isOk());</pre>
149         *
150         * <p>The message of the exception is &quot;The validated expression is 
151         * false&quot;.</p>
152         * 
153         * @param expression the boolean expression to check 
154         * @throws IllegalArgumentException if expression is <code>false</code>
155         */
156        public static void isTrue(boolean expression) {
157            if (expression == false) {
158                throw new IllegalArgumentException("The validated expression is false");
159            }
160        }
161    
162        // notNull
163        //---------------------------------------------------------------------------------
164    
165        /**
166         * <p>Validate that the specified argument is not <code>null</code>; 
167         * otherwise throwing an exception.
168         *
169         * <pre>Validate.notNull(myObject);</pre>
170         *
171         * <p>The message of the exception is &quot;The validated object is 
172         * null&quot;.</p>
173         * 
174         * @param object the object to check
175         * @throws IllegalArgumentException if the object is <code>null</code>
176         */
177        public static void notNull(Object object) {
178            notNull(object, "The validated object is null");
179        }
180    
181        /**
182         * <p>Validate that the specified argument is not <code>null</code>; 
183         * otherwise throwing an exception with the specified message.
184         *
185         * <pre>Validate.notNull(myObject, "The object must not be null");</pre>
186         * 
187         * @param object the object to check
188         * @param message the exception message if invalid
189         */
190        public static void notNull(Object object, String message) {
191            if (object == null) {
192                throw new IllegalArgumentException(message);
193            }
194        }
195    
196        // notEmpty array
197        //---------------------------------------------------------------------------------
198    
199        /**
200         * <p>Validate that the specified argument array is neither <code>null</code> 
201         * nor a length of zero (no elements); otherwise throwing an exception 
202         * with the specified message.
203         *
204         * <pre>Validate.notEmpty(myArray, "The array must not be empty");</pre>
205         * 
206         * @param array the array to check
207         * @param message the exception message if invalid
208         * @throws IllegalArgumentException if the array is empty
209         */
210        public static void notEmpty(Object[] array, String message) {
211            if (array == null || array.length == 0) {
212                throw new IllegalArgumentException(message);
213            }
214        }
215    
216        /**
217         * <p>Validate that the specified argument array is neither <code>null</code> 
218         * nor a length of zero (no elements); otherwise throwing an exception. 
219         *
220         * <pre>Validate.notEmpty(myArray);</pre>
221         * 
222         * <p>The message in the exception is &quot;The validated array is 
223         * empty&quot;.
224         * 
225         * @param array the array to check
226         * @throws IllegalArgumentException if the array is empty
227         */
228        public static void notEmpty(Object[] array) {
229            notEmpty(array, "The validated array is empty");
230        }
231    
232        // notEmpty collection
233        //---------------------------------------------------------------------------------
234    
235        /**
236         * <p>Validate that the specified argument collection is neither <code>null</code> 
237         * nor a size of zero (no elements); otherwise throwing an exception 
238         * with the specified message.
239         *
240         * <pre>Validate.notEmpty(myCollection, "The collection must not be empty");</pre>
241         * 
242         * @param collection the collection to check
243         * @param message the exception message if invalid
244         * @throws IllegalArgumentException if the collection is empty
245         */
246        public static void notEmpty(Collection collection, String message) {
247            if (collection == null || collection.size() == 0) {
248                throw new IllegalArgumentException(message);
249            }
250        }
251    
252        /**
253         * <p>Validate that the specified argument collection is neither <code>null</code> 
254         * nor a size of zero (no elements); otherwise throwing an exception. 
255         *
256         * <pre>Validate.notEmpty(myCollection);</pre>
257         * 
258         * <p>The message in the exception is &quot;The validated collection is 
259         * empty&quot;.</p>
260         * 
261         * @param collection the collection to check
262         * @throws IllegalArgumentException if the collection is empty
263         */
264        public static void notEmpty(Collection collection) {
265            notEmpty(collection, "The validated collection is empty");
266        }
267    
268        // notEmpty map
269        //---------------------------------------------------------------------------------
270    
271        /**
272         * <p>Validate that the specified argument map is neither <code>null</code> 
273         * nor a size of zero (no elements); otherwise throwing an exception 
274         * with the specified message.
275         *
276         * <pre>Validate.notEmpty(myMap, "The map must not be empty");</pre>
277         * 
278         * @param map the map to check
279         * @param message the exception message if invalid
280         * @throws IllegalArgumentException if the map is empty
281         */
282        public static void notEmpty(Map map, String message) {
283            if (map == null || map.size() == 0) {
284                throw new IllegalArgumentException(message);
285            }
286        }
287    
288        /**
289         * <p>Validate that the specified argument map is neither <code>null</code> 
290         * nor a size of zero (no elements); otherwise throwing an exception. 
291         *
292         * <pre>Validate.notEmpty(myMap);</pre>
293         * 
294         * <p>The message in the exception is &quot;The validated map is 
295         * empty&quot;.</p>
296         * 
297         * @param map the map to check
298         * @throws IllegalArgumentException if the map is empty
299         * @see #notEmpty(Map, String, Object...)
300         */
301        public static void notEmpty(Map map) {
302            notEmpty(map, "The validated map is empty");
303        }
304    
305        // notEmpty string
306        //---------------------------------------------------------------------------------
307    
308        /**
309         * <p>Validate that the specified argument string is 
310         * neither <code>null</code> nor a length of zero (no characters); 
311         * otherwise throwing an exception with the specified message.
312         *
313         * <pre>Validate.notEmpty(myString, "The string must not be empty");</pre>
314         * 
315         * @param string the string to check
316         * @param message the exception message if invalid
317         * @throws IllegalArgumentException if the string is empty
318         */
319        public static void notEmpty(String string, String message) {
320            if (string == null || string.length() == 0) {
321                throw new IllegalArgumentException(message);
322            }
323        }
324    
325        /**
326         * <p>Validate that the specified argument string is 
327         * neither <code>null</code> nor a length of zero (no characters); 
328         * otherwise throwing an exception with the specified message.
329         *
330         * <pre>Validate.notEmpty(myString);</pre>
331         * 
332         * <p>The message in the exception is &quot;The validated 
333         * string is empty&quot;.</p>
334         * 
335         * @param string the string to check
336         * @throws IllegalArgumentException if the string is empty
337         */
338        public static void notEmpty(String string) {
339            notEmpty(string, "The validated string is empty");
340        }
341    
342        // notNullElements array
343        //---------------------------------------------------------------------------------
344    
345        /**
346         * <p>Validate that the specified argument array is neither 
347         * <code>null</code> nor contains any elements that are <code>null</code>;
348         * otherwise throwing an exception with the specified message.
349         *
350         * <pre>Validate.noNullElements(myArray, "The array contain null at position %d");</pre>
351         * 
352         * <p>If the array is <code>null</code>, then the message in the exception 
353         * is &quot;The validated object is null&quot;.</p>
354         *
355         * @param array the array to check
356         * @param message the exception message if the collection has <code>null</code> elements
357         * @throws IllegalArgumentException if the array is <code>null</code> or
358         * an element in the array is <code>null</code>
359         */
360        public static void noNullElements(Object[] array, String message) {
361            Validate.notNull(array);
362            for (int i = 0; i < array.length; i++) {
363                if (array[i] == null) {
364                    throw new IllegalArgumentException(message);
365                }
366            }
367        }
368    
369        /**
370         * <p>Validate that the specified argument array is neither 
371         * <code>null</code> nor contains any elements that are <code>null</code>;
372         * otherwise throwing an exception.
373         *
374         * <pre>Validate.noNullElements(myArray);</pre>
375         * 
376         * <p>If the array is <code>null</code>, then the message in the exception 
377         * is &quot;The validated object is null&quot;.</p>
378         * 
379         * <p>If the array has a <code>null</code> element, then the message in the
380         * exception is &quot;The validated array contains null element at index: 
381         * &quot followed by the index.</p>
382         *
383         * @param array the array to check
384         * @throws IllegalArgumentException if the array is <code>null</code> or
385         * an element in the array is <code>null</code>
386         */
387        public static void noNullElements(Object[] array) {
388            Validate.notNull(array);
389            for (int i = 0; i < array.length; i++) {
390                if (array[i] == null) {
391                    throw new IllegalArgumentException("The validated array contains null element at index: " + i);
392                }
393            }
394        }
395    
396        // notNullElements collection
397        //---------------------------------------------------------------------------------
398    
399        /**
400         * <p>Validate that the specified argument collection is neither 
401         * <code>null</code> nor contains any elements that are <code>null</code>;
402         * otherwise throwing an exception with the specified message.
403         *
404         * <pre>Validate.noNullElements(myCollection, "The collection contains null elements");</pre>
405         * 
406         * <p>If the collection is <code>null</code>, then the message in the exception 
407         * is &quot;The validated object is null&quot;.</p>
408         * 
409         *
410         * @param collection  the collection to check
411         * @param message  the exception message if the collection has
412         * @throws IllegalArgumentException if the collection is <code>null</code> or
413         * an element in the collection is <code>null</code>
414         */
415        public static void noNullElements(Collection collection, String message) {
416            Validate.notNull(collection);
417            for (Iterator it = collection.iterator(); it.hasNext();) {
418                if (it.next() == null) {
419                    throw new IllegalArgumentException(message);
420                }
421            }
422        }
423    
424        /**
425         * <p>Validate that the specified argument collection is neither 
426         * <code>null</code> nor contains any elements that are <code>null</code>;
427         * otherwise throwing an exception.
428         *
429         * <pre>Validate.noNullElements(myCollection);</pre>
430         * 
431         * <p>If the collection is <code>null</code>, then the message in the exception 
432         * is &quot;The validated object is null&quot;.</p>
433         * 
434         * <p>If the collection has a <code>null</code> element, then the message in the
435         * exception is &quot;The validated collection contains null element at index: 
436         * &quot followed by the index.</p>
437         *
438         * @param collection  the collection to check
439         * @throws IllegalArgumentException if the collection is <code>null</code> or
440         * an element in the collection is <code>null</code>
441         */
442        public static void noNullElements(Collection collection) {
443            Validate.notNull(collection);
444            int i = 0;
445            for (Iterator it = collection.iterator(); it.hasNext(); i++) {
446                if (it.next() == null) {
447                    throw new IllegalArgumentException("The validated collection contains null element at index: " + i);
448                }
449            }
450        }
451    
452        /**
453         * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
454         * if the argument collection  is <code>null</code> or has elements that
455         * are not of type <code>clazz</code> or a subclass.</p>
456         *
457         * <pre>
458         * Validate.allElementsOfType(collection, String.class, "Collection has invalid elements");
459         * </pre>
460         *
461         * @param collection  the collection to check, not null
462         * @param clazz  the <code>Class</code> which the collection's elements are expected to be, not null
463         * @param message  the exception message if the <code>Collection</code> has elements not of type <code>clazz</code>
464         * @since 2.1
465         */
466        public static void allElementsOfType(Collection collection, Class clazz, String message) {
467            Validate.notNull(collection);
468            Validate.notNull(clazz);
469            for (Iterator it = collection.iterator(); it.hasNext(); ) {
470                if (clazz.isInstance(it.next()) == false) {
471                    throw new IllegalArgumentException(message);
472                }
473            }
474        }
475    
476        /**
477         * <p>
478         * Validate an argument, throwing <code>IllegalArgumentException</code> if the argument collection is
479         * <code>null</code> or has elements that are not of type <code>clazz</code> or a subclass.
480         * </p>
481         * 
482         * <pre>
483         * Validate.allElementsOfType(collection, String.class);
484         * </pre>
485         * 
486         * <p>
487         * The message in the exception is 'The validated collection contains an element not of type clazz at index: '.
488         * </p>
489         * 
490         * @param collection  the collection to check, not null
491         * @param clazz  the <code>Class</code> which the collection's elements are expected to be, not null
492         * @since 2.1
493         */
494        public static void allElementsOfType(Collection collection, Class clazz) {
495            Validate.notNull(collection);
496            Validate.notNull(clazz);
497            int i = 0;
498            for (Iterator it = collection.iterator(); it.hasNext(); i++) {
499                if (clazz.isInstance(it.next()) == false) {
500                    throw new IllegalArgumentException("The validated collection contains an element not of type "
501                        + clazz.getName() + " at index: " + i);
502                }
503            }
504        }
505    
506    }