View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.commons.lang3;
18  
19  import java.util.Collection;
20  import java.util.Iterator;
21  import java.util.Map;
22  import java.util.regex.Pattern;
23  
24  /**
25   * <p>This class assists in validating arguments. The validation methods are
26   * based along the following principles:
27   * <ul>
28   *   <li>An invalid {@code null} argument causes a {@link NullPointerException}.</li>
29   *   <li>A non-{@code null} argument causes an {@link IllegalArgumentException}.</li>
30   *   <li>An invalid index into an array/collection/map/string causes an {@link IndexOutOfBoundsException}.</li>
31   * </ul>
32   *
33   * <p>All exceptions messages are
34   * <a href="http://docs.oracle.com/javase/1.5.0/docs/api/java/util/Formatter.html#syntax">format strings</a>
35   * as defined by the Java platform. For example:</p>
36   *
37   * <pre>
38   * Validate.isTrue(i &gt; 0, "The value must be greater than zero: %d", i);
39   * Validate.notNull(surname, "The surname must not be %s", null);
40   * </pre>
41   *
42   * <p>#ThreadSafe#</p>
43   * @version $Id: Validate.java 1583482 2014-03-31 22:54:57Z niallp $
44   * @see java.lang.String#format(String, Object...)
45   * @since 2.0
46   */
47  public class Validate {
48  
49      private static final String DEFAULT_EXCLUSIVE_BETWEEN_EX_MESSAGE =
50          "The value %s is not in the specified exclusive range of %s to %s";
51      private static final String DEFAULT_INCLUSIVE_BETWEEN_EX_MESSAGE =
52          "The value %s is not in the specified inclusive range of %s to %s";
53      private static final String DEFAULT_MATCHES_PATTERN_EX = "The string %s does not match the pattern %s";
54      private static final String DEFAULT_IS_NULL_EX_MESSAGE = "The validated object is null";
55      private static final String DEFAULT_IS_TRUE_EX_MESSAGE = "The validated expression is false";
56      private static final String DEFAULT_NO_NULL_ELEMENTS_ARRAY_EX_MESSAGE =
57          "The validated array contains null element at index: %d";
58      private static final String DEFAULT_NO_NULL_ELEMENTS_COLLECTION_EX_MESSAGE =
59          "The validated collection contains null element at index: %d";
60      private static final String DEFAULT_NOT_BLANK_EX_MESSAGE = "The validated character sequence is blank";
61      private static final String DEFAULT_NOT_EMPTY_ARRAY_EX_MESSAGE = "The validated array is empty";
62      private static final String DEFAULT_NOT_EMPTY_CHAR_SEQUENCE_EX_MESSAGE =
63          "The validated character sequence is empty";
64      private static final String DEFAULT_NOT_EMPTY_COLLECTION_EX_MESSAGE = "The validated collection is empty";
65      private static final String DEFAULT_NOT_EMPTY_MAP_EX_MESSAGE = "The validated map is empty";
66      private static final String DEFAULT_VALID_INDEX_ARRAY_EX_MESSAGE = "The validated array index is invalid: %d";
67      private static final String DEFAULT_VALID_INDEX_CHAR_SEQUENCE_EX_MESSAGE =
68          "The validated character sequence index is invalid: %d";
69      private static final String DEFAULT_VALID_INDEX_COLLECTION_EX_MESSAGE =
70          "The validated collection index is invalid: %d";
71      private static final String DEFAULT_VALID_STATE_EX_MESSAGE = "The validated state is false";
72      private static final String DEFAULT_IS_ASSIGNABLE_EX_MESSAGE = "Cannot assign a %s to a %s";
73      private static final String DEFAULT_IS_INSTANCE_OF_EX_MESSAGE = "Expected type: %s, actual: %s";
74  
75      /**
76       * Constructor. This class should not normally be instantiated.
77       */
78      public Validate() {
79        super();
80      }
81  
82      // isTrue
83      //---------------------------------------------------------------------------------
84  
85      /**
86       * <p>Validate that the argument condition is {@code true}; otherwise
87       * throwing an exception with the specified message. This method is useful when
88       * validating according to an arbitrary boolean expression, such as validating a
89       * primitive number or using your own custom validation expression.</p>
90       *
91       * <pre>Validate.isTrue(i &gt; 0.0, "The value must be greater than zero: &#37;d", i);</pre>
92       *
93       * <p>For performance reasons, the long value is passed as a separate parameter and
94       * appended to the exception message only in the case of an error.</p>
95       *
96       * @param expression  the boolean expression to check
97       * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
98       * @param value  the value to append to the message when invalid
99       * @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 }