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