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