    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.lang3;
    018
    019    import java.util.Collection;
    020    import java.util.Iterator;
    021    import java.util.Map;
    022    import java.util.regex.Pattern;
    023
    024    /**
    025     * <p>This class assists in validating arguments. The validation methods are
    026     * based along the following principles:
    027     * <ul>
    028     *   <li>An invalid {@code null} argument causes a {@link NullPointerException}.</li>
    029     *   <li>A non-{@code null} argument causes an {@link IllegalArgumentException}.</li>
    030     *   <li>An invalid index into an array/collection/map/string causes an {@link IndexOutOfBoundsException}.</li>
    031     * </ul>
    032     *
    033     * <p>All exceptions messages are
    034     * <a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Formatter.html#syntax">format strings</a>
    035     * as defined by the Java platform. For example:</p>
    036     *
    037     * <pre>
    038     * Validate.isTrue(i > 0, "The value must be greater than zero: %d", i);
    039     * Validate.notNull(surname, "The surname must not be %s", null);
    040     * </pre>
    041     *
    042     * <p>#ThreadSafe#</p>
    043     * @version $Id: Validate.java 1199983 2011-11-09 21:41:24Z ggregory $
    044     * @see java.lang.String#format(String, Object...)
    045     * @since 2.0
    046     */
    047    public class Validate {
    048
    049        private static final String DEFAULT_EXCLUSIVE_BETWEEN_EX_MESSAGE =
    050            "The value %s is not in the specified exclusive range of %s to %s";
    051        private static final String DEFAULT_INCLUSIVE_BETWEEN_EX_MESSAGE =
    052            "The value %s is not in the specified inclusive range of %s to %s";
    053        private static final String DEFAULT_MATCHES_PATTERN_EX = "The string %s does not match the pattern %s";
    054        private static final String DEFAULT_IS_NULL_EX_MESSAGE = "The validated object is null";
    055        private static final String DEFAULT_IS_TRUE_EX_MESSAGE = "The validated expression is false";
    056        private static final String DEFAULT_NO_NULL_ELEMENTS_ARRAY_EX_MESSAGE =
    057            "The validated array contains null element at index: %d";
    058        private static final String DEFAULT_NO_NULL_ELEMENTS_COLLECTION_EX_MESSAGE =
    059            "The validated collection contains null element at index: %d";
    060        private static final String DEFAULT_NOT_BLANK_EX_MESSAGE = "The validated character sequence is blank";
    061        private static final String DEFAULT_NOT_EMPTY_ARRAY_EX_MESSAGE = "The validated array is empty";
    062        private static final String DEFAULT_NOT_EMPTY_CHAR_SEQUENCE_EX_MESSAGE =
    063            "The validated character sequence is empty";
    064        private static final String DEFAULT_NOT_EMPTY_COLLECTION_EX_MESSAGE = "The validated collection is empty";
    065        private static final String DEFAULT_NOT_EMPTY_MAP_EX_MESSAGE = "The validated map is empty";
    066        private static final String DEFAULT_VALID_INDEX_ARRAY_EX_MESSAGE = "The validated array index is invalid: %d";
    067        private static final String DEFAULT_VALID_INDEX_CHAR_SEQUENCE_EX_MESSAGE =
    068            "The validated character sequence index is invalid: %d";
    069        private static final String DEFAULT_VALID_INDEX_COLLECTION_EX_MESSAGE =
    070            "The validated collection index is invalid: %d";
    071        private static final String DEFAULT_VALID_STATE_EX_MESSAGE = "The validated state is false";
    072        private static final String DEFAULT_IS_ASSIGNABLE_EX_MESSAGE = "Cannot assign a %s to a %s";
    073        private static final String DEFAULT_IS_INSTANCE_OF_EX_MESSAGE = "Expected type: %s, actual: %s";
    074
    075        /**
    076         * Constructor. This class should not normally be instantiated.
    077         */
    078        public Validate() {
    079          super();
    080        }
    081
    082        // isTrue
    083        //---------------------------------------------------------------------------------
    084
    085        /**
    086         * <p>Validate that the argument condition is {@code true}; otherwise
    087         * throwing an exception with the specified message. This method is useful when
    088         * validating according to an arbitrary boolean expression, such as validating a
    089         * primitive number or using your own custom validation expression.</p>
    090         *
    091         * <pre>Validate.isTrue(i > 0.0, "The value must be greater than zero: %d", i);</pre>
    092         *
    093         * <p>For performance reasons, the long value is passed as a separate parameter and
    094         * appended to the exception message only in the case of an error.</p>
    095         *
    096         * @param expression  the boolean expression to check
    097         * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
    098         * @param value  the value to append to the message when invalid
    099         * @throws IllegalArgumentException if expression is {@code false}
    100         * @see #isTrue(boolean)
    101         * @see #isTrue(boolean, String, double)
    102         * @see #isTrue(boolean, String, Object...)
    103         */
    104        public static void isTrue(boolean expression, String message, long value) {
    105            if (expression == false) {
    106                throw new IllegalArgumentException(String.format(message, Long.valueOf(value)));
    107            }
    108        }
    109
    110        /**
    111         * <p>Validate that the argument condition is {@code true}; otherwise
    112         * throwing an exception with the specified message. This method is useful when
    113         * validating according to an arbitrary boolean expression, such as validating a
    114         * primitive number or using your own custom validation expression.</p>
    115         *
    116         * <pre>Validate.isTrue(d > 0.0, "The value must be greater than zero: %s", d);</pre>
    117         *
    118         * <p>For performance reasons, the double value is passed as a separate parameter and
    119         * appended to the exception message only in the case of an error.</p>
    120         *
    121         * @param expression  the boolean expression to check
    122         * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
    123         * @param value  the value to append to the message when invalid
    124         * @throws IllegalArgumentException if expression is {@code false}
    125         * @see #isTrue(boolean)
    126         * @see #isTrue(boolean, String, long)
    127         * @see #isTrue(boolean, String, Object...)
    128         */
    129        public static void isTrue(boolean expression, String message, double value) {
    130            if (expression == false) {
    131                throw new IllegalArgumentException(String.format(message, Double.valueOf(value)));
    132            }
    133        }
    134
    135        /**
    136         * <p>Validate that the argument condition is {@code true}; otherwise
    137         * throwing an exception with the specified message. This method is useful when
    138         * validating according to an arbitrary boolean expression, such as validating a
    139         * primitive number or using your own custom validation expression.</p>
    140         *
    141         * <pre>
    142         * Validate.isTrue(i >= min && i <= max, "The value must be between %d and %d", min, max);
    143         * Validate.isTrue(myObject.isOk(), "The object is not okay");</pre>
    144         *
    145         * @param expression  the boolean expression to check
    146         * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
    147         * @param values  the optional values for the formatted exception message, null array not recommended
    148         * @throws IllegalArgumentException if expression is {@code false}
    149         * @see #isTrue(boolean)
    150         * @see #isTrue(boolean, String, long)
    151         * @see #isTrue(boolean, String, double)
    152         */
    153        public static void isTrue(boolean expression, String message, Object... values) {
    154            if (expression == false) {
    155                throw new IllegalArgumentException(String.format(message, values));
    156            }
    157        }
    158
    159        /**
    160         * <p>Validate that the argument condition is {@code true}; otherwise
    161         * throwing an exception. This method is useful when validating according
    162         * to an arbitrary boolean expression, such as validating a
    163         * primitive number or using your own custom validation expression.</p>
    164         *
    165         * <pre>
    166         * Validate.isTrue(i > 0);
    167         * Validate.isTrue(myObject.isOk());</pre>
    168         *
    169         * <p>The message of the exception is &quot;The validated expression is
    170         * false&quot;.</p>
    171         *
    172         * @param expression  the boolean expression to check
    173         * @throws IllegalArgumentException if expression is {@code false}
    174         * @see #isTrue(boolean, String, long)
    175         * @see #isTrue(boolean, String, double)
    176         * @see #isTrue(boolean, String, Object...)
    177         */
    178        public static void isTrue(boolean expression) {
    179            if (expression == false) {
    180                throw new IllegalArgumentException(DEFAULT_IS_TRUE_EX_MESSAGE);
    181            }
    182        }
    183
    184        // notNull
    185        //---------------------------------------------------------------------------------
    186
    187        /**
    188         * <p>Validate that the specified argument is not {@code null};
    189         * otherwise throwing an exception.
    190         *
    191         * <pre>Validate.notNull(myObject, "The object must not be null");</pre>
    192         *
    193         * <p>The message of the exception is &quot;The validated object is
    194         * null&quot;.</p>
    195         *
    196         * @param <T> the object type
    197         * @param object  the object to check
    198         * @return the validated object (never {@code null} for method chaining)
    199         * @throws NullPointerException if the object is {@code null}
    200         * @see #notNull(Object, String, Object...)
    201         */
    202        public static <T> T notNull(T object) {
    203            return notNull(object, DEFAULT_IS_NULL_EX_MESSAGE);
    204        }
    205
    206        /**
    207         * <p>Validate that the specified argument is not {@code null};
    208         * otherwise throwing an exception with the specified message.
    209         *
    210         * <pre>Validate.notNull(myObject, "The object must not be null");</pre>
    211         *
    212         * @param <T> the object type
    213         * @param object  the object to check
    214         * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
    215         * @param values  the optional values for the formatted exception message
    216         * @return the validated object (never {@code null} for method chaining)
    217         * @throws NullPointerException if the object is {@code null}
    218         * @see #notNull(Object)
    219         */
    220        public static <T> T notNull(T object, String message, Object... values) {
    221            if (object == null) {
    222                throw new NullPointerException(String.format(message, values));
    223            }
    224            return object;
    225        }
    226
    227        // notEmpty array
    228        //---------------------------------------------------------------------------------
    229
    230        /**
    231         * <p>Validate that the specified argument array is neither {@code null}
    232         * nor a length of zero (no elements); otherwise throwing an exception
    233         * with the specified message.
    234         *
    235         * <pre>Validate.notEmpty(myArray, "The array must not be empty");</pre>
    236         *
    237         * @param <T> the array type
    238         * @param array  the array to check, validated not null by this method
    239         * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
    240         * @param values  the optional values for the formatted exception message, null array not recommended
    241         * @return the validated array (never {@code null} method for chaining)
    242         * @throws NullPointerException if the array is {@code null}
    243         * @throws IllegalArgumentException if the array is empty
    244         * @see #notEmpty(Object[])
    245         */
    246        public static <T> T[] notEmpty(T[] array, String message, Object... values) {
    247            if (array == null) {
    248                throw new NullPointerException(String.format(message, values));
    249            }
    250            if (array.length == 0) {
    251                throw new IllegalArgumentException(String.format(message, values));
    252            }
    253            return array;
    254        }
    255
    256        /**
    257         * <p>Validate that the specified argument array is neither {@code null}
    258         * nor a length of zero (no elements); otherwise throwing an exception.
    259         *
    260         * <pre>Validate.notEmpty(myArray);</pre>
    261         *
    262         * <p>The message in the exception is &quot;The validated array is
    263         * empty&quot;.
    264         *
    265         * @param <T> the array type
    266         * @param array  the array to check, validated not null by this method
    267         * @return the validated array (never {@code null} method for chaining)
    268         * @throws NullPointerException if the array is {@code null}
    269         * @throws IllegalArgumentException if the array is empty
    270         * @see #notEmpty(Object[], String, Object...)
    271         */
    272        public static <T> T[] notEmpty(T[] array) {
    273            return notEmpty(array, DEFAULT_NOT_EMPTY_ARRAY_EX_MESSAGE);
    274        }
    275
    276        // notEmpty collection
    277        //---------------------------------------------------------------------------------
    278
    279        /**
    280         * <p>Validate that the specified argument collection is neither {@code null}
    281         * nor a size of zero (no elements); otherwise throwing an exception
    282         * with the specified message.
    283         *
    284         * <pre>Validate.notEmpty(myCollection, "The collection must not be empty");</pre>
    285         *
    286         * @param <T> the collection type
    287         * @param collection  the collection to check, validated not null by this method
    288         * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
    289         * @param values  the optional values for the formatted exception message, null array not recommended
    290         * @return the validated collection (never {@code null} method for chaining)
    291         * @throws NullPointerException if the collection is {@code null}
    292         * @throws IllegalArgumentException if the collection is empty
    293         * @see #notEmpty(Object[])
    294         */
    295        public static <T extends Collection<?>> T notEmpty(T collection, String message, Object... values) {
    296            if (collection == null) {
    297                throw new NullPointerException(String.format(message, values));
    298            }
    299            if (collection.isEmpty()) {
    300                throw new IllegalArgumentException(String.format(message, values));
    301            }
    302            return collection;
    303        }
    304
    305        /**
    306         * <p>Validate that the specified argument collection is neither {@code null}
    307         * nor a size of zero (no elements); otherwise throwing an exception.
    308         *
    309         * <pre>Validate.notEmpty(myCollection);</pre>
    310         *
    311         * <p>The message in the exception is &quot;The validated collection is
    312         * empty&quot;.</p>
    313         *
    314         * @param <T> the collection type
    315         * @param collection  the collection to check, validated not null by this method
    316         * @return the validated collection (never {@code null} method for chaining)
    317         * @throws NullPointerException if the collection is {@code null}
    318         * @throws IllegalArgumentException if the collection is empty
    319         * @see #notEmpty(Collection, String, Object...)
    320         */
    321        public static <T extends Collection<?>> T notEmpty(T collection) {
    322            return notEmpty(collection, DEFAULT_NOT_EMPTY_COLLECTION_EX_MESSAGE);
    323        }
    324
    325        // notEmpty map
    326        //---------------------------------------------------------------------------------
    327
    328        /**
    329         * <p>Validate that the specified argument map is neither {@code null}
    330         * nor a size of zero (no elements); otherwise throwing an exception
    331         * with the specified message.
    332         *
    333         * <pre>Validate.notEmpty(myMap, "The map must not be empty");</pre>
    334         *
    335         * @param <T> the map type
    336         * @param map  the map to check, validated not null by this method
    337         * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
    338         * @param values  the optional values for the formatted exception message, null array not recommended
    339         * @return the validated map (never {@code null} method for chaining)
    340         * @throws NullPointerException if the map is {@code null}
    341         * @throws IllegalArgumentException if the map is empty
    342         * @see #notEmpty(Object[])
    343         */
    344        public static <T extends Map<?, ?>> T notEmpty(T map, String message, Object... values) {
    345            if (map == null) {
    346                throw new NullPointerException(String.format(message, values));
    347            }
    348            if (map.isEmpty()) {
    349                throw new IllegalArgumentException(String.format(message, values));
    350            }
    351            return map;
    352        }
    353
    354        /**
    355         * <p>Validate that the specified argument map is neither {@code null}
    356         * nor a size of zero (no elements); otherwise throwing an exception.
    357         *
    358         * <pre>Validate.notEmpty(myMap);</pre>
    359         *
    360         * <p>The message in the exception is &quot;The validated map is
    361         * empty&quot;.</p>
    362         *
    363         * @param <T> the map type
    364         * @param map  the map to check, validated not null by this method
    365         * @return the validated map (never {@code null} method for chaining)
    366         * @throws NullPointerException if the map is {@code null}
    367         * @throws IllegalArgumentException if the map is empty
    368         * @see #notEmpty(Map, String, Object...)
    369         */
    370        public static <T extends Map<?, ?>> T notEmpty(T map) {
    371            return notEmpty(map, DEFAULT_NOT_EMPTY_MAP_EX_MESSAGE);
    372        }
    373
    374        // notEmpty string
    375        //---------------------------------------------------------------------------------
    376
    377        /**
    378         * <p>Validate that the specified argument character sequence is
    379         * neither {@code null} nor a length of zero (no characters);
    380         * otherwise throwing an exception with the specified message.
    381         *
    382         * <pre>Validate.notEmpty(myString, "The string must not be empty");</pre>
    383         *
    384         * @param <T> the character sequence type
    385         * @param chars  the character sequence to check, validated not null by this method
    386         * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
    387         * @param values  the optional values for the formatted exception message, null array not recommended
    388         * @return the validated character sequence (never {@code null} method for chaining)
    389         * @throws NullPointerException if the character sequence is {@code null}
    390         * @throws IllegalArgumentException if the character sequence is empty
    391         * @see #notEmpty(CharSequence)
    392         */
    393        public static <T extends CharSequence> T notEmpty(T chars, String message, Object... values) {
    394            if (chars == null) {
    395                throw new NullPointerException(String.format(message, values));
    396            }
    397            if (chars.length() == 0) {
    398                throw new IllegalArgumentException(String.format(message, values));
    399            }
    400            return chars;
    401        }
    402
    403        /**
    404         * <p>Validate that the specified argument character sequence is
    405         * neither {@code null} nor a length of zero (no characters);
    406         * otherwise throwing an exception with the specified message.
    407         *
    408         * <pre>Validate.notEmpty(myString);</pre>
    409         *
    410         * <p>The message in the exception is &quot;The validated
    411         * character sequence is empty&quot;.</p>
    412         *
    413         * @param <T> the character sequence type
    414         * @param chars  the character sequence to check, validated not null by this method
    415         * @return the validated character sequence (never {@code null} method for chaining)
    416         * @throws NullPointerException if the character sequence is {@code null}
    417         * @throws IllegalArgumentException if the character sequence is empty
    418         * @see #notEmpty(CharSequence, String, Object...)
    419         */
    420        public static <T extends CharSequence> T notEmpty(T chars) {
    421            return notEmpty(chars, DEFAULT_NOT_EMPTY_CHAR_SEQUENCE_EX_MESSAGE);
    422        }
    423
    424        // notBlank string
    425        //---------------------------------------------------------------------------------
    426
    427        /**
    428         * <p>Validate that the specified argument character sequence is
    429         * neither {@code null}, a length of zero (no characters), empty
    430         * nor whitespace; otherwise throwing an exception with the specified
    431         * message.
    432         *
    433         * <pre>Validate.notBlank(myString, "The string must not be blank");</pre>
    434         *
    435         * @param <T> the character sequence type
    436         * @param chars  the character sequence to check, validated not null by this method
    437         * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
    438         * @param values  the optional values for the formatted exception message, null array not recommended
    439         * @return the validated character sequence (never {@code null} method for chaining)
    440         * @throws NullPointerException if the character sequence is {@code null}
    441         * @throws IllegalArgumentException if the character sequence is blank
    442         * @see #notBlank(CharSequence)
    443         *
    444         * @since 3.0
    445         */
    446        public static <T extends CharSequence> T notBlank(T chars, String message, Object... values) {
    447            if (chars == null) {
    448                throw new NullPointerException(String.format(message, values));
    449            }
    450            if (StringUtils.isBlank(chars)) {
    451                throw new IllegalArgumentException(String.format(message, values));
    452            }
    453            return chars;
    454        }
    455
    456        /**
    457         * <p>Validate that the specified argument character sequence is
    458         * neither {@code null}, a length of zero (no characters), empty
    459         * nor whitespace; otherwise throwing an exception.
    460         *
    461         * <pre>Validate.notBlank(myString);</pre>
    462         *
    463         * <p>The message in the exception is &quot;The validated character
    464         * sequence is blank&quot;.</p>
    465         *
    466         * @param <T> the character sequence type
    467         * @param chars  the character sequence to check, validated not null by this method
    468         * @return the validated character sequence (never {@code null} method for chaining)
    469         * @throws NullPointerException if the character sequence is {@code null}
    470         * @throws IllegalArgumentException if the character sequence is blank
    471         * @see #notBlank(CharSequence, String, Object...)
    472         *
    473         * @since 3.0
    474         */
    475        public static <T extends CharSequence> T notBlank(T chars) {
    476            return notBlank(chars, DEFAULT_NOT_BLANK_EX_MESSAGE);
    477        }
    478
    479        // noNullElements array
    480        //---------------------------------------------------------------------------------
    481
    482        /**
    483         * <p>Validate that the specified argument array is neither
    484         * {@code null} nor contains any elements that are {@code null};
    485         * otherwise throwing an exception with the specified message.
    486         *
    487         * <pre>Validate.noNullElements(myArray, "The array contain null at position %d");</pre>
    488         *
    489         * <p>If the array is {@code null}, then the message in the exception
    490         * is &quot;The validated object is null&quot;.</p>
    491         *
    492         * <p>If the array has a {@code null} element, then the iteration
    493         * index of the invalid element is appended to the {@code values}
    494         * argument.</p>
    495         *
    496         * @param <T> the array type
    497         * @param array  the array to check, validated not null by this method
    498         * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
    499         * @param values  the optional values for the formatted exception message, null array not recommended
    500         * @return the validated array (never {@code null} method for chaining)
    501         * @throws NullPointerException if the array is {@code null}
    502         * @throws IllegalArgumentException if an element is {@code null}
    503         * @see #noNullElements(Object[])
    504         */
    505        public static <T> T[] noNullElements(T[] array, String message, Object... values) {
    506            Validate.notNull(array);
    507            for (int i = 0; i < array.length; i++) {
    508                if (array[i] == null) {
    509                    Object[] values2 = ArrayUtils.add(values, Integer.valueOf(i));
    510                    throw new IllegalArgumentException(String.format(message, values2));
    511                }
    512            }
    513            return array;
    514        }
    515
    516        /**
    517         * <p>Validate that the specified argument array is neither
    518         * {@code null} nor contains any elements that are {@code null};
    519         * otherwise throwing an exception.
    520         *
    521         * <pre>Validate.noNullElements(myArray);</pre>
    522         *
    523         * <p>If the array is {@code null}, then the message in the exception
    524         * is &quot;The validated object is null&quot;.</p>
    525         *
    526         * <p>If the array has a {@code null} element, then the message in the
    527         * exception is &quot;The validated array contains null element at index:
    528         * &quot followed by the index.</p>
    529         *
    530         * @param <T> the array type
    531         * @param array  the array to check, validated not null by this method
    532         * @return the validated array (never {@code null} method for chaining)
    533         * @throws NullPointerException if the array is {@code null}
    534         * @throws IllegalArgumentException if an element is {@code null}
    535         * @see #noNullElements(Object[], String, Object...)
    536         */
    537        public static <T> T[] noNullElements(T[] array) {
    538            return noNullElements(array, DEFAULT_NO_NULL_ELEMENTS_ARRAY_EX_MESSAGE);
    539        }
    540
    541        // noNullElements iterable
    542        //---------------------------------------------------------------------------------
    543
    544        /**
    545         * <p>Validate that the specified argument iterable is neither
    546         * {@code null} nor contains any elements that are {@code null};
    547         * otherwise throwing an exception with the specified message.
    548         *
    549         * <pre>Validate.noNullElements(myCollection, "The collection contains null at position %d");</pre>
    550         *
    551         * <p>If the iterable is {@code null}, then the message in the exception
    552         * is &quot;The validated object is null&quot;.</p>
    553         *
    554         * <p>If the iterable has a {@code null} element, then the iteration
    555         * index of the invalid element is appended to the {@code values}
    556         * argument.</p>
    557         *
    558         * @param <T> the iterable type
    559         * @param iterable  the iterable to check, validated not null by this method
    560         * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
    561         * @param values  the optional values for the formatted exception message, null array not recommended
    562         * @return the validated iterable (never {@code null} method for chaining)
    563         * @throws NullPointerException if the array is {@code null}
    564         * @throws IllegalArgumentException if an element is {@code null}
    565         * @see #noNullElements(Iterable)
    566         */
    567        public static <T extends Iterable<?>> T noNullElements(T iterable, String message, Object... values) {
    568            Validate.notNull(iterable);
    569            int i = 0;
    570            for (Iterator<?> it = iterable.iterator(); it.hasNext(); i++) {
    571                if (it.next() == null) {
    572                    Object[] values2 = ArrayUtils.addAll(values, Integer.valueOf(i));
    573                    throw new IllegalArgumentException(String.format(message, values2));
    574                }
    575            }
    576            return iterable;
    577        }
    578
    579        /**
    580         * <p>Validate that the specified argument iterable is neither
    581         * {@code null} nor contains any elements that are {@code null};
    582         * otherwise throwing an exception.
    583         *
    584         * <pre>Validate.noNullElements(myCollection);</pre>
    585         *
    586         * <p>If the iterable is {@code null}, then the message in the exception
    587         * is &quot;The validated object is null&quot;.</p>
    588         *
    589         * <p>If the array has a {@code null} element, then the message in the
    590         * exception is &quot;The validated iterable contains null element at index:
    591         * &quot followed by the index.</p>
    592         *
    593         * @param <T> the iterable type
    594         * @param iterable  the iterable to check, validated not null by this method
    595         * @return the validated iterable (never {@code null} method for chaining)
    596         * @throws NullPointerException if the array is {@code null}
    597         * @throws IllegalArgumentException if an element is {@code null}
    598         * @see #noNullElements(Iterable, String, Object...)
    599         */
    600        public static <T extends Iterable<?>> T noNullElements(T iterable) {
    601            return noNullElements(iterable, DEFAULT_NO_NULL_ELEMENTS_COLLECTION_EX_MESSAGE);
    602        }
    603
    604        // validIndex array
    605        //---------------------------------------------------------------------------------
    606
    607        /**
    608         * <p>Validates that the index is within the bounds of the argument
    609         * array; otherwise throwing an exception with the specified message.</p>
    610         *
    611         * <pre>Validate.validIndex(myArray, 2, "The array index is invalid: ");</pre>
    612         *
    613         * <p>If the array is {@code null}, then the message of the exception
    614         * is &quot;The validated object is null&quot;.</p>
    615         *
    616         * @param <T> the array type
    617         * @param array  the array to check, validated not null by this method
    618         * @param index  the index to check
    619         * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
    620         * @param values  the optional values for the formatted exception message, null array not recommended
    621         * @return the validated array (never {@code null} for method chaining)
    622         * @throws NullPointerException if the array is {@code null}
    623         * @throws IndexOutOfBoundsException if the index is invalid
    624         * @see #validIndex(Object[], int)
    625         *
    626         * @since 3.0
    627         */
    628        public static <T> T[] validIndex(T[] array, int index, String message, Object... values) {
    629            Validate.notNull(array);
    630            if (index < 0 || index >= array.length) {
    631                throw new IndexOutOfBoundsException(String.format(message, values));
    632            }
    633            return array;
    634        }
    635
    636        /**
    637         * <p>Validates that the index is within the bounds of the argument
    638         * array; otherwise throwing an exception.</p>
    639         *
    640         * <pre>Validate.validIndex(myArray, 2);</pre>
    641         *
    642         * <p>If the array is {@code null}, then the message of the exception
    643         * is &quot;The validated object is null&quot;.</p>
    644         *
    645         * <p>If the index is invalid, then the message of the exception is
    646         * &quot;The validated array index is invalid: &quot; followed by the
    647         * index.</p>
    648         *
    649         * @param <T> the array type
    650         * @param array  the array to check, validated not null by this method
    651         * @param index  the index to check
    652         * @return the validated array (never {@code null} for method chaining)
    653         * @throws NullPointerException if the array is {@code null}
    654         * @throws IndexOutOfBoundsException if the index is invalid
    655         * @see #validIndex(Object[], int, String, Object...)
    656         *
    657         * @since 3.0
    658         */
    659        public static <T> T[] validIndex(T[] array, int index) {
    660            return validIndex(array, index, DEFAULT_VALID_INDEX_ARRAY_EX_MESSAGE, Integer.valueOf(index));
    661        }
    662
    663        // validIndex collection
    664        //---------------------------------------------------------------------------------
    665
    666        /**
    667         * <p>Validates that the index is within the bounds of the argument
    668         * collection; otherwise throwing an exception with the specified message.</p>
    669         *
    670         * <pre>Validate.validIndex(myCollection, 2, "The collection index is invalid: ");</pre>
    671         *
    672         * <p>If the collection is {@code null}, then the message of the
    673         * exception is &quot;The validated object is null&quot;.</p>
    674         *
    675         * @param <T> the collection type
    676         * @param collection  the collection to check, validated not null by this method
    677         * @param index  the index to check
    678         * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
    679         * @param values  the optional values for the formatted exception message, null array not recommended
    680         * @return the validated collection (never {@code null} for chaining)
    681         * @throws NullPointerException if the collection is {@code null}
    682         * @throws IndexOutOfBoundsException if the index is invalid
    683         * @see #validIndex(Collection, int)
    684         *
    685         * @since 3.0
    686         */
    687        public static <T extends Collection<?>> T validIndex(T collection, int index, String message, Object... values) {
    688            Validate.notNull(collection);
    689            if (index < 0 || index >= collection.size()) {
    690                throw new IndexOutOfBoundsException(String.format(message, values));
    691            }
    692            return collection;
    693        }
    694
    695        /**
    696         * <p>Validates that the index is within the bounds of the argument
    697         * collection; otherwise throwing an exception.</p>
    698         *
    699         * <pre>Validate.validIndex(myCollection, 2);</pre>
    700         *
    701         * <p>If the index is invalid, then the message of the exception
    702         * is &quot;The validated collection index is invalid: &quot;
    703         * followed by the index.</p>
    704         *
    705         * @param <T> the collection type
    706         * @param collection  the collection to check, validated not null by this method
    707         * @param index  the index to check
    708         * @return the validated collection (never {@code null} for method chaining)
    709         * @throws NullPointerException if the collection is {@code null}
    710         * @throws IndexOutOfBoundsException if the index is invalid
    711         * @see #validIndex(Collection, int, String, Object...)
    712         *
    713         * @since 3.0
    714         */
    715        public static <T extends Collection<?>> T validIndex(T collection, int index) {
    716            return validIndex(collection, index, DEFAULT_VALID_INDEX_COLLECTION_EX_MESSAGE, Integer.valueOf(index));
    717        }
    718
    719        // validIndex string
    720        //---------------------------------------------------------------------------------
    721
    722        /**
    723         * <p>Validates that the index is within the bounds of the argument
    724         * character sequence; otherwise throwing an exception with the
    725         * specified message.</p>
    726         *
    727         * <pre>Validate.validIndex(myStr, 2, "The string index is invalid: ");</pre>
    728         *
    729         * <p>If the character sequence is {@code null}, then the message
    730         * of the exception is &quot;The validated object is null&quot;.</p>
    731         *
    732         * @param <T> the character sequence type
    733         * @param chars  the character sequence to check, validated not null by this method
    734         * @param index  the index to check
    735         * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
    736         * @param values  the optional values for the formatted exception message, null array not recommended
    737         * @return the validated character sequence (never {@code null} for method chaining)
    738         * @throws NullPointerException if the character sequence is {@code null}
    739         * @throws IndexOutOfBoundsException if the index is invalid
    740         * @see #validIndex(CharSequence, int)
    741         *
    742         * @since 3.0
    743         */
    744        public static <T extends CharSequence> T validIndex(T chars, int index, String message, Object... values) {
    745            Validate.notNull(chars);
    746            if (index < 0 || index >= chars.length()) {
    747                throw new IndexOutOfBoundsException(String.format(message, values));
    748            }
    749            return chars;
    750        }
    751
    752        /**
    753         * <p>Validates that the index is within the bounds of the argument
    754         * character sequence; otherwise throwing an exception.</p>
    755         *
    756         * <pre>Validate.validIndex(myStr, 2);</pre>
    757         *
    758         * <p>If the character sequence is {@code null}, then the message
    759         * of the exception is &quot;The validated object is
    760         * null&quot;.</p>
    761         *
    762         * <p>If the index is invalid, then the message of the exception
    763         * is &quot;The validated character sequence index is invalid: &quot;
    764         * followed by the index.</p>
    765         *
    766         * @param <T> the character sequence type
    767         * @param chars  the character sequence to check, validated not null by this method
    768         * @param index  the index to check
    769         * @return the validated character sequence (never {@code null} for method chaining)
    770         * @throws NullPointerException if the character sequence is {@code null}
    771         * @throws IndexOutOfBoundsException if the index is invalid
    772         * @see #validIndex(CharSequence, int, String, Object...)
    773         *
    774         * @since 3.0
    775         */
    776        public static <T extends CharSequence> T validIndex(T chars, int index) {
    777            return validIndex(chars, index, DEFAULT_VALID_INDEX_CHAR_SEQUENCE_EX_MESSAGE, Integer.valueOf(index));
    778        }
    779
    780        // validState
    781        //---------------------------------------------------------------------------------
    782
    783        /**
    784         * <p>Validate that the stateful condition is {@code true}; otherwise
    785         * throwing an exception. This method is useful when validating according
    786         * to an arbitrary boolean expression, such as validating a
    787         * primitive number or using your own custom validation expression.</p>
    788         *
    789         * <pre>
    790         * Validate.validState(field > 0);
    791         * Validate.validState(this.isOk());</pre>
    792         *
    793         * <p>The message of the exception is &quot;The validated state is
    794         * false&quot;.</p>
    795         *
    796         * @param expression  the boolean expression to check
    797         * @throws IllegalStateException if expression is {@code false}
    798         * @see #validState(boolean, String, Object...)
    799         *
    800         * @since 3.0
    801         */
    802        public static void validState(boolean expression) {
    803            if (expression == false) {
    804                throw new IllegalStateException(DEFAULT_VALID_STATE_EX_MESSAGE);
    805            }
    806        }
    807
    808        /**
    809         * <p>Validate that the stateful condition is {@code true}; otherwise
    810         * throwing an exception with the specified message. This method is useful when
    811         * validating according to an arbitrary boolean expression, such as validating a
    812         * primitive number or using your own custom validation expression.</p>
    813         *
    814         * <pre>Validate.validState(this.isOk(), "The state is not OK: %s", myObject);</pre>
    815         *
    816         * @param expression  the boolean expression to check
    817         * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
    818         * @param values  the optional values for the formatted exception message, null array not recommended
    819         * @throws IllegalStateException if expression is {@code false}
    820         * @see #validState(boolean)
    821         *
    822         * @since 3.0
    823         */
    824        public static void validState(boolean expression, String message, Object... values) {
    825            if (expression == false) {
    826                throw new IllegalStateException(String.format(message, values));
    827            }
    828        }
    829
    830        // matchesPattern
    831        //---------------------------------------------------------------------------------
    832
    833        /**
    834         * <p>Validate that the specified argument character sequence matches the specified regular
    835         * expression pattern; otherwise throwing an exception.</p>
    836         *
    837         * <pre>Validate.matchesPattern("hi", "[a-z]*");</pre>
    838         *
    839         * <p>The syntax of the pattern is the one used in the {@link Pattern} class.</p>
    840         *
    841         * @param input  the character sequence to validate, not null
    842         * @param pattern  the regular expression pattern, not null
    843         * @throws IllegalArgumentException if the character sequence does not match the pattern
    844         * @see #matchesPattern(CharSequence, String, String, Object...)
    845         *
    846         * @since 3.0
    847         */
    848        public static void matchesPattern(CharSequence input, String pattern) {
    849            if (Pattern.matches(pattern, input) == false) {
    850                throw new IllegalArgumentException(String.format(DEFAULT_MATCHES_PATTERN_EX, input, pattern));
    851            }
    852        }
    853
    854        /**
    855         * <p>Validate that the specified argument character sequence matches the specified regular
    856         * expression pattern; otherwise throwing an exception with the specified message.</p>
    857         *
    858         * <pre>Validate.matchesPattern("hi", "[a-z]*", "%s does not match %s", "hi" "[a-z]*");</pre>
    859         *
    860         * <p>The syntax of the pattern is the one used in the {@link Pattern} class.</p>
    861         *
    862         * @param input  the character sequence to validate, not null
    863         * @param pattern  the regular expression pattern, not null
    864         * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
    865         * @param values  the optional values for the formatted exception message, null array not recommended
    866         * @throws IllegalArgumentException if the character sequence does not match the pattern
    867         * @see #matchesPattern(CharSequence, String)
    868         *
    869         * @since 3.0
    870         */
    871        public static void matchesPattern(CharSequence input, String pattern, String message, Object... values) {
    872            if (Pattern.matches(pattern, input) == false) {
    873                throw new IllegalArgumentException(String.format(message, values));
    874            }
    875        }
    876
    877        // inclusiveBetween
    878        //---------------------------------------------------------------------------------
    879
    880        /**
    881         * <p>Validate that the specified argument object fall between the two
    882         * inclusive values specified; otherwise, throws an exception.</p>
    883         *
    884         * <pre>Validate.inclusiveBetween(0, 2, 1);</pre>
    885         *
    886         * @param <T> the type of the argument object
    887         * @param start  the inclusive start value, not null
    888         * @param end  the inclusive end value, not null
    889         * @param value  the object to validate, not null
    890         * @throws IllegalArgumentException if the value falls out of the boundaries
    891         * @see #inclusiveBetween(Object, Object, Comparable, String, Object...)
    892         *
    893         * @since 3.0
    894         */
    895        public static <T> void inclusiveBetween(T start, T end, Comparable<T> value) {
    896            if (value.compareTo(start) < 0 || value.compareTo(end) > 0) {
    897                throw new IllegalArgumentException(String.format(DEFAULT_INCLUSIVE_BETWEEN_EX_MESSAGE, value, start, end));
    898            }
    899        }
    900
    901        /**
    902         * <p>Validate that the specified argument object fall between the two
    903         * inclusive values specified; otherwise, throws an exception with the
    904         * specified message.</p>
    905         *
    906         * <pre>Validate.inclusiveBetween(0, 2, 1, "Not in boundaries");</pre>
    907         *
    908         * @param <T> the type of the argument object
    909         * @param start  the inclusive start value, not null
    910         * @param end  the inclusive end value, not null
    911         * @param value  the object to validate, not null
    912         * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
    913         * @param values  the optional values for the formatted exception message, null array not recommended
    914         * @throws IllegalArgumentException if the value falls out of the boundaries
    915         * @see #inclusiveBetween(Object, Object, Comparable)
    916         *
    917         * @since 3.0
    918         */
    919        public static <T> void inclusiveBetween(T start, T end, Comparable<T> value, String message, Object... values) {
    920            if (value.compareTo(start) < 0 || value.compareTo(end) > 0) {
    921                throw new IllegalArgumentException(String.format(message, values));
    922            }
    923        }
    924
    925        // exclusiveBetween
    926        //---------------------------------------------------------------------------------
    927
    928        /**
    929         * <p>Validate that the specified argument object fall between the two
    930         * exclusive values specified; otherwise, throws an exception.</p>
    931         *
    932         * <pre>Validate.inclusiveBetween(0, 2, 1);</pre>
    933         *
    934         * @param <T> the type of the argument object
    935         * @param start  the exclusive start value, not null
    936         * @param end  the exclusive end value, not null
    937         * @param value  the object to validate, not null
    938         * @throws IllegalArgumentException if the value falls out of the boundaries
    939         * @see #exclusiveBetween(Object, Object, Comparable, String, Object...)
    940         *
    941         * @since 3.0
    942         */
    943        public static <T> void exclusiveBetween(T start, T end, Comparable<T> value) {
    944            if (value.compareTo(start) <= 0 || value.compareTo(end) >= 0) {
    945                throw new IllegalArgumentException(String.format(DEFAULT_EXCLUSIVE_BETWEEN_EX_MESSAGE, value, start, end));
    946            }
    947        }
    948
    949        /**
    950         * <p>Validate that the specified argument object fall between the two
    951         * exclusive values specified; otherwise, throws an exception with the
    952         * specified message.</p>
    953         *
    954         * <pre>Validate.inclusiveBetween(0, 2, 1, "Not in boundaries");</pre>
    955         *
    956         * @param <T> the type of the argument object
    957         * @param start  the exclusive start value, not null
    958         * @param end  the exclusive end value, not null
    959         * @param value  the object to validate, not null
    960         * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
    961         * @param values  the optional values for the formatted exception message, null array not recommended
    962         * @throws IllegalArgumentException if the value falls out of the boundaries
    963         * @see #exclusiveBetween(Object, Object, Comparable)
    964         *
    965         * @since 3.0
    966         */
    967        public static <T> void exclusiveBetween(T start, T end, Comparable<T> value, String message, Object... values) {
    968            if (value.compareTo(start) <= 0 || value.compareTo(end) >= 0) {
    969                throw new IllegalArgumentException(String.format(message, values));
    970            }
    971        }
    972
    973        // isInstanceOf
    974        //---------------------------------------------------------------------------------
    975
    976        /**
    977         * Validates that the argument is an instance of the specified class, if not throws an exception.
    978         *
    979         * <p>This method is useful when validating according to an arbitrary class</p>
    980         *
    981         * <pre>Validate.isInstanceOf(OkClass.class, object);</pre>
    982         *
    983         * <p>The message of the exception is &quot;Expected type: {type}, actual: {obj_type}&quot;</p>
    984         *
    985         * @param type  the class the object must be validated against, not null
    986         * @param obj  the object to check, null throws an exception
    987         * @throws IllegalArgumentException if argument is not of specified class
    988         * @see #isInstanceOf(Class, Object, String, Object...)
    989         *
    990         * @since 3.0
    991         */
    992        public static void isInstanceOf(Class<?> type, Object obj) {
    993            if (type.isInstance(obj) == false) {
    994                throw new IllegalArgumentException(String.format(DEFAULT_IS_INSTANCE_OF_EX_MESSAGE, type.getName(),
    995                        obj == null ? "null" : obj.getClass().getName()));
    996            }
    997        }
    998
    999        /**
    1000         * <p>Validate that the argument is an instance of the specified class; otherwise
    1001         * throwing an exception with the specified message. This method is useful when
    1002         * validating according to an arbitrary class</p>
    1003         *
    1004         * <pre>Validate.isInstanceOf(OkClass.classs, object, "Wrong class, object is of class %s",
    1005         *   object.getClass().getName());</pre>
    1006         *
    1007         * @param type  the class the object must be validated against, not null
    1008         * @param obj  the object to check, null throws an exception
    1009         * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
    1010         * @param values  the optional values for the formatted exception message, null array not recommended
    1011         * @throws IllegalArgumentException if argument is not of specified class
    1012         * @see #isInstanceOf(Class, Object)
    1013         *
    1014         * @since 3.0
    1015         */
    1016        public static void isInstanceOf(Class<?> type, Object obj, String message, Object... values) {
    1017            if (type.isInstance(obj) == false) {
    1018                throw new IllegalArgumentException(String.format(message, values));
    1019            }
    1020        }
    1021
    1022        // isAssignableFrom
    1023        //---------------------------------------------------------------------------------
    1024
    1025        /**
    1026         * Validates that the argument can be converted to the specified class, if not, throws an exception.
    1027         *
    1028         * <p>This method is useful when validating that there will be no casting errors.</p>
    1029         *
    1030         * <pre>Validate.isAssignableFrom(SuperClass.class, object.getClass());</pre>
    1031         *
    1032         * <p>The message format of the exception is &quot;Cannot assign {type} to {superType}&quot;</p>
    1033         *
    1034         * @param superType  the class the class must be validated against, not null
    1035         * @param type  the class to check, not null
    1036         * @throws IllegalArgumentException if type argument is not assignable to the specified superType
    1037         * @see #isAssignableFrom(Class, Class, String, Object...)
    1038         *
    1039         * @since 3.0
    1040         */
    1041        public static void isAssignableFrom(Class<?> superType, Class<?> type) {
    1042            if (superType.isAssignableFrom(type) == false) {
    1043                throw new IllegalArgumentException(String.format(DEFAULT_IS_ASSIGNABLE_EX_MESSAGE, type == null ? "null" : type.getName(),
    1044                        superType.getName()));
    1045            }
    1046        }
    1047
    1048        /**
    1049         * Validates that the argument can be converted to the specified class, if not throws an exception.
    1050         *
    1051         * <p>This method is useful when validating if there will be no casting errors.</p>
    1052         *
    1053         * <pre>Validate.isAssignableFrom(SuperClass.class, object.getClass());</pre>
    1054         *
    1055         * <p>The message of the exception is &quot;The validated object can not be converted to the&quot;
    1056         * followed by the name of the class and &quot;class&quot;</p>
    1057         *
    1058         * @param superType  the class the class must be validated against, not null
    1059         * @param type  the class to check, not null
    1060         * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
    1061         * @param values  the optional values for the formatted exception message, null array not recommended
    1062         * @throws IllegalArgumentException if argument can not be converted to the specified class
    1063         * @see #isAssignableFrom(Class, Class)
    1064         */
    1065        public static void isAssignableFrom(Class<?> superType, Class<?> type, String message, Object... values) {
    1066            if (superType.isAssignableFrom(type) == false) {
    1067                throw new IllegalArgumentException(String.format(message, values));
    1068            }
    1069        }
    1070    }