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