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