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 */
017package org.apache.commons.lang3;
018
019import java.util.Collection;
020import java.util.Iterator;
021import java.util.Map;
022import 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://docs.oracle.com/javase/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 &gt; 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 1583482 2014-03-31 22:54:57Z niallp $
044 * @see java.lang.String#format(String, Object...)
045 * @since 2.0
046 */
047public 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 &gt; 0.0, "The value must be greater than zero: &#37;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(final boolean expression, final String message, final 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 &gt; 0.0, "The value must be greater than zero: &#37;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(final boolean expression, final String message, final 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 &gt;= min &amp;&amp; i &lt;= max, "The value must be between &#37;d and &#37;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(final boolean expression, final String message, final 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 &gt; 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(final 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(final 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(final T object, final String message, final 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(final T[] array, final String message, final 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(final 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(final T collection, final String message, final 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(final 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(final T map, final String message, final 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(final 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(final T chars, final String message, final 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(final 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(final T chars, final String message, final 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(final 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(final T[] array, final String message, final Object... values) {
506        Validate.notNull(array);
507        for (int i = 0; i < array.length; i++) {
508            if (array[i] == null) {
509                final 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.</p>
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(final 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(final T iterable, final String message, final Object... values) {
568        Validate.notNull(iterable);
569        int i = 0;
570        for (final Iterator<?> it = iterable.iterator(); it.hasNext(); i++) {
571            if (it.next() == null) {
572                final 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(final 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(final T[] array, final int index, final String message, final 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(final T[] array, final 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(final T collection, final int index, final String message, final 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(final T collection, final 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(final T chars, final int index, final String message, final 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(final T chars, final 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 &gt; 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(final 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(final boolean expression, final String message, final 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(final CharSequence input, final String pattern) {
849        // TODO when breaking BC, consider returning input
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(final CharSequence input, final String pattern, final String message, final Object... values) {
873        // TODO when breaking BC, consider returning input
874        if (Pattern.matches(pattern, input) == false) {
875            throw new IllegalArgumentException(String.format(message, values));
876        }
877    }
878
879    // inclusiveBetween
880    //---------------------------------------------------------------------------------
881
882    /**
883     * <p>Validate that the specified argument object fall between the two
884     * inclusive values specified; otherwise, throws an exception.</p>
885     *
886     * <pre>Validate.inclusiveBetween(0, 2, 1);</pre>
887     *
888     * @param <T> the type of the argument object
889     * @param start  the inclusive start value, not null
890     * @param end  the inclusive end value, not null
891     * @param value  the object to validate, not null
892     * @throws IllegalArgumentException if the value falls outside the boundaries
893     * @see #inclusiveBetween(Object, Object, Comparable, String, Object...)
894     *
895     * @since 3.0
896     */
897    public static <T> void inclusiveBetween(final T start, final T end, final Comparable<T> value) {
898        // TODO when breaking BC, consider returning value
899        if (value.compareTo(start) < 0 || value.compareTo(end) > 0) {
900            throw new IllegalArgumentException(String.format(DEFAULT_INCLUSIVE_BETWEEN_EX_MESSAGE, value, start, end));
901        }
902    }
903
904    /**
905     * <p>Validate that the specified argument object fall between the two
906     * inclusive values specified; otherwise, throws an exception with the
907     * specified message.</p>
908     *
909     * <pre>Validate.inclusiveBetween(0, 2, 1, "Not in boundaries");</pre>
910     *
911     * @param <T> the type of the argument object
912     * @param start  the inclusive start value, not null
913     * @param end  the inclusive end value, not null
914     * @param value  the object to validate, not null
915     * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
916     * @param values  the optional values for the formatted exception message, null array not recommended
917     * @throws IllegalArgumentException if the value falls outside the boundaries
918     * @see #inclusiveBetween(Object, Object, Comparable)
919     *
920     * @since 3.0
921     */
922    public static <T> void inclusiveBetween(final T start, final T end, final Comparable<T> value, final String message, final Object... values) {
923        // TODO when breaking BC, consider returning value
924        if (value.compareTo(start) < 0 || value.compareTo(end) > 0) {
925            throw new IllegalArgumentException(String.format(message, values));
926        }
927    }
928
929    /**
930    * Validate that the specified primitive value falls between the two
931    * inclusive values specified; otherwise, throws an exception.
932    *
933    * <pre>Validate.inclusiveBetween(0, 2, 1);</pre>
934    *
935    * @param start the inclusive start value
936    * @param end   the inclusive end value
937    * @param value the value to validate
938    * @throws IllegalArgumentException if the value falls outside the boundaries (inclusive)
939    *
940    * @since 3.3
941    */
942    @SuppressWarnings("boxing")
943    public static void inclusiveBetween(long start, long end, long value) {
944        // TODO when breaking BC, consider returning value
945        if (value < start || value > end) {
946            throw new IllegalArgumentException(String.format(DEFAULT_INCLUSIVE_BETWEEN_EX_MESSAGE, value, start, end));
947        }
948    }
949
950    /**
951    * Validate that the specified primitive value falls between the two
952    * inclusive values specified; otherwise, throws an exception with the
953    * specified message.
954    *
955    * <pre>Validate.inclusiveBetween(0, 2, 1, "Not in range");</pre>
956    *
957    * @param start the inclusive start value
958    * @param end   the inclusive end value
959    * @param value the value to validate
960    * @param message the exception message if invalid, not null
961    *
962    * @throws IllegalArgumentException if the value falls outside the boundaries
963    *
964    * @since 3.3
965    */
966    public static void inclusiveBetween(long start, long end, long value, String message) {
967        // TODO when breaking BC, consider returning value
968        if (value < start || value > end) {
969            throw new IllegalArgumentException(String.format(message));
970        }
971    }
972
973    /**
974    * Validate that the specified primitive value falls between the two
975    * inclusive values specified; otherwise, throws an exception.
976    *
977    * <pre>Validate.inclusiveBetween(0.1, 2.1, 1.1);</pre>
978    *
979    * @param start the inclusive start value
980    * @param end   the inclusive end value
981    * @param value the value to validate
982    * @throws IllegalArgumentException if the value falls outside the boundaries (inclusive)
983    *
984    * @since 3.3
985    */
986    @SuppressWarnings("boxing")
987    public static void inclusiveBetween(double start, double end, double value) {
988        // TODO when breaking BC, consider returning value
989        if (value < start || value > end) {
990            throw new IllegalArgumentException(String.format(DEFAULT_INCLUSIVE_BETWEEN_EX_MESSAGE, value, start, end));
991        }
992    }
993
994    /**
995    * Validate that the specified primitive value falls between the two
996    * inclusive values specified; otherwise, throws an exception with the
997    * specified message.
998    *
999    * <pre>Validate.inclusiveBetween(0.1, 2.1, 1.1, "Not in range");</pre>
1000    *
1001    * @param start the inclusive start value
1002    * @param end   the inclusive end value
1003    * @param value the value to validate
1004    * @param message the exception message if invalid, not null
1005    *
1006    * @throws IllegalArgumentException if the value falls outside the boundaries
1007    *
1008    * @since 3.3
1009    */
1010    public static void inclusiveBetween(double start, double end, double value, String message) {
1011        // TODO when breaking BC, consider returning value
1012        if (value < start || value > end) {
1013            throw new IllegalArgumentException(String.format(message));
1014        }
1015    }
1016
1017    // exclusiveBetween
1018    //---------------------------------------------------------------------------------
1019
1020    /**
1021     * <p>Validate that the specified argument object fall between the two
1022     * exclusive values specified; otherwise, throws an exception.</p>
1023     *
1024     * <pre>Validate.exclusiveBetween(0, 2, 1);</pre>
1025     *
1026     * @param <T> the type of the argument object
1027     * @param start  the exclusive start value, not null
1028     * @param end  the exclusive end value, not null
1029     * @param value  the object to validate, not null
1030     * @throws IllegalArgumentException if the value falls outside the boundaries
1031     * @see #exclusiveBetween(Object, Object, Comparable, String, Object...)
1032     *
1033     * @since 3.0
1034     */
1035    public static <T> void exclusiveBetween(final T start, final T end, final Comparable<T> value) {
1036        // TODO when breaking BC, consider returning value
1037        if (value.compareTo(start) <= 0 || value.compareTo(end) >= 0) {
1038            throw new IllegalArgumentException(String.format(DEFAULT_EXCLUSIVE_BETWEEN_EX_MESSAGE, value, start, end));
1039        }
1040    }
1041
1042    /**
1043     * <p>Validate that the specified argument object fall between the two
1044     * exclusive values specified; otherwise, throws an exception with the
1045     * specified message.</p>
1046     *
1047     * <pre>Validate.exclusiveBetween(0, 2, 1, "Not in boundaries");</pre>
1048     *
1049     * @param <T> the type of the argument object
1050     * @param start  the exclusive start value, not null
1051     * @param end  the exclusive end value, not null
1052     * @param value  the object to validate, not null
1053     * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
1054     * @param values  the optional values for the formatted exception message, null array not recommended
1055     * @throws IllegalArgumentException if the value falls outside the boundaries
1056     * @see #exclusiveBetween(Object, Object, Comparable)
1057     *
1058     * @since 3.0
1059     */
1060    public static <T> void exclusiveBetween(final T start, final T end, final Comparable<T> value, final String message, final Object... values) {
1061        // TODO when breaking BC, consider returning value
1062        if (value.compareTo(start) <= 0 || value.compareTo(end) >= 0) {
1063            throw new IllegalArgumentException(String.format(message, values));
1064        }
1065    }
1066
1067    /**
1068    * Validate that the specified primitive value falls between the two
1069    * exclusive values specified; otherwise, throws an exception.
1070    *
1071    * <pre>Validate.exclusiveBetween(0, 2, 1);</pre>
1072    *
1073    * @param start the exclusive start value
1074    * @param end   the exclusive end value
1075    * @param value the value to validate
1076    * @throws IllegalArgumentException if the value falls out of the boundaries
1077    *
1078    * @since 3.3
1079    */
1080    @SuppressWarnings("boxing")
1081    public static void exclusiveBetween(long start, long end, long value) {
1082        // TODO when breaking BC, consider returning value
1083        if (value <= start || value >= end) {
1084            throw new IllegalArgumentException(String.format(DEFAULT_EXCLUSIVE_BETWEEN_EX_MESSAGE, value, start, end));
1085        }
1086    }
1087
1088    /**
1089    * Validate that the specified primitive value falls between the two
1090    * exclusive values specified; otherwise, throws an exception with the
1091    * specified message.
1092    *
1093    * <pre>Validate.exclusiveBetween(0, 2, 1, "Not in range");</pre>
1094    *
1095    * @param start the exclusive start value
1096    * @param end   the exclusive end value
1097    * @param value the value to validate
1098    * @param message the exception message if invalid, not null
1099    *
1100    * @throws IllegalArgumentException if the value falls outside the boundaries
1101    *
1102    * @since 3.3
1103    */
1104    public static void exclusiveBetween(long start, long end, long value, String message) {
1105        // TODO when breaking BC, consider returning value
1106        if (value <= start || value >= end) {
1107            throw new IllegalArgumentException(String.format(message));
1108        }
1109    }
1110
1111    /**
1112    * Validate that the specified primitive value falls between the two
1113    * exclusive values specified; otherwise, throws an exception.
1114    *
1115    * <pre>Validate.exclusiveBetween(0.1, 2.1, 1.1);</pre>
1116    *
1117    * @param start the exclusive start value
1118    * @param end   the exclusive end value
1119    * @param value the value to validate
1120    * @throws IllegalArgumentException if the value falls out of the boundaries
1121    *
1122    * @since 3.3
1123    */
1124    @SuppressWarnings("boxing")
1125    public static void exclusiveBetween(double start, double end, double value) {
1126        // TODO when breaking BC, consider returning value
1127        if (value <= start || value >= end) {
1128            throw new IllegalArgumentException(String.format(DEFAULT_EXCLUSIVE_BETWEEN_EX_MESSAGE, value, start, end));
1129        }
1130    }
1131
1132    /**
1133    * Validate that the specified primitive value falls between the two
1134    * exclusive values specified; otherwise, throws an exception with the
1135    * specified message.
1136    *
1137    * <pre>Validate.exclusiveBetween(0.1, 2.1, 1.1, "Not in range");</pre>
1138    *
1139    * @param start the exclusive start value
1140    * @param end   the exclusive end value
1141    * @param value the value to validate
1142    * @param message the exception message if invalid, not null
1143    *
1144    * @throws IllegalArgumentException if the value falls outside the boundaries
1145    *
1146    * @since 3.3
1147    */
1148    public static void exclusiveBetween(double start, double end, double value, String message) {
1149        // TODO when breaking BC, consider returning value
1150        if (value <= start || value >= end) {
1151            throw new IllegalArgumentException(String.format(message));
1152        }
1153    }
1154
1155    // isInstanceOf
1156    //---------------------------------------------------------------------------------
1157
1158    /**
1159     * Validates that the argument is an instance of the specified class, if not throws an exception.
1160     *  
1161     * <p>This method is useful when validating according to an arbitrary class</p>
1162     *
1163     * <pre>Validate.isInstanceOf(OkClass.class, object);</pre>
1164     *
1165     * <p>The message of the exception is &quot;Expected type: {type}, actual: {obj_type}&quot;</p>
1166     *
1167     * @param type  the class the object must be validated against, not null
1168     * @param obj  the object to check, null throws an exception
1169     * @throws IllegalArgumentException if argument is not of specified class
1170     * @see #isInstanceOf(Class, Object, String, Object...)
1171     *
1172     * @since 3.0
1173     */
1174    public static void isInstanceOf(final Class<?> type, final Object obj) {
1175        // TODO when breaking BC, consider returning obj
1176        if (type.isInstance(obj) == false) {
1177            throw new IllegalArgumentException(String.format(DEFAULT_IS_INSTANCE_OF_EX_MESSAGE, type.getName(),
1178                    obj == null ? "null" : obj.getClass().getName()));
1179        }
1180    }
1181
1182    /**
1183     * <p>Validate that the argument is an instance of the specified class; otherwise
1184     * throwing an exception with the specified message. This method is useful when
1185     * validating according to an arbitrary class</p>
1186     *
1187     * <pre>Validate.isInstanceOf(OkClass.classs, object, "Wrong class, object is of class %s",
1188     *   object.getClass().getName());</pre>
1189     *
1190     * @param type  the class the object must be validated against, not null
1191     * @param obj  the object to check, null throws an exception
1192     * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
1193     * @param values  the optional values for the formatted exception message, null array not recommended
1194     * @throws IllegalArgumentException if argument is not of specified class
1195     * @see #isInstanceOf(Class, Object)
1196     *
1197     * @since 3.0
1198     */
1199    public static void isInstanceOf(final Class<?> type, final Object obj, final String message, final Object... values) {
1200        // TODO when breaking BC, consider returning obj
1201        if (type.isInstance(obj) == false) {
1202            throw new IllegalArgumentException(String.format(message, values));
1203        }
1204    }
1205
1206    // isAssignableFrom
1207    //---------------------------------------------------------------------------------
1208
1209    /**
1210     * Validates that the argument can be converted to the specified class, if not, throws an exception.
1211     * 
1212     * <p>This method is useful when validating that there will be no casting errors.</p>
1213     *
1214     * <pre>Validate.isAssignableFrom(SuperClass.class, object.getClass());</pre>
1215     *
1216     * <p>The message format of the exception is &quot;Cannot assign {type} to {superType}&quot;</p>
1217     *
1218     * @param superType  the class the class must be validated against, not null
1219     * @param type  the class to check, not null
1220     * @throws IllegalArgumentException if type argument is not assignable to the specified superType
1221     * @see #isAssignableFrom(Class, Class, String, Object...)
1222     *
1223     * @since 3.0
1224     */
1225    public static void isAssignableFrom(final Class<?> superType, final Class<?> type) {
1226        // TODO when breaking BC, consider returning type
1227        if (superType.isAssignableFrom(type) == false) {
1228            throw new IllegalArgumentException(String.format(DEFAULT_IS_ASSIGNABLE_EX_MESSAGE, type == null ? "null" : type.getName(),
1229                    superType.getName()));
1230        }
1231    }
1232
1233    /**
1234     * Validates that the argument can be converted to the specified class, if not throws an exception.
1235     *  
1236     * <p>This method is useful when validating if there will be no casting errors.</p>
1237     *
1238     * <pre>Validate.isAssignableFrom(SuperClass.class, object.getClass());</pre>
1239     *
1240     * <p>The message of the exception is &quot;The validated object can not be converted to the&quot;
1241     * followed by the name of the class and &quot;class&quot;</p>
1242     *
1243     * @param superType  the class the class must be validated against, not null
1244     * @param type  the class to check, not null
1245     * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
1246     * @param values  the optional values for the formatted exception message, null array not recommended
1247     * @throws IllegalArgumentException if argument can not be converted to the specified class
1248     * @see #isAssignableFrom(Class, Class)
1249     */
1250    public static void isAssignableFrom(final Class<?> superType, final Class<?> type, final String message, final Object... values) {
1251        // TODO when breaking BC, consider returning type
1252        if (superType.isAssignableFrom(type) == false) {
1253            throw new IllegalArgumentException(String.format(message, values));
1254        }
1255    }
1256}