001    /*
002     * Licensed to the Apache Software Foundation (ASF) under one
003     * or more contributor license agreements.  See the NOTICE file
004     * distributed with this work for additional information
005     * regarding copyright ownership.  The ASF licenses this file
006     * to you under the Apache License, Version 2.0 (the
007     * "License"); you may not use this file except in compliance
008     * with the License.  You may obtain a copy of the License at
009     *
010     *   http://www.apache.org/licenses/LICENSE-2.0
011     *
012     * Unless required by applicable law or agreed to in writing,
013     * software distributed under the License is distributed on an
014     * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015     * KIND, either express or implied.  See the License for the
016     * specific language governing permissions and limitations
017     * under the License.
018     */
019    package org.apache.fulcrum.yaafi.framework.util;
020    
021    import java.util.Collection;
022    import java.util.Iterator;
023    import java.util.Map;
024    
025    /**
026     * <p>Assists in validating arguments.</p>
027     *
028     * <p>The class is based along the lines of JUnit. If an argument value is
029     * deemed invalid, an IllegalArgumentException is thrown. For example:</p>
030     *
031     * <pre>
032     * Validate.isTrue( i > 0, "The value must be greater than zero: ", i);
033     * Validate.notNull( surname, "The surname must not be null");
034     * </pre>
035     *
036     * @author <a href="mailto:ola.berg@arkitema.se">Ola Berg</a>
037     * @author Stephen Colebourne
038     * @author Gary Gregory
039     * @author Norm Deane
040     * @since 2.0
041     * @version $Id: Validate.java 535465 2007-05-05 06:58:06Z tv $
042     */
043    public class Validate
044    {
045        // Validate has no dependencies on other classes in Commons Lang at present
046    
047        /**
048         * Constructor. This class should not normally be instantiated.
049         */
050        public Validate()
051        {
052            // nothing to do
053        }
054    
055        // isTrue
056        //---------------------------------------------------------------------------------
057    
058        /**
059         * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
060         * if the test result is <code>false</code>.</p>
061         *
062         * <p>This is used when validating according to an arbitrary boolean expression,
063         * such as validating a primitive number or using your own custom validation
064         * expression.</p>
065         *
066         * <pre>
067         * Validate.isTrue( myObject.isOk(), "The object is not OK: ", myObject);
068         * </pre>
069         *
070         * <p>For performance reasons, the object is passed as a separate parameter and
071         * appended to the message string only in the case of an error.</p>
072         *
073         * @param expression  a boolean expression
074         * @param message  the exception message you would like to see if the
075         *  expression is <code>false</code>
076         * @param value  the value to append to the message in case of error
077         * @throws IllegalArgumentException if expression is <code>false</code>
078         */
079        public static void isTrue(boolean expression, String message, Object value)
080        {
081            if (expression == false)
082            {
083                throw new IllegalArgumentException( message + value );
084            }
085        }
086    
087        /**
088         * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
089         * if the test result is <code>false</code>.</p>
090         *
091         * <p>This is used when validating according to an arbitrary boolean expression,
092         * such as validating a primitive number or using your own custom validation
093         * expression.</p>
094         *
095         * <pre>
096         * Validate.isTrue( i > 0, "The value must be greater than zero: ", i);
097         * </pre>
098         *
099         * <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    }