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