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    }