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