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