    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 1057051 2011-01-09 23:15:51Z sebb $
    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)
    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    }