001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.commons.lang3;
018
019import java.util.Collection;
020import java.util.Iterator;
021import java.util.Map;
022import java.util.Objects;
023import java.util.function.Supplier;
024import java.util.regex.Pattern;
025
026/**
027 * This class assists in validating arguments. The validation methods are
028 * based along the following principles:
029 * <ul>
030 *   <li>An invalid {@code null} argument causes a {@link NullPointerException}.</li>
031 *   <li>A non-{@code null} argument causes an {@link IllegalArgumentException}.</li>
032 *   <li>An invalid index into an array/collection/map/string causes an {@link IndexOutOfBoundsException}.</li>
033 * </ul>
034 *
035 * <p>All exceptions messages are
036 * <a href="https://docs.oracle.com/javase/8/docs/api/java/util/Formatter.html#syntax">format strings</a>
037 * as defined by the Java platform. For example:
038 *
039 * <pre>
040 * Validate.isTrue(i &gt; 0, "The value must be greater than zero: %d", i);
041 * Validate.notNull(surname, "The surname must not be %s", null);
042 * </pre>
043 *
044 * <p>#ThreadSafe#</p>
045 * @see String#format(String, Object...)
046 * @since 2.0
047 */
048public class Validate {
049
050    private static final String DEFAULT_NOT_NAN_EX_MESSAGE =
051        "The validated value is not a number";
052    private static final String DEFAULT_FINITE_EX_MESSAGE =
053        "The value is invalid: %f";
054    private static final String DEFAULT_EXCLUSIVE_BETWEEN_EX_MESSAGE =
055        "The value %s is not in the specified exclusive range of %s to %s";
056    private static final String DEFAULT_INCLUSIVE_BETWEEN_EX_MESSAGE =
057        "The value %s is not in the specified inclusive range of %s to %s";
058    private static final String DEFAULT_MATCHES_PATTERN_EX = "The string %s does not match the pattern %s";
059    private static final String DEFAULT_IS_NULL_EX_MESSAGE = "The validated object is null";
060    private static final String DEFAULT_IS_TRUE_EX_MESSAGE = "The validated expression is false";
061    private static final String DEFAULT_NO_NULL_ELEMENTS_ARRAY_EX_MESSAGE =
062        "The validated array contains null element at index: %d";
063    private static final String DEFAULT_NO_NULL_ELEMENTS_COLLECTION_EX_MESSAGE =
064        "The validated collection contains null element at index: %d";
065    private static final String DEFAULT_NOT_BLANK_EX_MESSAGE = "The validated character sequence is blank";
066    private static final String DEFAULT_NOT_EMPTY_ARRAY_EX_MESSAGE = "The validated array is empty";
067    private static final String DEFAULT_NOT_EMPTY_CHAR_SEQUENCE_EX_MESSAGE =
068        "The validated character sequence is empty";
069    private static final String DEFAULT_NOT_EMPTY_COLLECTION_EX_MESSAGE = "The validated collection is empty";
070    private static final String DEFAULT_NOT_EMPTY_MAP_EX_MESSAGE = "The validated map is empty";
071    private static final String DEFAULT_VALID_INDEX_ARRAY_EX_MESSAGE = "The validated array index is invalid: %d";
072    private static final String DEFAULT_VALID_INDEX_CHAR_SEQUENCE_EX_MESSAGE =
073        "The validated character sequence index is invalid: %d";
074    private static final String DEFAULT_VALID_INDEX_COLLECTION_EX_MESSAGE =
075        "The validated collection index is invalid: %d";
076    private static final String DEFAULT_VALID_STATE_EX_MESSAGE = "The validated state is false";
077    private static final String DEFAULT_IS_ASSIGNABLE_EX_MESSAGE = "Cannot assign a %s to a %s";
078    private static final String DEFAULT_IS_INSTANCE_OF_EX_MESSAGE = "Expected type: %s, actual: %s";
079
080    /**
081     * Validate that the specified primitive value falls between the two
082     * exclusive values specified; otherwise, throws an exception.
083     *
084     * <pre>Validate.exclusiveBetween(0.1, 2.1, 1.1);</pre>
085     *
086     * @param start the exclusive start value
087     * @param end   the exclusive end value
088     * @param value the value to validate
089     * @throws IllegalArgumentException if the value falls out of the boundaries
090     * @since 3.3
091     */
092    @SuppressWarnings("boxing")
093    public static void exclusiveBetween(final double start, final double end, final double value) {
094        // TODO when breaking BC, consider returning value
095        if (value <= start || value >= end) {
096            throw new IllegalArgumentException(String.format(DEFAULT_EXCLUSIVE_BETWEEN_EX_MESSAGE, value, start, end));
097        }
098    }
099
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}