    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}