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