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