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_GREATER_EX_MESSAGE =
53          "The value %s is not greater than %s";
54      private static final String DEFAULT_GREATER_OR_EQUAL_EX_MESSAGE =
55          "The value %s is not greater than or equal to %s";
56      private static final String DEFAULT_SMALLER_EX_MESSAGE =
57          "The value %s is not smaller than %s";
58      private static final String DEFAULT_SMALLER_OR_EQUAL_EX_MESSAGE =
59          "The value %s is not smaller than or equal to %s";
60      private static final String DEFAULT_DIFFERENT_EX_MESSAGE =
61          "The value %s is invalid";
62      private static final String DEFAULT_EXCLUSIVE_BETWEEN_EX_MESSAGE =
63          "The value %s is not in the specified exclusive range of %s to %s";
64      private static final String DEFAULT_INCLUSIVE_BETWEEN_EX_MESSAGE =
65          "The value %s is not in the specified inclusive range of %s to %s";
66      private static final String DEFAULT_MATCHES_PATTERN_EX = "The string %s does not match the pattern %s";
67      private static final String DEFAULT_IS_NULL_EX_MESSAGE = "The validated object is null";
68      private static final String DEFAULT_IS_TRUE_EX_MESSAGE = "The validated expression is false";
69      private static final String DEFAULT_NO_NULL_ELEMENTS_ARRAY_EX_MESSAGE =
70          "The validated array contains null element at index: %d";
71      private static final String DEFAULT_NO_NULL_ELEMENTS_COLLECTION_EX_MESSAGE =
72          "The validated collection contains null element at index: %d";
73      private static final String DEFAULT_NOT_BLANK_EX_MESSAGE = "The validated character sequence is blank";
74      private static final String DEFAULT_NOT_EMPTY_ARRAY_EX_MESSAGE = "The validated array is empty";
75      private static final String DEFAULT_NOT_EMPTY_CHAR_SEQUENCE_EX_MESSAGE =
76          "The validated character sequence is empty";
77      private static final String DEFAULT_NOT_EMPTY_COLLECTION_EX_MESSAGE = "The validated collection is empty";
78      private static final String DEFAULT_NOT_EMPTY_MAP_EX_MESSAGE = "The validated map is empty";
79      private static final String DEFAULT_VALID_INDEX_ARRAY_EX_MESSAGE = "The validated array index is invalid: %d";
80      private static final String DEFAULT_VALID_INDEX_CHAR_SEQUENCE_EX_MESSAGE =
81          "The validated character sequence index is invalid: %d";
82      private static final String DEFAULT_VALID_INDEX_COLLECTION_EX_MESSAGE =
83          "The validated collection index is invalid: %d";
84      private static final String DEFAULT_VALID_STATE_EX_MESSAGE = "The validated state is false";
85      private static final String DEFAULT_IS_ASSIGNABLE_EX_MESSAGE = "Cannot assign a %s to a %s";
86      private static final String DEFAULT_IS_INSTANCE_OF_EX_MESSAGE = "Expected type: %s, actual: %s";
87  
88      /**
89       * Constructor. This class should not normally be instantiated.
90       */
91      public Validate() {
92        super();
93      }
94  
95      // isTrue
96      //---------------------------------------------------------------------------------
97  
98      /**
99       * <p>Validate that the argument condition is {@code true}; otherwise
100      * throwing an exception with the specified message. This method is useful when
101      * validating according to an arbitrary boolean expression, such as validating a
102      * primitive number or using your own custom validation expression.</p>
103      *
104      * <pre>Validate.isTrue(i &gt; 0.0, "The value must be greater than zero: &#37;d", i);</pre>
105      *
106      * <p>For performance reasons, the long value is passed as a separate parameter and
107      * appended to the exception message only in the case of an error.</p>
108      *
109      * @param expression  the boolean expression to check
110      * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
111      * @param value  the value to append to the message when invalid
112      * @throws IllegalArgumentException if expression is {@code false}
113      * @see #isTrue(boolean)
114      * @see #isTrue(boolean, String, double)
115      * @see #isTrue(boolean, String, Object...)
116      */
117     public static void isTrue(final boolean expression, final String message, final long value) {
118         if (expression == false) {
119             throw new IllegalArgumentException(String.format(message, Long.valueOf(value)));
120         }
121     }
122 
123     /**
124      * <p>Validate that the argument condition is {@code true}; otherwise
125      * throwing an exception with the specified message. This method is useful when
126      * validating according to an arbitrary boolean expression, such as validating a
127      * primitive number or using your own custom validation expression.</p>
128      *
129      * <pre>Validate.isTrue(d &gt; 0.0, "The value must be greater than zero: &#37;s", d);</pre>
130      *
131      * <p>For performance reasons, the double value is passed as a separate parameter and
132      * appended to the exception message only in the case of an error.</p>
133      *
134      * @param expression  the boolean expression to check
135      * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
136      * @param value  the value to append to the message when invalid
137      * @throws IllegalArgumentException if expression is {@code false}
138      * @see #isTrue(boolean)
139      * @see #isTrue(boolean, String, long)
140      * @see #isTrue(boolean, String, Object...)
141      */
142     public static void isTrue(final boolean expression, final String message, final double value) {
143         if (expression == false) {
144             throw new IllegalArgumentException(String.format(message, Double.valueOf(value)));
145         }
146     }
147 
148     /**
149      * <p>Validate that the argument condition is {@code true}; otherwise
150      * throwing an exception with the specified message. This method is useful when
151      * validating according to an arbitrary boolean expression, such as validating a
152      * primitive number or using your own custom validation expression.</p>
153      *
154      * <pre>
155      * Validate.isTrue(i &gt;= min &amp;&amp; i &lt;= max, "The value must be between &#37;d and &#37;d", min, max);
156      * Validate.isTrue(myObject.isOk(), "The object is not okay");</pre>
157      *
158      * @param expression  the boolean expression to check
159      * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
160      * @param values  the optional values for the formatted exception message, null array not recommended
161      * @throws IllegalArgumentException if expression is {@code false}
162      * @see #isTrue(boolean)
163      * @see #isTrue(boolean, String, long)
164      * @see #isTrue(boolean, String, double)
165      */
166     public static void isTrue(final boolean expression, final String message, final Object... values) {
167         if (expression == false) {
168             throw new IllegalArgumentException(String.format(message, values));
169         }
170     }
171 
172     /**
173      * <p>Validate that the argument condition is {@code true}; otherwise
174      * throwing an exception. This method is useful when validating according
175      * to an arbitrary boolean expression, such as validating a
176      * primitive number or using your own custom validation expression.</p>
177      *
178      * <pre>
179      * Validate.isTrue(i &gt; 0);
180      * Validate.isTrue(myObject.isOk());</pre>
181      *
182      * <p>The message of the exception is &quot;The validated expression is
183      * false&quot;.</p>
184      *
185      * @param expression  the boolean expression to check
186      * @throws IllegalArgumentException if expression is {@code false}
187      * @see #isTrue(boolean, String, long)
188      * @see #isTrue(boolean, String, double)
189      * @see #isTrue(boolean, String, Object...)
190      */
191     public static void isTrue(final boolean expression) {
192         if (expression == false) {
193             throw new IllegalArgumentException(DEFAULT_IS_TRUE_EX_MESSAGE);
194         }
195     }
196 
197     // notNull
198     //---------------------------------------------------------------------------------
199 
200     /**
201      * <p>Validate that the specified argument is not {@code null};
202      * otherwise throwing an exception.
203      *
204      * <pre>Validate.notNull(myObject, "The object must not be null");</pre>
205      *
206      * <p>The message of the exception is &quot;The validated object is
207      * null&quot;.</p>
208      *
209      * @param <T> the object type
210      * @param object  the object to check
211      * @return the validated object (never {@code null} for method chaining)
212      * @throws NullPointerException if the object is {@code null}
213      * @see #notNull(Object, String, Object...)
214      */
215     public static <T> T notNull(final T object) {
216         return notNull(object, DEFAULT_IS_NULL_EX_MESSAGE);
217     }
218 
219     /**
220      * <p>Validate that the specified argument is not {@code null};
221      * otherwise throwing an exception with the specified message.
222      *
223      * <pre>Validate.notNull(myObject, "The object must not be null");</pre>
224      *
225      * @param <T> the object type
226      * @param object  the object to check
227      * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
228      * @param values  the optional values for the formatted exception message
229      * @return the validated object (never {@code null} for method chaining)
230      * @throws NullPointerException if the object is {@code null}
231      * @see #notNull(Object)
232      */
233     public static <T> T notNull(final T object, final String message, final Object... values) {
234         if (object == null) {
235             throw new NullPointerException(String.format(message, values));
236         }
237         return object;
238     }
239 
240     // notEmpty array
241     //---------------------------------------------------------------------------------
242 
243     /**
244      * <p>Validate that the specified argument array is neither {@code null}
245      * nor a length of zero (no elements); otherwise throwing an exception
246      * with the specified message.
247      *
248      * <pre>Validate.notEmpty(myArray, "The array must not be empty");</pre>
249      *
250      * @param <T> the array type
251      * @param array  the array to check, validated not null by this method
252      * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
253      * @param values  the optional values for the formatted exception message, null array not recommended
254      * @return the validated array (never {@code null} method for chaining)
255      * @throws NullPointerException if the array is {@code null}
256      * @throws IllegalArgumentException if the array is empty
257      * @see #notEmpty(Object[])
258      */
259     public static <T> T[] notEmpty(final T[] array, final String message, final Object... values) {
260         if (array == null) {
261             throw new NullPointerException(String.format(message, values));
262         }
263         if (array.length == 0) {
264             throw new IllegalArgumentException(String.format(message, values));
265         }
266         return array;
267     }
268 
269     /**
270      * <p>Validate that the specified argument array is neither {@code null}
271      * nor a length of zero (no elements); otherwise throwing an exception.
272      *
273      * <pre>Validate.notEmpty(myArray);</pre>
274      *
275      * <p>The message in the exception is &quot;The validated array is
276      * empty&quot;.
277      *
278      * @param <T> the array type
279      * @param array  the array to check, validated not null by this method
280      * @return the validated array (never {@code null} method for chaining)
281      * @throws NullPointerException if the array is {@code null}
282      * @throws IllegalArgumentException if the array is empty
283      * @see #notEmpty(Object[], String, Object...)
284      */
285     public static <T> T[] notEmpty(final T[] array) {
286         return notEmpty(array, DEFAULT_NOT_EMPTY_ARRAY_EX_MESSAGE);
287     }
288 
289     // notEmpty collection
290     //---------------------------------------------------------------------------------
291 
292     /**
293      * <p>Validate that the specified argument collection is neither {@code null}
294      * nor a size of zero (no elements); otherwise throwing an exception
295      * with the specified message.
296      *
297      * <pre>Validate.notEmpty(myCollection, "The collection must not be empty");</pre>
298      *
299      * @param <T> the collection type
300      * @param collection  the collection to check, validated not null by this method
301      * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
302      * @param values  the optional values for the formatted exception message, null array not recommended
303      * @return the validated collection (never {@code null} method for chaining)
304      * @throws NullPointerException if the collection is {@code null}
305      * @throws IllegalArgumentException if the collection is empty
306      * @see #notEmpty(Object[])
307      */
308     public static <T extends Collection<?>> T notEmpty(final T collection, final String message, final Object... values) {
309         if (collection == null) {
310             throw new NullPointerException(String.format(message, values));
311         }
312         if (collection.isEmpty()) {
313             throw new IllegalArgumentException(String.format(message, values));
314         }
315         return collection;
316     }
317 
318     /**
319      * <p>Validate that the specified argument collection is neither {@code null}
320      * nor a size of zero (no elements); otherwise throwing an exception.
321      *
322      * <pre>Validate.notEmpty(myCollection);</pre>
323      *
324      * <p>The message in the exception is &quot;The validated collection is
325      * empty&quot;.</p>
326      *
327      * @param <T> the collection type
328      * @param collection  the collection to check, validated not null by this method
329      * @return the validated collection (never {@code null} method for chaining)
330      * @throws NullPointerException if the collection is {@code null}
331      * @throws IllegalArgumentException if the collection is empty
332      * @see #notEmpty(Collection, String, Object...)
333      */
334     public static <T extends Collection<?>> T notEmpty(final T collection) {
335         return notEmpty(collection, DEFAULT_NOT_EMPTY_COLLECTION_EX_MESSAGE);
336     }
337 
338     // notEmpty map
339     //---------------------------------------------------------------------------------
340 
341     /**
342      * <p>Validate that the specified argument map is neither {@code null}
343      * nor a size of zero (no elements); otherwise throwing an exception
344      * with the specified message.
345      *
346      * <pre>Validate.notEmpty(myMap, "The map must not be empty");</pre>
347      *
348      * @param <T> the map type
349      * @param map  the map to check, validated not null by this method
350      * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
351      * @param values  the optional values for the formatted exception message, null array not recommended
352      * @return the validated map (never {@code null} method for chaining)
353      * @throws NullPointerException if the map is {@code null}
354      * @throws IllegalArgumentException if the map is empty
355      * @see #notEmpty(Object[])
356      */
357     public static <T extends Map<?, ?>> T notEmpty(final T map, final String message, final Object... values) {
358         if (map == null) {
359             throw new NullPointerException(String.format(message, values));
360         }
361         if (map.isEmpty()) {
362             throw new IllegalArgumentException(String.format(message, values));
363         }
364         return map;
365     }
366 
367     /**
368      * <p>Validate that the specified argument map is neither {@code null}
369      * nor a size of zero (no elements); otherwise throwing an exception.
370      *
371      * <pre>Validate.notEmpty(myMap);</pre>
372      *
373      * <p>The message in the exception is &quot;The validated map is
374      * empty&quot;.</p>
375      *
376      * @param <T> the map type
377      * @param map  the map to check, validated not null by this method
378      * @return the validated map (never {@code null} method for chaining)
379      * @throws NullPointerException if the map is {@code null}
380      * @throws IllegalArgumentException if the map is empty
381      * @see #notEmpty(Map, String, Object...)
382      */
383     public static <T extends Map<?, ?>> T notEmpty(final T map) {
384         return notEmpty(map, DEFAULT_NOT_EMPTY_MAP_EX_MESSAGE);
385     }
386 
387     // notEmpty string
388     //---------------------------------------------------------------------------------
389 
390     /**
391      * <p>Validate that the specified argument character sequence is
392      * neither {@code null} nor a length of zero (no characters);
393      * otherwise throwing an exception with the specified message.
394      *
395      * <pre>Validate.notEmpty(myString, "The string must not be empty");</pre>
396      *
397      * @param <T> the character sequence type
398      * @param chars  the character sequence to check, validated not null by this method
399      * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
400      * @param values  the optional values for the formatted exception message, null array not recommended
401      * @return the validated character sequence (never {@code null} method for chaining)
402      * @throws NullPointerException if the character sequence is {@code null}
403      * @throws IllegalArgumentException if the character sequence is empty
404      * @see #notEmpty(CharSequence)
405      */
406     public static <T extends CharSequence> T notEmpty(final T chars, final String message, final Object... values) {
407         if (chars == null) {
408             throw new NullPointerException(String.format(message, values));
409         }
410         if (chars.length() == 0) {
411             throw new IllegalArgumentException(String.format(message, values));
412         }
413         return chars;
414     }
415 
416     /**
417      * <p>Validate that the specified argument character sequence is
418      * neither {@code null} nor a length of zero (no characters);
419      * otherwise throwing an exception with the specified message.
420      *
421      * <pre>Validate.notEmpty(myString);</pre>
422      *
423      * <p>The message in the exception is &quot;The validated
424      * character sequence is empty&quot;.</p>
425      *
426      * @param <T> the character sequence type
427      * @param chars  the character sequence to check, validated not null by this method
428      * @return the validated character sequence (never {@code null} method for chaining)
429      * @throws NullPointerException if the character sequence is {@code null}
430      * @throws IllegalArgumentException if the character sequence is empty
431      * @see #notEmpty(CharSequence, String, Object...)
432      */
433     public static <T extends CharSequence> T notEmpty(final T chars) {
434         return notEmpty(chars, DEFAULT_NOT_EMPTY_CHAR_SEQUENCE_EX_MESSAGE);
435     }
436 
437     // notBlank string
438     //---------------------------------------------------------------------------------
439 
440     /**
441      * <p>Validate that the specified argument character sequence is
442      * neither {@code null}, a length of zero (no characters), empty
443      * nor whitespace; otherwise throwing an exception with the specified
444      * message.
445      *
446      * <pre>Validate.notBlank(myString, "The string must not be blank");</pre>
447      *
448      * @param <T> the character sequence type
449      * @param chars  the character sequence to check, validated not null by this method
450      * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
451      * @param values  the optional values for the formatted exception message, null array not recommended
452      * @return the validated character sequence (never {@code null} method for chaining)
453      * @throws NullPointerException if the character sequence is {@code null}
454      * @throws IllegalArgumentException if the character sequence is blank
455      * @see #notBlank(CharSequence)
456      *
457      * @since 3.0
458      */
459     public static <T extends CharSequence> T notBlank(final T chars, final String message, final Object... values) {
460         if (chars == null) {
461             throw new NullPointerException(String.format(message, values));
462         }
463         if (StringUtils.isBlank(chars)) {
464             throw new IllegalArgumentException(String.format(message, values));
465         }
466         return chars;
467     }
468 
469     /**
470      * <p>Validate that the specified argument character sequence is
471      * neither {@code null}, a length of zero (no characters), empty
472      * nor whitespace; otherwise throwing an exception.
473      *
474      * <pre>Validate.notBlank(myString);</pre>
475      *
476      * <p>The message in the exception is &quot;The validated character
477      * sequence is blank&quot;.</p>
478      *
479      * @param <T> the character sequence type
480      * @param chars  the character sequence to check, validated not null by this method
481      * @return the validated character sequence (never {@code null} method for chaining)
482      * @throws NullPointerException if the character sequence is {@code null}
483      * @throws IllegalArgumentException if the character sequence is blank
484      * @see #notBlank(CharSequence, String, Object...)
485      *
486      * @since 3.0
487      */
488     public static <T extends CharSequence> T notBlank(final T chars) {
489         return notBlank(chars, DEFAULT_NOT_BLANK_EX_MESSAGE);
490     }
491 
492     // noNullElements array
493     //---------------------------------------------------------------------------------
494 
495     /**
496      * <p>Validate that the specified argument array is neither
497      * {@code null} nor contains any elements that are {@code null};
498      * otherwise throwing an exception with the specified message.
499      *
500      * <pre>Validate.noNullElements(myArray, "The array contain null at position %d");</pre>
501      *
502      * <p>If the array is {@code null}, then the message in the exception
503      * is &quot;The validated object is null&quot;.</p>
504      *
505      * <p>If the array has a {@code null} element, then the iteration
506      * index of the invalid element is appended to the {@code values}
507      * argument.</p>
508      *
509      * @param <T> the array type
510      * @param array  the array to check, validated not null by this method
511      * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
512      * @param values  the optional values for the formatted exception message, null array not recommended
513      * @return the validated array (never {@code null} method for chaining)
514      * @throws NullPointerException if the array is {@code null}
515      * @throws IllegalArgumentException if an element is {@code null}
516      * @see #noNullElements(Object[])
517      */
518     public static <T> T[] noNullElements(final T[] array, final String message, final Object... values) {
519         Validate.notNull(array);
520         for (int i = 0; i < array.length; i++) {
521             if (array[i] == null) {
522                 final Object[] values2 = ArrayUtils.add(values, Integer.valueOf(i));
523                 throw new IllegalArgumentException(String.format(message, values2));
524             }
525         }
526         return array;
527     }
528 
529     /**
530      * <p>Validate that the specified argument array is neither
531      * {@code null} nor contains any elements that are {@code null};
532      * otherwise throwing an exception.</p>
533      *
534      * <pre>Validate.noNullElements(myArray);</pre>
535      *
536      * <p>If the array is {@code null}, then the message in the exception
537      * is &quot;The validated object is null&quot;.</p>
538      *
539      * <p>If the array has a {@code null} element, then the message in the
540      * exception is &quot;The validated array contains null element at index:
541      * &quot; followed by the index.</p>
542      *
543      * @param <T> the array type
544      * @param array  the array to check, validated not null by this method
545      * @return the validated array (never {@code null} method for chaining)
546      * @throws NullPointerException if the array is {@code null}
547      * @throws IllegalArgumentException if an element is {@code null}
548      * @see #noNullElements(Object[], String, Object...)
549      */
550     public static <T> T[] noNullElements(final T[] array) {
551         return noNullElements(array, DEFAULT_NO_NULL_ELEMENTS_ARRAY_EX_MESSAGE);
552     }
553 
554     // noNullElements iterable
555     //---------------------------------------------------------------------------------
556 
557     /**
558      * <p>Validate that the specified argument iterable is neither
559      * {@code null} nor contains any elements that are {@code null};
560      * otherwise throwing an exception with the specified message.
561      *
562      * <pre>Validate.noNullElements(myCollection, "The collection contains null at position %d");</pre>
563      *
564      * <p>If the iterable is {@code null}, then the message in the exception
565      * is &quot;The validated object is null&quot;.</p>
566      *
567      * <p>If the iterable has a {@code null} element, then the iteration
568      * index of the invalid element is appended to the {@code values}
569      * argument.</p>
570      *
571      * @param <T> the iterable type
572      * @param iterable  the iterable to check, validated not null by this method
573      * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
574      * @param values  the optional values for the formatted exception message, null array not recommended
575      * @return the validated iterable (never {@code null} method for chaining)
576      * @throws NullPointerException if the array is {@code null}
577      * @throws IllegalArgumentException if an element is {@code null}
578      * @see #noNullElements(Iterable)
579      */
580     public static <T extends Iterable<?>> T noNullElements(final T iterable, final String message, final Object... values) {
581         Validate.notNull(iterable);
582         int i = 0;
583         for (final Iterator<?> it = iterable.iterator(); it.hasNext(); i++) {
584             if (it.next() == null) {
585                 final Object[] values2 = ArrayUtils.addAll(values, Integer.valueOf(i));
586                 throw new IllegalArgumentException(String.format(message, values2));
587             }
588         }
589         return iterable;
590     }
591 
592     /**
593      * <p>Validate that the specified argument iterable is neither
594      * {@code null} nor contains any elements that are {@code null};
595      * otherwise throwing an exception.
596      *
597      * <pre>Validate.noNullElements(myCollection);</pre>
598      *
599      * <p>If the iterable is {@code null}, then the message in the exception
600      * is &quot;The validated object is null&quot;.</p>
601      *
602      * <p>If the array has a {@code null} element, then the message in the
603      * exception is &quot;The validated iterable contains null element at index:
604      * &quot; followed by the index.</p>
605      *
606      * @param <T> the iterable type
607      * @param iterable  the iterable to check, validated not null by this method
608      * @return the validated iterable (never {@code null} method for chaining)
609      * @throws NullPointerException if the array is {@code null}
610      * @throws IllegalArgumentException if an element is {@code null}
611      * @see #noNullElements(Iterable, String, Object...)
612      */
613     public static <T extends Iterable<?>> T noNullElements(final T iterable) {
614         return noNullElements(iterable, DEFAULT_NO_NULL_ELEMENTS_COLLECTION_EX_MESSAGE);
615     }
616 
617     // validIndex array
618     //---------------------------------------------------------------------------------
619 
620     /**
621      * <p>Validates that the index is within the bounds of the argument
622      * array; otherwise throwing an exception with the specified message.</p>
623      *
624      * <pre>Validate.validIndex(myArray, 2, "The array index is invalid: ");</pre>
625      *
626      * <p>If the array is {@code null}, then the message of the exception
627      * is &quot;The validated object is null&quot;.</p>
628      *
629      * @param <T> the array type
630      * @param array  the array to check, validated not null by this method
631      * @param index  the index to check
632      * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
633      * @param values  the optional values for the formatted exception message, null array not recommended
634      * @return the validated array (never {@code null} for method chaining)
635      * @throws NullPointerException if the array is {@code null}
636      * @throws IndexOutOfBoundsException if the index is invalid
637      * @see #validIndex(Object[], int)
638      *
639      * @since 3.0
640      */
641     public static <T> T[] validIndex(final T[] array, final int index, final String message, final Object... values) {
642         Validate.notNull(array);
643         if (index < 0 || index >= array.length) {
644             throw new IndexOutOfBoundsException(String.format(message, values));
645         }
646         return array;
647     }
648 
649     /**
650      * <p>Validates that the index is within the bounds of the argument
651      * array; otherwise throwing an exception.</p>
652      *
653      * <pre>Validate.validIndex(myArray, 2);</pre>
654      *
655      * <p>If the array is {@code null}, then the message of the exception
656      * is &quot;The validated object is null&quot;.</p>
657      *
658      * <p>If the index is invalid, then the message of the exception is
659      * &quot;The validated array index is invalid: &quot; followed by the
660      * index.</p>
661      *
662      * @param <T> the array type
663      * @param array  the array to check, validated not null by this method
664      * @param index  the index to check
665      * @return the validated array (never {@code null} for method chaining)
666      * @throws NullPointerException if the array is {@code null}
667      * @throws IndexOutOfBoundsException if the index is invalid
668      * @see #validIndex(Object[], int, String, Object...)
669      *
670      * @since 3.0
671      */
672     public static <T> T[] validIndex(final T[] array, final int index) {
673         return validIndex(array, index, DEFAULT_VALID_INDEX_ARRAY_EX_MESSAGE, Integer.valueOf(index));
674     }
675 
676     // validIndex collection
677     //---------------------------------------------------------------------------------
678 
679     /**
680      * <p>Validates that the index is within the bounds of the argument
681      * collection; otherwise throwing an exception with the specified message.</p>
682      *
683      * <pre>Validate.validIndex(myCollection, 2, "The collection index is invalid: ");</pre>
684      *
685      * <p>If the collection is {@code null}, then the message of the
686      * exception is &quot;The validated object is null&quot;.</p>
687      *
688      * @param <T> the collection type
689      * @param collection  the collection to check, validated not null by this method
690      * @param index  the index to check
691      * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
692      * @param values  the optional values for the formatted exception message, null array not recommended
693      * @return the validated collection (never {@code null} for chaining)
694      * @throws NullPointerException if the collection is {@code null}
695      * @throws IndexOutOfBoundsException if the index is invalid
696      * @see #validIndex(Collection, int)
697      *
698      * @since 3.0
699      */
700     public static <T extends Collection<?>> T validIndex(final T collection, final int index, final String message, final Object... values) {
701         Validate.notNull(collection);
702         if (index < 0 || index >= collection.size()) {
703             throw new IndexOutOfBoundsException(String.format(message, values));
704         }
705         return collection;
706     }
707 
708     /**
709      * <p>Validates that the index is within the bounds of the argument
710      * collection; otherwise throwing an exception.</p>
711      *
712      * <pre>Validate.validIndex(myCollection, 2);</pre>
713      *
714      * <p>If the index is invalid, then the message of the exception
715      * is &quot;The validated collection index is invalid: &quot;
716      * followed by the index.</p>
717      *
718      * @param <T> the collection type
719      * @param collection  the collection to check, validated not null by this method
720      * @param index  the index to check
721      * @return the validated collection (never {@code null} for method chaining)
722      * @throws NullPointerException if the collection is {@code null}
723      * @throws IndexOutOfBoundsException if the index is invalid
724      * @see #validIndex(Collection, int, String, Object...)
725      *
726      * @since 3.0
727      */
728     public static <T extends Collection<?>> T validIndex(final T collection, final int index) {
729         return validIndex(collection, index, DEFAULT_VALID_INDEX_COLLECTION_EX_MESSAGE, Integer.valueOf(index));
730     }
731 
732     // validIndex string
733     //---------------------------------------------------------------------------------
734 
735     /**
736      * <p>Validates that the index is within the bounds of the argument
737      * character sequence; otherwise throwing an exception with the
738      * specified message.</p>
739      *
740      * <pre>Validate.validIndex(myStr, 2, "The string index is invalid: ");</pre>
741      *
742      * <p>If the character sequence is {@code null}, then the message
743      * of the exception is &quot;The validated object is null&quot;.</p>
744      *
745      * @param <T> the character sequence type
746      * @param chars  the character sequence to check, validated not null by this method
747      * @param index  the index to check
748      * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
749      * @param values  the optional values for the formatted exception message, null array not recommended
750      * @return the validated character sequence (never {@code null} for method chaining)
751      * @throws NullPointerException if the character sequence is {@code null}
752      * @throws IndexOutOfBoundsException if the index is invalid
753      * @see #validIndex(CharSequence, int)
754      *
755      * @since 3.0
756      */
757     public static <T extends CharSequence> T validIndex(final T chars, final int index, final String message, final Object... values) {
758         Validate.notNull(chars);
759         if (index < 0 || index >= chars.length()) {
760             throw new IndexOutOfBoundsException(String.format(message, values));
761         }
762         return chars;
763     }
764 
765     /**
766      * <p>Validates that the index is within the bounds of the argument
767      * character sequence; otherwise throwing an exception.</p>
768      *
769      * <pre>Validate.validIndex(myStr, 2);</pre>
770      *
771      * <p>If the character sequence is {@code null}, then the message
772      * of the exception is &quot;The validated object is
773      * null&quot;.</p>
774      *
775      * <p>If the index is invalid, then the message of the exception
776      * is &quot;The validated character sequence index is invalid: &quot;
777      * followed by the index.</p>
778      *
779      * @param <T> the character sequence type
780      * @param chars  the character sequence to check, validated not null by this method
781      * @param index  the index to check
782      * @return the validated character sequence (never {@code null} for method chaining)
783      * @throws NullPointerException if the character sequence is {@code null}
784      * @throws IndexOutOfBoundsException if the index is invalid
785      * @see #validIndex(CharSequence, int, String, Object...)
786      *
787      * @since 3.0
788      */
789     public static <T extends CharSequence> T validIndex(final T chars, final int index) {
790         return validIndex(chars, index, DEFAULT_VALID_INDEX_CHAR_SEQUENCE_EX_MESSAGE, Integer.valueOf(index));
791     }
792 
793     // validState
794     //---------------------------------------------------------------------------------
795 
796     /**
797      * <p>Validate that the stateful condition is {@code true}; otherwise
798      * throwing an exception. This method is useful when validating according
799      * to an arbitrary boolean expression, such as validating a
800      * primitive number or using your own custom validation expression.</p>
801      *
802      * <pre>
803      * Validate.validState(field &gt; 0);
804      * Validate.validState(this.isOk());</pre>
805      *
806      * <p>The message of the exception is &quot;The validated state is
807      * false&quot;.</p>
808      *
809      * @param expression  the boolean expression to check
810      * @throws IllegalStateException if expression is {@code false}
811      * @see #validState(boolean, String, Object...)
812      *
813      * @since 3.0
814      */
815     public static void validState(final boolean expression) {
816         if (expression == false) {
817             throw new IllegalStateException(DEFAULT_VALID_STATE_EX_MESSAGE);
818         }
819     }
820 
821     /**
822      * <p>Validate that the stateful condition is {@code true}; otherwise
823      * throwing an exception with the specified message. This method is useful when
824      * validating according to an arbitrary boolean expression, such as validating a
825      * primitive number or using your own custom validation expression.</p>
826      *
827      * <pre>Validate.validState(this.isOk(), "The state is not OK: %s", myObject);</pre>
828      *
829      * @param expression  the boolean expression to check
830      * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
831      * @param values  the optional values for the formatted exception message, null array not recommended
832      * @throws IllegalStateException if expression is {@code false}
833      * @see #validState(boolean)
834      *
835      * @since 3.0
836      */
837     public static void validState(final boolean expression, final String message, final Object... values) {
838         if (expression == false) {
839             throw new IllegalStateException(String.format(message, values));
840         }
841     }
842 
843     // matchesPattern
844     //---------------------------------------------------------------------------------
845 
846     /**
847      * <p>Validate that the specified argument character sequence matches the specified regular
848      * expression pattern; otherwise throwing an exception.</p>
849      *
850      * <pre>Validate.matchesPattern("hi", "[a-z]*");</pre>
851      *
852      * <p>The syntax of the pattern is the one used in the {@link Pattern} class.</p>
853      *
854      * @param input  the character sequence to validate, not null
855      * @param pattern  the regular expression pattern, not null
856      * @throws IllegalArgumentException if the character sequence does not match the pattern
857      * @see #matchesPattern(CharSequence, String, String, Object...)
858      *
859      * @since 3.0
860      */
861     public static void matchesPattern(final CharSequence input, final String pattern) {
862         // TODO when breaking BC, consider returning input
863         if (Pattern.matches(pattern, input) == false) {
864             throw new IllegalArgumentException(String.format(DEFAULT_MATCHES_PATTERN_EX, input, pattern));
865         }
866     }
867 
868     /**
869      * <p>Validate that the specified argument character sequence matches the specified regular
870      * expression pattern; otherwise throwing an exception with the specified message.</p>
871      *
872      * <pre>Validate.matchesPattern("hi", "[a-z]*", "%s does not match %s", "hi" "[a-z]*");</pre>
873      *
874      * <p>The syntax of the pattern is the one used in the {@link Pattern} class.</p>
875      *
876      * @param input  the character sequence to validate, not null
877      * @param pattern  the regular expression pattern, not null
878      * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
879      * @param values  the optional values for the formatted exception message, null array not recommended
880      * @throws IllegalArgumentException if the character sequence does not match the pattern
881      * @see #matchesPattern(CharSequence, String)
882      *
883      * @since 3.0
884      */
885     public static void matchesPattern(final CharSequence input, final String pattern, final String message, final Object... values) {
886         // TODO when breaking BC, consider returning input
887         if (Pattern.matches(pattern, input) == false) {
888             throw new IllegalArgumentException(String.format(message, values));
889         }
890     }
891 
892     // notNaN
893     //---------------------------------------------------------------------------------
894 
895     /**
896      * <p>Validates that the specified argument is not {@code NaN}; otherwise
897      * throwing an exception.</p>
898      *
899      * <pre>Validate.notNaN(myDouble);</pre>
900      *
901      * <p>The message of the exception is &quot;The validated value is not a
902      * number&quot;.</p>
903      *
904      * @param value  the value to validate
905      * @throws IllegalArgumentException if the value is not a number
906      * @see #notNaN(double, java.lang.String, java.lang.Object...)
907      *
908      * @since 3.5
909      */
910     public static void notNaN(final double value) {
911         notNaN(value, DEFAULT_NOT_NAN_EX_MESSAGE);
912     }
913 
914     /**
915      * <p>Validates that the specified argument is not {@code NaN}; otherwise
916      * throwing an exception with the specified message.</p>
917      *
918      * <pre>Validate.notNaN(myDouble, "The value must be a number");</pre>
919      *
920      * @param value  the value to validate
921      * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
922      * @param values  the optional values for the formatted exception message
923      * @throws IllegalArgumentException if the value is not a number
924      * @see #notNaN(double)
925      *
926      * @since 3.5
927      */
928     public static void notNaN(final double value, final String message, final Object... values) {
929         if (Double.isNaN(value)) {
930             throw new IllegalArgumentException(String.format(message, values));
931         }
932     }
933 
934     // finite
935     //---------------------------------------------------------------------------------
936 
937     /**
938      * <p>Validates that the specified argument is not infinite or {@code NaN};
939      * otherwise throwing an exception.</p>
940      *
941      * <pre>Validate.finite(myDouble);</pre>
942      *
943      * <p>The message of the exception is &quot;The value is invalid: %f&quot;.</p>
944      *
945      * @param value  the value to validate
946      * @throws IllegalArgumentException if the value is infinite or {@code NaN}
947      * @see #finite(double, java.lang.String, java.lang.Object...)
948      *
949      * @since 3.5
950      */
951     public static void finite(final double value) {
952         finite(value, DEFAULT_FINITE_EX_MESSAGE, value);
953     }
954 
955     /**
956      * <p>Validates that the specified argument is not infinite or {@code NaN};
957      * otherwise throwing an exception with the specified message.</p>
958      *
959      * <pre>Validate.finite(myDouble, "The argument must contain a numeric value");</pre>
960      *
961      * @param value the value to validate
962      * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
963      * @param values  the optional values for the formatted exception message
964      * @throws IllegalArgumentException if the value is infinite or {@code NaN}
965      * @see #finite(double)
966      *
967      * @since 3.5
968      */
969     public static void finite(final double value, final String message, final Object... values) {
970         if (Double.isNaN(value) || Double.isInfinite(value)) {
971             throw new IllegalArgumentException(String.format(message, values));
972         }
973     }
974 
975     // greater
976     //---------------------------------------------------------------------------------
977 
978     /**
979      * <p>Validates that the specified argument is strictly greater than a given
980      * reference; otherwise throwing an exception.</p>
981      *
982      * <pre>Validate.greaterObj(myObject, refObject);</pre>
983      *
984      * <p>The message of the exception is &quot;The value {@code value} is not
985      * greater than {@code min}&quot;.</p>
986      *
987      * @param <T>  the type of the argument object
988      * @param value  the object to validate
989      * @param min  the reference value
990      * @throws IllegalArgumentException if {@code value} is smaller than or equal to {@code min}
991      * @see #greaterObj(java.lang.Comparable, java.lang.Object, java.lang.String, java.lang.Object...)
992      *
993      * @since 3.5
994      */
995     public static <T> void greaterObj(final Comparable<T> value, final T min) {
996         greaterObj(value, min, DEFAULT_GREATER_EX_MESSAGE, value, min);
997     }
998 
999     /**
1000      * <p>Validates that the specified argument is strictly greater than a given
1001      * reference; otherwise throwing an exception with the specified message.</p>
1002      *
1003      * <pre>Validate.greaterObj(myObject, refObject, "The value must be greater than the reference");</pre>
1004      *
1005      * @param <T>  the type of the argument object
1006      * @param value  the object to validate
1007      * @param min  the reference value
1008      * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
1009      * @param values  the optional values for the formatted exception message
1010      * @throws IllegalArgumentException if {@code value} is smaller than or equal to {@code min}
1011      * @see #greaterObj(java.lang.Comparable, java.lang.Object)
1012      *
1013      * @since 3.5
1014      */
1015     public static <T> void greaterObj(final Comparable<T> value, final T min, final String message, final Object... values) {
1016         if (value.compareTo(min) <= 0) {
1017             throw new IllegalArgumentException(String.format(message, values));
1018         }
1019     }
1020 
1021     /**
1022      * <p>Validates that the specified argument is strictly greater than a given
1023      * reference; otherwise throwing an exception.</p>
1024      *
1025      * <pre>Validate.greater(myLong, 0);</pre>
1026      *
1027      * <p>The message of the exception is &quot;The value {@code value} is not
1028      * greater than {@code min}&quot;.</p>
1029      *
1030      * @param value  the value to validate
1031      * @param min  the reference value
1032      * @throws IllegalArgumentException if {@code value} is smaller than or equal to {@code min}
1033      * @see #greater(long, long, java.lang.String, java.lang.Object...)
1034      *
1035      * @since 3.5
1036      */
1037     public static void greater(final long value, final long min) {
1038         greater(value, min, DEFAULT_GREATER_EX_MESSAGE, value, min);
1039     }
1040 
1041     /**
1042      * <p>Validates that the specified argument is strictly greater than a given
1043      * reference; otherwise throwing an exception with the specified message.</p>
1044      *
1045      * <pre>Validate.greater(myLong, 0);</pre>
1046      *
1047      * @param value  the value to validate
1048      * @param min  the reference value
1049      * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
1050      * @param values  the optional values for the formatted exception message
1051      * @throws IllegalArgumentException if {@code value} is smaller than or equal to {@code min}
1052      * @see #greater(long, long)
1053      *
1054      * @since 3.5
1055      */
1056     public static void greater(final long value, final long min, final String message, final Object... values) {
1057         if (value <= min) {
1058             throw new IllegalArgumentException(String.format(message, values));
1059         }
1060     }
1061 
1062     /**
1063      * <p>Validates that the specified argument is strictly greater than a given
1064      * reference; otherwise throwing an exception.</p>
1065      *
1066      * <p>If {@code min} or {@code value} is {@code NaN}, the test will fail and
1067      * the exception will be thrown.</p>
1068      *
1069      * <pre>Validate.greater(myDouble, 0.0);</pre>
1070      *
1071      * <p>The message of the exception is &quot;The value {@code value} is not
1072      * greater than {@code min}&quot;.</p>
1073      *
1074      * @param value  the value to validate
1075      * @param min  the reference value
1076      * @throws IllegalArgumentException if {@code value} is smaller than or equal to {@code min}
1077      * @see #greater(double, double, java.lang.String, java.lang.Object...)
1078      *
1079      * @since 3.5
1080      */
1081     public static void greater(final double value, final double min) {
1082         greater(value, min, DEFAULT_GREATER_EX_MESSAGE, value, min);
1083     }
1084 
1085     /**
1086      * <p>Validates that the specified argument is strictly greater than a given
1087      * reference; otherwise throwing an exception with the specified message.</p>
1088      *
1089      * <p>If {@code min} or {@code value} is {@code NaN}, the test will fail and
1090      * the exception will be thrown.</p>
1091      *
1092      * <pre>Validate.greater(myDouble, 0.0);</pre>
1093      *
1094      * @param value  the value to validate
1095      * @param min  the reference value
1096      * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
1097      * @param values  the optional values for the formatted exception message
1098      * @throws IllegalArgumentException if {@code value} is smaller than or equal to {@code min}
1099      * @see #greater(double, double)
1100      *
1101      * @since 3.5
1102      */
1103     public static void greater(final double value, final double min, final String message, final Object... values) {
1104         if (!(value > min)) {
1105             throw new IllegalArgumentException(String.format(message, values));
1106         }
1107     }
1108 
1109     // greaterOrEqual
1110     //---------------------------------------------------------------------------------
1111 
1112     /**
1113      * <p>Validates that the specified argument is greater than, or equal to, a
1114      * given reference; otherwise throwing an exception.</p>
1115      *
1116      * <pre>Validate.greaterOrEqualObj(myObject, refObject);</pre>
1117      *
1118      * <p>The message of the exception is &quot;The value {@code value} is not
1119      * greater than or equal to {@code min}&quot;.</p>
1120      *
1121      * @param <T>  the type of the argument object
1122      * @param value  the object to validate
1123      * @param min  the reference value
1124      * @throws IllegalArgumentException if {@code value} is smaller than {@code min}
1125      * @see #greaterOrEqualObj(java.lang.Comparable, java.lang.Object, java.lang.String, java.lang.Object...)
1126      *
1127      * @since 3.5
1128      */
1129     public static <T> void greaterOrEqualObj(final Comparable<T> value, final T min) {
1130         greaterOrEqualObj(value, min, DEFAULT_GREATER_OR_EQUAL_EX_MESSAGE, value, min);
1131     }
1132 
1133     /**
1134      * <p>Validates that the specified argument is greater than, or equal to, a
1135      * given reference; otherwise throwing an exception.</p>
1136      *
1137      * <pre>Validate.greaterOrEqualObj(myObject, refObject, "The value must be greater than the reference");</pre>
1138      *
1139      * @param <T>  the type of the argument object
1140      * @param value  the object to validate
1141      * @param min  the reference value
1142      * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
1143      * @param values  the optional values for the formatted exception message
1144      * @throws IllegalArgumentException if {@code value} is smaller than {@code min}
1145      * @see #greaterOrEqualObj(java.lang.Comparable, java.lang.Object)
1146      *
1147      * @since 3.5
1148      */
1149     public static <T> void greaterOrEqualObj(final Comparable<T> value, final T min, final String message, final Object... values) {
1150         if (value.compareTo(min) < 0) {
1151             throw new IllegalArgumentException(String.format(message, values));
1152         }
1153     }
1154 
1155     /**
1156      * <p>Validates that the specified argument is greater than, or equal to, a
1157      * given reference; otherwise throwing an exception.</p>
1158      *
1159      * <pre>Validate.greaterOrEqual(myLong, 0);</pre>
1160      *
1161      * <p>The message of the exception is &quot;The value {@code value} is not
1162      * greater than or equal to {@code min}&quot;.</p>
1163      *
1164      * @param value  the value to validate
1165      * @param min  the reference value
1166      * @throws IllegalArgumentException if {@code value} is smaller than {@code min}
1167      * @see #greaterOrEqual(long, long, java.lang.String, java.lang.Object...)
1168      *
1169      * @since 3.5
1170      */
1171     public static void greaterOrEqual(final long value, final long min) {
1172         greaterOrEqual(value, min, DEFAULT_GREATER_OR_EQUAL_EX_MESSAGE, value, min);
1173     }
1174 
1175     /**
1176      * <p>Validates that the specified argument is greater than, or equal to, a
1177      * given reference; otherwise throwing an exception with the specified message.</p>
1178      *
1179      * <pre>Validate.greaterOrEqual(myLong, 0);</pre>
1180      *
1181      * @param value  the value to validate
1182      * @param min  the reference value
1183      * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
1184      * @param values  the optional values for the formatted exception message
1185      * @throws IllegalArgumentException if {@code value} is smaller than {@code min}
1186      * @see #greaterOrEqual(long, long)
1187      *
1188      * @since 3.5
1189      */
1190     public static void greaterOrEqual(final long value, final long min, final String message, final Object... values) {
1191         if (value < min) {
1192             throw new IllegalArgumentException(String.format(message, values));
1193         }
1194     }
1195 
1196     /**
1197      * <p>Validates that the specified argument is greater than, or equal to, a
1198      * given reference; otherwise throwing an exception.</p>
1199      *
1200      * <p>If {@code min} or {@code value} is {@code NaN}, the test will fail and
1201      * the exception will be thrown.</p>
1202      *
1203      * <pre>Validate.greaterOrEqual(myDouble, 0.0);</pre>
1204      *
1205      * <p>The message of the exception is &quot;The value {@code value} is not
1206      * greater than or equal to {@code min}&quot;.</p>
1207      *
1208      * @param value  the value to validate
1209      * @param min  the reference value
1210      * @throws IllegalArgumentException if {@code value} is smaller than {@code min}
1211      * @see #greaterOrEqual(double, double, java.lang.String, java.lang.Object...)
1212      *
1213      * @since 3.5
1214      */
1215     public static void greaterOrEqual(final double value, final double min) {
1216         greaterOrEqual(value, min, DEFAULT_GREATER_OR_EQUAL_EX_MESSAGE, value, min);
1217     }
1218 
1219     /**
1220      * <p>Validates that the specified argument is greater than, or equal to, a
1221      * given reference; otherwise throwing an exception with the specified message.</p>
1222      *
1223      * <p>If {@code min} or {@code value} is {@code NaN}, the test will fail and
1224      * the exception will be thrown.</p>
1225      *
1226      * <pre>Validate.greaterOrEqual(myDouble, 0.0);</pre>
1227      *
1228      * @param value  the value to validate
1229      * @param min  the reference value
1230      * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
1231      * @param values  the optional values for the formatted exception message
1232      * @throws IllegalArgumentException if {@code value} is smaller than {@code min}
1233      * @see #greaterOrEqual(double, double)
1234      *
1235      * @since 3.5
1236      */
1237     public static void greaterOrEqual(final double value, final double min, final String message, final Object... values) {
1238         if (!(value >= min)) {
1239             throw new IllegalArgumentException(String.format(message, values));
1240         }
1241     }
1242 
1243     // smaller
1244     //---------------------------------------------------------------------------------
1245 
1246     /**
1247      * <p>Validates that the specified argument is strictly smaller than a given
1248      * reference; otherwise throwing an exception.</p>
1249      *
1250      * <pre>Validate.smallerObj(myObject, refObject);</pre>
1251      *
1252      * <p>The message of the exception is &quot;The value {@code value} is not
1253      * smaller than {@code max}&quot;.</p>
1254      *
1255      * @param <T>  the type of the argument object
1256      * @param value  the object to validate
1257      * @param max  the reference value
1258      * @throws IllegalArgumentException if {@code value} is greater than or equal to {@code max}
1259      * @see #smallerObj(java.lang.Comparable, java.lang.Object, java.lang.String, java.lang.Object...)
1260      *
1261      * @since 3.5
1262      */
1263     public static <T> void smallerObj(final Comparable<T> value, final T max) {
1264         smallerObj(value, max, DEFAULT_SMALLER_EX_MESSAGE, value, max);
1265     }
1266 
1267     /**
1268      * <p>Validates that the specified argument is strictly smaller than a given
1269      * reference; otherwise throwing an exception with the specified message.</p>
1270      *
1271      * <pre>Validate.smallerObj(myObject, refObject, "The value must be greater than the reference");</pre>
1272      *
1273      * @param <T>  the type of the argument object
1274      * @param value  the object to validate
1275      * @param max  the reference value
1276      * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
1277      * @param values  the optional values for the formatted exception message
1278      * @throws IllegalArgumentException if {@code value} is greater than or equal to {@code max}
1279      * @see #smallerObj(java.lang.Comparable, java.lang.Object)
1280      *
1281      * @since 3.5
1282      */
1283     public static <T> void smallerObj(final Comparable<T> value, final T max, final String message, final Object... values) {
1284         if (value.compareTo(max) >= 0) {
1285             throw new IllegalArgumentException(String.format(message, values));
1286         }
1287     }
1288 
1289     /**
1290      * <p>Validates that the specified argument is strictly smaller than a given
1291      * reference; otherwise throwing an exception.</p>
1292      *
1293      * <pre>Validate.smaller(myLong, 0);</pre>
1294      *
1295      * <p>The message of the exception is &quot;The value {@code value} is not
1296      * smaller than {@code max}&quot;.</p>
1297      *
1298      * @param value  the value to validate
1299      * @param max  the reference value
1300      * @throws IllegalArgumentException if {@code value} is greater than or equal to {@code max}
1301      * @see #smaller(long, long, java.lang.String, java.lang.Object...)
1302      *
1303      * @since 3.5
1304      */
1305     public static void smaller(final long value, final long max) {
1306         smaller(value, max, DEFAULT_SMALLER_EX_MESSAGE, value, max);
1307     }
1308 
1309     /**
1310      * <p>Validates that the specified argument is strictly smaller than a given
1311      * reference; otherwise throwing an exception with the specified message.</p>
1312      *
1313      * <pre>Validate.smaller(myLong, 0);</pre>
1314      *
1315      * @param value  the value to validate
1316      * @param max  the reference value
1317      * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
1318      * @param values  the optional values for the formatted exception message
1319      * @throws IllegalArgumentException if {@code value} is greater than or equal to {@code max}
1320      * @see #smaller(long, long)
1321      *
1322      * @since 3.5
1323      */
1324     public static void smaller(final long value, final long max, final String message, final Object... values) {
1325         if (value >= max) {
1326             throw new IllegalArgumentException(String.format(message, values));
1327         }
1328     }
1329 
1330     /**
1331      * <p>Validates that the specified argument is strictly smaller than a given
1332      * reference; otherwise throwing an exception.</p>
1333      *
1334      * <p>If {@code min} or {@code value} is {@code NaN}, the test will fail and
1335      * the exception will be thrown.</p>
1336      *
1337      * <pre>Validate.smaller(myDouble, 0.0);</pre>
1338      *
1339      * <p>The message of the exception is &quot;The value {@code value} is not
1340      * smaller than {@code max}&quot;.</p>
1341      *
1342      * @param value  the value to validate
1343      * @param max  the reference value
1344      * @throws IllegalArgumentException if {@code value} is greater than or equal to {@code max}
1345      * @see #smaller(double, double, java.lang.String, java.lang.Object...)
1346      *
1347      * @since 3.5
1348      */
1349     public static void smaller(final double value, final double max) {
1350         smaller(value, max, DEFAULT_SMALLER_EX_MESSAGE, value, max);
1351     }
1352 
1353     /**
1354      * <p>Validates that the specified argument is strictly smaller than a given
1355      * reference; otherwise throwing an exception with the specified message.</p>
1356      *
1357      * <p>If {@code min} or {@code value} is {@code NaN}, the test will fail and
1358      * the exception will be thrown.</p>
1359      *
1360      * <pre>Validate.smaller(myDouble, 0.0);</pre>
1361      *
1362      * @param value  the value to validate
1363      * @param max  the reference value
1364      * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
1365      * @param values  the optional values for the formatted exception message
1366      * @throws IllegalArgumentException if {@code value} is greater than or equal to {@code max}
1367      * @see #smaller(double, double)
1368      *
1369      * @since 3.5
1370      */
1371     public static void smaller(final double value, final double max, final String message, final Object... values) {
1372         if (!(value < max)) {
1373             throw new IllegalArgumentException(String.format(message, values));
1374         }
1375     }
1376 
1377     // smallerOrEqual
1378     //---------------------------------------------------------------------------------
1379 
1380     /**
1381      * <p>Validates that the specified argument is smaller than, or equal to, a
1382      * given reference; otherwise throwing an exception.</p>
1383      *
1384      * <pre>Validate.smallerOrEqualObj(myObject, refObject);</pre>
1385      *
1386      * <p>The message of the exception is &quot;The value {@code value} is not
1387      * smaller than or equal to {@code max}&quot;.</p>
1388      *
1389      * @param <T>  the type of the argument object
1390      * @param value  the object to validate
1391      * @param max  the reference value
1392      * @throws IllegalArgumentException if {@code value} is greater than {@code max}
1393      * @see #smallerOrEqualObj(java.lang.Comparable, java.lang.Object, java.lang.String, java.lang.Object...)
1394      *
1395      * @since 3.5
1396      */
1397     public static <T> void smallerOrEqualObj(final Comparable<T> value, final T max) {
1398         smallerOrEqualObj(value, max, DEFAULT_SMALLER_OR_EQUAL_EX_MESSAGE, value, max);
1399     }
1400 
1401     /**
1402      * <p>Validates that the specified argument is smaller than, or equal to, a
1403      * given reference; otherwise throwing an exception with the specified message.</p>
1404      *
1405      * <pre>Validate.smallerOrEqualObj(myObject, refObject, "The value must be greater than the reference");</pre>
1406      *
1407      * @param <T>  the type of the argument object
1408      * @param value  the object to validate
1409      * @param max  the reference value
1410      * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
1411      * @param values  the optional values for the formatted exception message
1412      * @throws IllegalArgumentException if {@code value} is greater than {@code max}
1413      * @see #smallerOrEqualObj(java.lang.Comparable, java.lang.Object)
1414      *
1415      * @since 3.5
1416      */
1417     public static <T> void smallerOrEqualObj(final Comparable<T> value, final T max, final String message, final Object... values) {
1418         if (value.compareTo(max) > 0) {
1419             throw new IllegalArgumentException(String.format(message, values));
1420         }
1421     }
1422 
1423     /**
1424      * <p>Validates that the specified argument is smaller than, or equal to, a
1425      * given reference; otherwise throwing an exception.</p>
1426      *
1427      * <pre>Validate.smallerOrEqual(myLong, 0);</pre>
1428      *
1429      * <p>The message of the exception is &quot;The value {@code value} is not
1430      * smaller than or equal to {@code max}&quot;.</p>
1431      *
1432      * @param value  the value to validate
1433      * @param max  the reference value
1434      * @throws IllegalArgumentException if {@code value} is greater than {@code max}
1435      * @see #smallerOrEqual(long, long, java.lang.String, java.lang.Object...)
1436      *
1437      * @since 3.5
1438      */
1439     public static void smallerOrEqual(final long value, final long max) {
1440         smallerOrEqual(value, max, DEFAULT_SMALLER_OR_EQUAL_EX_MESSAGE, value, max);
1441     }
1442 
1443     /**
1444      * <p>Validates that the specified argument is smaller than, or equal to, a
1445      * given reference; otherwise throwing an exception with the specified message.</p>
1446      *
1447      * <pre>Validate.smallerOrEqual(myLong, 0);</pre>
1448      *
1449      * @param value  the value to validate
1450      * @param max  the reference value
1451      * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
1452      * @param values  the optional values for the formatted exception message
1453      * @throws IllegalArgumentException if {@code value} is greater than {@code max}
1454      * @see #smallerOrEqual(long, long)
1455      *
1456      * @since 3.5
1457      */
1458     public static void smallerOrEqual(final long value, final long max, final String message, final Object... values) {
1459         if (value > max) {
1460             throw new IllegalArgumentException(String.format(message, values));
1461         }
1462     }
1463 
1464     /**
1465      * <p>Validates that the specified argument is smaller than, or equal to, a
1466      * given reference; otherwise throwing an exception.</p>
1467      *
1468      * <p>If {@code min} or {@code value} is {@code NaN}, the test will fail and
1469      * the exception will be thrown.</p>
1470      *
1471      * <pre>Validate.smallerOrEqual(myDouble, 0.0);</pre>
1472      *
1473      * <p>The message of the exception is &quot;The value {@code value} is not
1474      * smaller than or equal to {@code max}&quot;.</p>
1475      *
1476      * @param value  the value to validate
1477      * @param max  the reference value
1478      * @throws IllegalArgumentException if {@code value} is greater than {@code max}
1479      * @see #smallerOrEqual(double, double, java.lang.String, java.lang.Object...)
1480      *
1481      * @since 3.5
1482      */
1483     public static void smallerOrEqual(final double value, final double max) {
1484         smallerOrEqual(value, max, DEFAULT_SMALLER_OR_EQUAL_EX_MESSAGE, value, max);
1485     }
1486 
1487     /**
1488      * <p>Validates that the specified argument is smaller than, or equal to, a
1489      * given reference; otherwise throwing an exception with the specified message.</p>
1490      *
1491      * <p>If {@code min} or {@code value} is {@code NaN}, the test will fail and
1492      * the exception will be thrown.</p>
1493      *
1494      * <pre>Validate.smallerOrEqual(myDouble, 0.0);</pre>
1495      *
1496      * @param value  the value to validate
1497      * @param max  the reference value
1498      * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
1499      * @param values  the optional values for the formatted exception message
1500      * @throws IllegalArgumentException if {@code value} is greater than {@code max}
1501      * @see #smallerOrEqual(double, double)
1502      *
1503      * @since 3.5
1504      */
1505     public static void smallerOrEqual(final double value, final double max, final String message, final Object... values) {
1506         if (!(value <= max)) {
1507             throw new IllegalArgumentException(String.format(message, values));
1508         }
1509     }
1510 
1511     // different
1512     //---------------------------------------------------------------------------------
1513 
1514     /**
1515      * <p>Validates that the specified argument is different from a given value
1516      * (reference); otherwise throwing an exception.</p>
1517      *
1518      * <p>Two objects are considered different if
1519      * {@code value.compareTo(reference) != 0}</p>
1520      *
1521      * <pre>Validate.differentObj(myObject, refObject);</pre>
1522      *
1523      * <p>The message of the exception is &quot;The value {@code value} is
1524      * invalid&quot;.</p>
1525      *
1526      * @param <T>  the type of the argument object
1527      * @param value  the object to validate
1528      * @param reference  the reference value
1529      * @throws IllegalArgumentException if {@code value} is equal to {@code reference}
1530      *
1531      * @since 3.5
1532      */
1533     public static <T> void differentObj(final Comparable<T> value, final T reference) {
1534         differentObj(value, reference, DEFAULT_DIFFERENT_EX_MESSAGE, value);
1535     }
1536 
1537     /**
1538      * <p>Validates that the specified argument is different from a given value
1539      * (reference); otherwise throwing an exception with the specified message.</p>
1540      *
1541      * <p>Two objects are considered different if
1542      * {@code value.compareTo(reference) != 0}</p>
1543      *
1544      * <pre>Validate.differentObj(myObject, refObject, "The value is invalid");</pre>
1545      *
1546      * @param <T>  the type of the argument object
1547      * @param value  the object to validate
1548      * @param reference  the reference value
1549      * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
1550      * @param values  the optional values for the formatted exception message
1551      * @throws IllegalArgumentException if {@code value} is equal to {@code reference}
1552      *
1553      * @since 3.5
1554      */
1555     public static <T> void differentObj(final Comparable<T> value, final T reference, final String message, final Object... values) {
1556         if (value.compareTo(reference) == 0) {
1557             throw new IllegalArgumentException(String.format(message, values));
1558         }
1559     }
1560 
1561     /**
1562      * <p>Validates that the specified argument is not equal to a given value
1563      * (reference); otherwise throwing an exception.</p>
1564      *
1565      * <pre>Validate.different(myLong, 0);</pre>
1566      *
1567      * <p>The message of the exception is &quot;The value {@code value} is
1568      * invalid&quot;.</p>
1569      *
1570      * @param value  the value to validate
1571      * @param reference  the reference value
1572      * @throws IllegalArgumentException if {@code value} is equal to {@code reference}
1573      *
1574      * @since 3.5
1575      */
1576     public static void different(final long value, final long reference) {
1577         different(value, reference, DEFAULT_DIFFERENT_EX_MESSAGE, value);
1578     }
1579 
1580     /**
1581      * <p>Validates that the specified argument is not equal to a given value
1582      * (reference); otherwise throwing an exception with the specified message.</p>
1583      *
1584      * <pre>Validate.different(myLong, 0, "The value is invalid");</pre>
1585      *
1586      * @param value  the value to validate
1587      * @param reference  the reference value
1588      * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
1589      * @param values  the optional values for the formatted exception message
1590      * @throws IllegalArgumentException if {@code value} is equal to {@code reference}
1591      *
1592      * @since 3.5
1593      */
1594     public static void different(final long value, final long reference, final String message, final Object... values) {
1595         if (value == reference) {
1596             throw new IllegalArgumentException(String.format(message, values));
1597         }
1598     }
1599 
1600     /**
1601      * <p>Validates that the specified argument is not equal to a given value
1602      * (reference); otherwise throwing an exception.</p>
1603      *
1604      * <p>If {@code value} or {@code reference} is {@code NaN}, no exception will be thrown.</p>
1605      *
1606      * <pre>Validate.different(myDouble, 0.0);</pre>
1607      *
1608      * <p>The message of the exception is &quot;The value {@code value} is
1609      * invalid&quot;.</p>
1610      *
1611      * @param value  the value to validate
1612      * @param reference  the reference value
1613      * @throws IllegalArgumentException if {@code value} is equal to {@code reference}
1614      *
1615      * @since 3.5
1616      */
1617     public static void different(final double value, final double reference) {
1618         different(value, reference, DEFAULT_DIFFERENT_EX_MESSAGE, value);
1619     }
1620 
1621     /**
1622      * <p>Validates that the specified argument is not equal to a given value
1623      * (reference); otherwise throwing an exception with the specified message.</p>
1624      *
1625      * <p>If {@code value} or {@code reference} is {@code NaN}, no exception will be thrown.</p>
1626      *
1627      * <pre>Validate.different(myDouble, 0.0, "The value is invalid");</pre>
1628      *
1629      * @param value  the value to validate
1630      * @param reference  the reference value
1631      * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
1632      * @param values  the optional values for the formatted exception message
1633      * @throws IllegalArgumentException if {@code value} is equal to {@code reference}
1634      *
1635      * @since 3.5
1636      */
1637     public static void different(final double value, final double reference, final String message, final Object... values) {
1638         if (value == reference) {
1639             throw new IllegalArgumentException(String.format(message, values));
1640         }
1641     }
1642 
1643     // inclusiveBetween
1644     //---------------------------------------------------------------------------------
1645 
1646     /**
1647      * <p>Validate that the specified argument object fall between the two
1648      * inclusive values specified; otherwise, throws an exception.</p>
1649      *
1650      * <pre>Validate.inclusiveBetween(0, 2, 1);</pre>
1651      *
1652      * @param <T> the type of the argument object
1653      * @param start  the inclusive start value, not null
1654      * @param end  the inclusive end value, not null
1655      * @param value  the object to validate, not null
1656      * @throws IllegalArgumentException if the value falls outside the boundaries
1657      * @see #inclusiveBetween(Object, Object, Comparable, String, Object...)
1658      *
1659      * @since 3.0
1660      */
1661     public static <T> void inclusiveBetween(final T start, final T end, final Comparable<T> value) {
1662         // TODO when breaking BC, consider returning value
1663         if (value.compareTo(start) < 0 || value.compareTo(end) > 0) {
1664             throw new IllegalArgumentException(String.format(DEFAULT_INCLUSIVE_BETWEEN_EX_MESSAGE, value, start, end));
1665         }
1666     }
1667 
1668     /**
1669      * <p>Validate that the specified argument object fall between the two
1670      * inclusive values specified; otherwise, throws an exception with the
1671      * specified message.</p>
1672      *
1673      * <pre>Validate.inclusiveBetween(0, 2, 1, "Not in boundaries");</pre>
1674      *
1675      * @param <T> the type of the argument object
1676      * @param start  the inclusive start value, not null
1677      * @param end  the inclusive end value, not null
1678      * @param value  the object to validate, not null
1679      * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
1680      * @param values  the optional values for the formatted exception message, null array not recommended
1681      * @throws IllegalArgumentException if the value falls outside the boundaries
1682      * @see #inclusiveBetween(Object, Object, Comparable)
1683      *
1684      * @since 3.0
1685      */
1686     public static <T> void inclusiveBetween(final T start, final T end, final Comparable<T> value, final String message, final Object... values) {
1687         // TODO when breaking BC, consider returning value
1688         if (value.compareTo(start) < 0 || value.compareTo(end) > 0) {
1689             throw new IllegalArgumentException(String.format(message, values));
1690         }
1691     }
1692 
1693     /**
1694     * Validate that the specified primitive value falls between the two
1695     * inclusive values specified; otherwise, throws an exception.
1696     *
1697     * <pre>Validate.inclusiveBetween(0, 2, 1);</pre>
1698     *
1699     * @param start the inclusive start value
1700     * @param end   the inclusive end value
1701     * @param value the value to validate
1702     * @throws IllegalArgumentException if the value falls outside the boundaries (inclusive)
1703     *
1704     * @since 3.3
1705     */
1706     @SuppressWarnings("boxing")
1707     public static void inclusiveBetween(final long start, final long end, final long value) {
1708         // TODO when breaking BC, consider returning value
1709         if (value < start || value > end) {
1710             throw new IllegalArgumentException(String.format(DEFAULT_INCLUSIVE_BETWEEN_EX_MESSAGE, value, start, end));
1711         }
1712     }
1713 
1714     /**
1715     * Validate that the specified primitive value falls between the two
1716     * inclusive values specified; otherwise, throws an exception with the
1717     * specified message.
1718     *
1719     * <pre>Validate.inclusiveBetween(0, 2, 1, "Not in range");</pre>
1720     *
1721     * @param start the inclusive start value
1722     * @param end   the inclusive end value
1723     * @param value the value to validate
1724     * @param message the exception message if invalid, not null
1725     *
1726     * @throws IllegalArgumentException if the value falls outside the boundaries
1727     *
1728     * @since 3.3
1729     */
1730     public static void inclusiveBetween(final long start, final long end, final long value, final String message) {
1731         // TODO when breaking BC, consider returning value
1732         if (value < start || value > end) {
1733             throw new IllegalArgumentException(String.format(message));
1734         }
1735     }
1736 
1737     /**
1738     * Validate that the specified primitive value falls between the two
1739     * inclusive values specified; otherwise, throws an exception.
1740     *
1741     * <pre>Validate.inclusiveBetween(0.1, 2.1, 1.1);</pre>
1742     *
1743     * @param start the inclusive start value
1744     * @param end   the inclusive end value
1745     * @param value the value to validate
1746     * @throws IllegalArgumentException if the value falls outside the boundaries (inclusive)
1747     *
1748     * @since 3.3
1749     */
1750     @SuppressWarnings("boxing")
1751     public static void inclusiveBetween(final double start, final double end, final double value) {
1752         // TODO when breaking BC, consider returning value
1753         if (value < start || value > end) {
1754             throw new IllegalArgumentException(String.format(DEFAULT_INCLUSIVE_BETWEEN_EX_MESSAGE, value, start, end));
1755         }
1756     }
1757 
1758     /**
1759     * Validate that the specified primitive value falls between the two
1760     * inclusive values specified; otherwise, throws an exception with the
1761     * specified message.
1762     *
1763     * <pre>Validate.inclusiveBetween(0.1, 2.1, 1.1, "Not in range");</pre>
1764     *
1765     * @param start the inclusive start value
1766     * @param end   the inclusive end value
1767     * @param value the value to validate
1768     * @param message the exception message if invalid, not null
1769     *
1770     * @throws IllegalArgumentException if the value falls outside the boundaries
1771     *
1772     * @since 3.3
1773     */
1774     public static void inclusiveBetween(final double start, final double end, final double value, final String message) {
1775         // TODO when breaking BC, consider returning value
1776         if (value < start || value > end) {
1777             throw new IllegalArgumentException(String.format(message));
1778         }
1779     }
1780 
1781     // exclusiveBetween
1782     //---------------------------------------------------------------------------------
1783 
1784     /**
1785      * <p>Validate that the specified argument object fall between the two
1786      * exclusive values specified; otherwise, throws an exception.</p>
1787      *
1788      * <pre>Validate.exclusiveBetween(0, 2, 1);</pre>
1789      *
1790      * @param <T> the type of the argument object
1791      * @param start  the exclusive start value, not null
1792      * @param end  the exclusive end value, not null
1793      * @param value  the object to validate, not null
1794      * @throws IllegalArgumentException if the value falls outside the boundaries
1795      * @see #exclusiveBetween(Object, Object, Comparable, String, Object...)
1796      *
1797      * @since 3.0
1798      */
1799     public static <T> void exclusiveBetween(final T start, final T end, final Comparable<T> value) {
1800         // TODO when breaking BC, consider returning value
1801         if (value.compareTo(start) <= 0 || value.compareTo(end) >= 0) {
1802             throw new IllegalArgumentException(String.format(DEFAULT_EXCLUSIVE_BETWEEN_EX_MESSAGE, value, start, end));
1803         }
1804     }
1805 
1806     /**
1807      * <p>Validate that the specified argument object fall between the two
1808      * exclusive values specified; otherwise, throws an exception with the
1809      * specified message.</p>
1810      *
1811      * <pre>Validate.exclusiveBetween(0, 2, 1, "Not in boundaries");</pre>
1812      *
1813      * @param <T> the type of the argument object
1814      * @param start  the exclusive start value, not null
1815      * @param end  the exclusive end value, not null
1816      * @param value  the object to validate, not null
1817      * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
1818      * @param values  the optional values for the formatted exception message, null array not recommended
1819      * @throws IllegalArgumentException if the value falls outside the boundaries
1820      * @see #exclusiveBetween(Object, Object, Comparable)
1821      *
1822      * @since 3.0
1823      */
1824     public static <T> void exclusiveBetween(final T start, final T end, final Comparable<T> value, final String message, final Object... values) {
1825         // TODO when breaking BC, consider returning value
1826         if (value.compareTo(start) <= 0 || value.compareTo(end) >= 0) {
1827             throw new IllegalArgumentException(String.format(message, values));
1828         }
1829     }
1830 
1831     /**
1832     * Validate that the specified primitive value falls between the two
1833     * exclusive values specified; otherwise, throws an exception.
1834     *
1835     * <pre>Validate.exclusiveBetween(0, 2, 1);</pre>
1836     *
1837     * @param start the exclusive start value
1838     * @param end   the exclusive end value
1839     * @param value the value to validate
1840     * @throws IllegalArgumentException if the value falls out of the boundaries
1841     *
1842     * @since 3.3
1843     */
1844     @SuppressWarnings("boxing")
1845     public static void exclusiveBetween(final long start, final long end, final long value) {
1846         // TODO when breaking BC, consider returning value
1847         if (value <= start || value >= end) {
1848             throw new IllegalArgumentException(String.format(DEFAULT_EXCLUSIVE_BETWEEN_EX_MESSAGE, value, start, end));
1849         }
1850     }
1851 
1852     /**
1853     * Validate that the specified primitive value falls between the two
1854     * exclusive values specified; otherwise, throws an exception with the
1855     * specified message.
1856     *
1857     * <pre>Validate.exclusiveBetween(0, 2, 1, "Not in range");</pre>
1858     *
1859     * @param start the exclusive start value
1860     * @param end   the exclusive end value
1861     * @param value the value to validate
1862     * @param message the exception message if invalid, not null
1863     *
1864     * @throws IllegalArgumentException if the value falls outside the boundaries
1865     *
1866     * @since 3.3
1867     */
1868     public static void exclusiveBetween(final long start, final long end, final long value, final String message) {
1869         // TODO when breaking BC, consider returning value
1870         if (value <= start || value >= end) {
1871             throw new IllegalArgumentException(String.format(message));
1872         }
1873     }
1874 
1875     /**
1876     * Validate that the specified primitive value falls between the two
1877     * exclusive values specified; otherwise, throws an exception.
1878     *
1879     * <pre>Validate.exclusiveBetween(0.1, 2.1, 1.1);</pre>
1880     *
1881     * @param start the exclusive start value
1882     * @param end   the exclusive end value
1883     * @param value the value to validate
1884     * @throws IllegalArgumentException if the value falls out of the boundaries
1885     *
1886     * @since 3.3
1887     */
1888     @SuppressWarnings("boxing")
1889     public static void exclusiveBetween(final double start, final double end, final double value) {
1890         // TODO when breaking BC, consider returning value
1891         if (value <= start || value >= end) {
1892             throw new IllegalArgumentException(String.format(DEFAULT_EXCLUSIVE_BETWEEN_EX_MESSAGE, value, start, end));
1893         }
1894     }
1895 
1896     /**
1897     * Validate that the specified primitive value falls between the two
1898     * exclusive values specified; otherwise, throws an exception with the
1899     * specified message.
1900     *
1901     * <pre>Validate.exclusiveBetween(0.1, 2.1, 1.1, "Not in range");</pre>
1902     *
1903     * @param start the exclusive start value
1904     * @param end   the exclusive end value
1905     * @param value the value to validate
1906     * @param message the exception message if invalid, not null
1907     *
1908     * @throws IllegalArgumentException if the value falls outside the boundaries
1909     *
1910     * @since 3.3
1911     */
1912     public static void exclusiveBetween(final double start, final double end, final double value, final String message) {
1913         // TODO when breaking BC, consider returning value
1914         if (value <= start || value >= end) {
1915             throw new IllegalArgumentException(String.format(message));
1916         }
1917     }
1918 
1919     // isInstanceOf
1920     //---------------------------------------------------------------------------------
1921 
1922     /**
1923      * Validates that the argument is an instance of the specified class, if not throws an exception.
1924      *
1925      * <p>This method is useful when validating according to an arbitrary class</p>
1926      *
1927      * <pre>Validate.isInstanceOf(OkClass.class, object);</pre>
1928      *
1929      * <p>The message of the exception is &quot;Expected type: {type}, actual: {obj_type}&quot;</p>
1930      *
1931      * @param type  the class the object must be validated against, not null
1932      * @param obj  the object to check, null throws an exception
1933      * @throws IllegalArgumentException if argument is not of specified class
1934      * @see #isInstanceOf(Class, Object, String, Object...)
1935      *
1936      * @since 3.0
1937      */
1938     public static void isInstanceOf(final Class<?> type, final Object obj) {
1939         // TODO when breaking BC, consider returning obj
1940         if (type.isInstance(obj) == false) {
1941             throw new IllegalArgumentException(String.format(DEFAULT_IS_INSTANCE_OF_EX_MESSAGE, type.getName(),
1942                     obj == null ? "null" : obj.getClass().getName()));
1943         }
1944     }
1945 
1946     /**
1947      * <p>Validate that the argument is an instance of the specified class; otherwise
1948      * throwing an exception with the specified message. This method is useful when
1949      * validating according to an arbitrary class</p>
1950      *
1951      * <pre>Validate.isInstanceOf(OkClass.class, object, "Wrong class, object is of class %s",
1952      *   object.getClass().getName());</pre>
1953      *
1954      * @param type  the class the object must be validated against, not null
1955      * @param obj  the object to check, null throws an exception
1956      * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
1957      * @param values  the optional values for the formatted exception message, null array not recommended
1958      * @throws IllegalArgumentException if argument is not of specified class
1959      * @see #isInstanceOf(Class, Object)
1960      *
1961      * @since 3.0
1962      */
1963     public static void isInstanceOf(final Class<?> type, final Object obj, final String message, final Object... values) {
1964         // TODO when breaking BC, consider returning obj
1965         if (type.isInstance(obj) == false) {
1966             throw new IllegalArgumentException(String.format(message, values));
1967         }
1968     }
1969 
1970     // isAssignableFrom
1971     //---------------------------------------------------------------------------------
1972 
1973     /**
1974      * Validates that the argument can be converted to the specified class, if not, throws an exception.
1975      *
1976      * <p>This method is useful when validating that there will be no casting errors.</p>
1977      *
1978      * <pre>Validate.isAssignableFrom(SuperClass.class, object.getClass());</pre>
1979      *
1980      * <p>The message format of the exception is &quot;Cannot assign {type} to {superType}&quot;</p>
1981      *
1982      * @param superType  the class the class must be validated against, not null
1983      * @param type  the class to check, not null
1984      * @throws IllegalArgumentException if type argument is not assignable to the specified superType
1985      * @see #isAssignableFrom(Class, Class, String, Object...)
1986      *
1987      * @since 3.0
1988      */
1989     public static void isAssignableFrom(final Class<?> superType, final Class<?> type) {
1990         // TODO when breaking BC, consider returning type
1991         if (superType.isAssignableFrom(type) == false) {
1992             throw new IllegalArgumentException(String.format(DEFAULT_IS_ASSIGNABLE_EX_MESSAGE, type == null ? "null" : type.getName(),
1993                     superType.getName()));
1994         }
1995     }
1996 
1997     /**
1998      * Validates that the argument can be converted to the specified class, if not throws an exception.
1999      *
2000      * <p>This method is useful when validating if there will be no casting errors.</p>
2001      *
2002      * <pre>Validate.isAssignableFrom(SuperClass.class, object.getClass());</pre>
2003      *
2004      * <p>The message of the exception is &quot;The validated object can not be converted to the&quot;
2005      * followed by the name of the class and &quot;class&quot;</p>
2006      *
2007      * @param superType  the class the class must be validated against, not null
2008      * @param type  the class to check, not null
2009      * @param message  the {@link String#format(String, Object...)} exception message if invalid, not null
2010      * @param values  the optional values for the formatted exception message, null array not recommended
2011      * @throws IllegalArgumentException if argument can not be converted to the specified class
2012      * @see #isAssignableFrom(Class, Class)
2013      */
2014     public static void isAssignableFrom(final Class<?> superType, final Class<?> type, final String message, final Object... values) {
2015         // TODO when breaking BC, consider returning type
2016         if (superType.isAssignableFrom(type) == false) {
2017             throw new IllegalArgumentException(String.format(message, values));
2018         }
2019     }
2020 }