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