001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements. See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License. You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017 package org.apache.commons.lang3;
018
019 import java.util.Collection;
020 import java.util.Iterator;
021 import java.util.Map;
022 import java.util.regex.Pattern;
023
024 /**
025 * <p>This class assists in validating arguments. The validation methods are
026 * based along the following principles:
027 * <ul>
028 * <li>An invalid {@code null} argument causes a {@link NullPointerException}.</li>
029 * <li>A non-{@code null} argument causes an {@link IllegalArgumentException}.</li>
030 * <li>An invalid index into an array/collection/map/string causes an {@link IndexOutOfBoundsException}.</li>
031 * </ul>
032 *
033 * <p>All exceptions messages are
034 * <a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Formatter.html#syntax">format strings</a>
035 * as defined by the Java platform. For example:</p>
036 *
037 * <pre>
038 * Validate.isTrue(i > 0, "The value must be greater than zero: %d", i);
039 * Validate.notNull(surname, "The surname must not be %s", null);
040 * </pre>
041 *
042 * <p>#ThreadSafe#</p>
043 * @version $Id: Validate.java 1199983 2011-11-09 21:41:24Z ggregory $
044 * @see java.lang.String#format(String, Object...)
045 * @since 2.0
046 */
047 public class Validate {
048
049 private static final String DEFAULT_EXCLUSIVE_BETWEEN_EX_MESSAGE =
050 "The value %s is not in the specified exclusive range of %s to %s";
051 private static final String DEFAULT_INCLUSIVE_BETWEEN_EX_MESSAGE =
052 "The value %s is not in the specified inclusive range of %s to %s";
053 private static final String DEFAULT_MATCHES_PATTERN_EX = "The string %s does not match the pattern %s";
054 private static final String DEFAULT_IS_NULL_EX_MESSAGE = "The validated object is null";
055 private static final String DEFAULT_IS_TRUE_EX_MESSAGE = "The validated expression is false";
056 private static final String DEFAULT_NO_NULL_ELEMENTS_ARRAY_EX_MESSAGE =
057 "The validated array contains null element at index: %d";
058 private static final String DEFAULT_NO_NULL_ELEMENTS_COLLECTION_EX_MESSAGE =
059 "The validated collection contains null element at index: %d";
060 private static final String DEFAULT_NOT_BLANK_EX_MESSAGE = "The validated character sequence is blank";
061 private static final String DEFAULT_NOT_EMPTY_ARRAY_EX_MESSAGE = "The validated array is empty";
062 private static final String DEFAULT_NOT_EMPTY_CHAR_SEQUENCE_EX_MESSAGE =
063 "The validated character sequence is empty";
064 private static final String DEFAULT_NOT_EMPTY_COLLECTION_EX_MESSAGE = "The validated collection is empty";
065 private static final String DEFAULT_NOT_EMPTY_MAP_EX_MESSAGE = "The validated map is empty";
066 private static final String DEFAULT_VALID_INDEX_ARRAY_EX_MESSAGE = "The validated array index is invalid: %d";
067 private static final String DEFAULT_VALID_INDEX_CHAR_SEQUENCE_EX_MESSAGE =
068 "The validated character sequence index is invalid: %d";
069 private static final String DEFAULT_VALID_INDEX_COLLECTION_EX_MESSAGE =
070 "The validated collection index is invalid: %d";
071 private static final String DEFAULT_VALID_STATE_EX_MESSAGE = "The validated state is false";
072 private static final String DEFAULT_IS_ASSIGNABLE_EX_MESSAGE = "Cannot assign a %s to a %s";
073 private static final String DEFAULT_IS_INSTANCE_OF_EX_MESSAGE = "Expected type: %s, actual: %s";
074
075 /**
076 * Constructor. This class should not normally be instantiated.
077 */
078 public Validate() {
079 super();
080 }
081
082 // isTrue
083 //---------------------------------------------------------------------------------
084
085 /**
086 * <p>Validate that the argument condition is {@code true}; otherwise
087 * throwing an exception with the specified message. This method is useful when
088 * validating according to an arbitrary boolean expression, such as validating a
089 * primitive number or using your own custom validation expression.</p>
090 *
091 * <pre>Validate.isTrue(i > 0.0, "The value must be greater than zero: %d", i);</pre>
092 *
093 * <p>For performance reasons, the long value is passed as a separate parameter and
094 * appended to the exception message only in the case of an error.</p>
095 *
096 * @param expression the boolean expression to check
097 * @param message the {@link String#format(String, Object...)} exception message if invalid, not null
098 * @param value the value to append to the message when invalid
099 * @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(boolean expression, String message, 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(boolean expression, String message, 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(boolean expression, String message, 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(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(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(T object, String message, 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(T[] array, String message, 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(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(T collection, String message, 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(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(T map, String message, 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(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(T chars, String message, 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(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(T chars, String message, 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(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(T[] array, String message, Object... values) {
506 Validate.notNull(array);
507 for (int i = 0; i < array.length; i++) {
508 if (array[i] == null) {
509 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(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(T iterable, String message, Object... values) {
568 Validate.notNull(iterable);
569 int i = 0;
570 for (Iterator<?> it = iterable.iterator(); it.hasNext(); i++) {
571 if (it.next() == null) {
572 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(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(T[] array, int index, String message, 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(T[] array, 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(T collection, int index, String message, 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(T collection, 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(T chars, int index, String message, 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(T chars, 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(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(boolean expression, String message, 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(CharSequence input, String pattern) {
849 if (Pattern.matches(pattern, input) == false) {
850 throw new IllegalArgumentException(String.format(DEFAULT_MATCHES_PATTERN_EX, input, pattern));
851 }
852 }
853
854 /**
855 * <p>Validate that the specified argument character sequence matches the specified regular
856 * expression pattern; otherwise throwing an exception with the specified message.</p>
857 *
858 * <pre>Validate.matchesPattern("hi", "[a-z]*", "%s does not match %s", "hi" "[a-z]*");</pre>
859 *
860 * <p>The syntax of the pattern is the one used in the {@link Pattern} class.</p>
861 *
862 * @param input the character sequence to validate, not null
863 * @param pattern the regular expression pattern, not null
864 * @param message the {@link String#format(String, Object...)} exception message if invalid, not null
865 * @param values the optional values for the formatted exception message, null array not recommended
866 * @throws IllegalArgumentException if the character sequence does not match the pattern
867 * @see #matchesPattern(CharSequence, String)
868 *
869 * @since 3.0
870 */
871 public static void matchesPattern(CharSequence input, String pattern, String message, Object... values) {
872 if (Pattern.matches(pattern, input) == false) {
873 throw new IllegalArgumentException(String.format(message, values));
874 }
875 }
876
877 // inclusiveBetween
878 //---------------------------------------------------------------------------------
879
880 /**
881 * <p>Validate that the specified argument object fall between the two
882 * inclusive values specified; otherwise, throws an exception.</p>
883 *
884 * <pre>Validate.inclusiveBetween(0, 2, 1);</pre>
885 *
886 * @param <T> the type of the argument object
887 * @param start the inclusive start value, not null
888 * @param end the inclusive end value, not null
889 * @param value the object to validate, not null
890 * @throws IllegalArgumentException if the value falls out of the boundaries
891 * @see #inclusiveBetween(Object, Object, Comparable, String, Object...)
892 *
893 * @since 3.0
894 */
895 public static <T> void inclusiveBetween(T start, T end, Comparable<T> value) {
896 if (value.compareTo(start) < 0 || value.compareTo(end) > 0) {
897 throw new IllegalArgumentException(String.format(DEFAULT_INCLUSIVE_BETWEEN_EX_MESSAGE, value, start, end));
898 }
899 }
900
901 /**
902 * <p>Validate that the specified argument object fall between the two
903 * inclusive values specified; otherwise, throws an exception with the
904 * specified message.</p>
905 *
906 * <pre>Validate.inclusiveBetween(0, 2, 1, "Not in boundaries");</pre>
907 *
908 * @param <T> the type of the argument object
909 * @param start the inclusive start value, not null
910 * @param end the inclusive end value, not null
911 * @param value the object to validate, not null
912 * @param message the {@link String#format(String, Object...)} exception message if invalid, not null
913 * @param values the optional values for the formatted exception message, null array not recommended
914 * @throws IllegalArgumentException if the value falls out of the boundaries
915 * @see #inclusiveBetween(Object, Object, Comparable)
916 *
917 * @since 3.0
918 */
919 public static <T> void inclusiveBetween(T start, T end, Comparable<T> value, String message, Object... values) {
920 if (value.compareTo(start) < 0 || value.compareTo(end) > 0) {
921 throw new IllegalArgumentException(String.format(message, values));
922 }
923 }
924
925 // exclusiveBetween
926 //---------------------------------------------------------------------------------
927
928 /**
929 * <p>Validate that the specified argument object fall between the two
930 * exclusive values specified; otherwise, throws an exception.</p>
931 *
932 * <pre>Validate.inclusiveBetween(0, 2, 1);</pre>
933 *
934 * @param <T> the type of the argument object
935 * @param start the exclusive start value, not null
936 * @param end the exclusive end value, not null
937 * @param value the object to validate, not null
938 * @throws IllegalArgumentException if the value falls out of the boundaries
939 * @see #exclusiveBetween(Object, Object, Comparable, String, Object...)
940 *
941 * @since 3.0
942 */
943 public static <T> void exclusiveBetween(T start, T end, Comparable<T> value) {
944 if (value.compareTo(start) <= 0 || value.compareTo(end) >= 0) {
945 throw new IllegalArgumentException(String.format(DEFAULT_EXCLUSIVE_BETWEEN_EX_MESSAGE, value, start, end));
946 }
947 }
948
949 /**
950 * <p>Validate that the specified argument object fall between the two
951 * exclusive values specified; otherwise, throws an exception with the
952 * specified message.</p>
953 *
954 * <pre>Validate.inclusiveBetween(0, 2, 1, "Not in boundaries");</pre>
955 *
956 * @param <T> the type of the argument object
957 * @param start the exclusive start value, not null
958 * @param end the exclusive end value, not null
959 * @param value the object to validate, not null
960 * @param message the {@link String#format(String, Object...)} exception message if invalid, not null
961 * @param values the optional values for the formatted exception message, null array not recommended
962 * @throws IllegalArgumentException if the value falls out of the boundaries
963 * @see #exclusiveBetween(Object, Object, Comparable)
964 *
965 * @since 3.0
966 */
967 public static <T> void exclusiveBetween(T start, T end, Comparable<T> value, String message, Object... values) {
968 if (value.compareTo(start) <= 0 || value.compareTo(end) >= 0) {
969 throw new IllegalArgumentException(String.format(message, values));
970 }
971 }
972
973 // isInstanceOf
974 //---------------------------------------------------------------------------------
975
976 /**
977 * Validates that the argument is an instance of the specified class, if not throws an exception.
978 *
979 * <p>This method is useful when validating according to an arbitrary class</p>
980 *
981 * <pre>Validate.isInstanceOf(OkClass.class, object);</pre>
982 *
983 * <p>The message of the exception is "Expected type: {type}, actual: {obj_type}"</p>
984 *
985 * @param type the class the object must be validated against, not null
986 * @param obj the object to check, null throws an exception
987 * @throws IllegalArgumentException if argument is not of specified class
988 * @see #isInstanceOf(Class, Object, String, Object...)
989 *
990 * @since 3.0
991 */
992 public static void isInstanceOf(Class<?> type, Object obj) {
993 if (type.isInstance(obj) == false) {
994 throw new IllegalArgumentException(String.format(DEFAULT_IS_INSTANCE_OF_EX_MESSAGE, type.getName(),
995 obj == null ? "null" : obj.getClass().getName()));
996 }
997 }
998
999 /**
1000 * <p>Validate that the argument is an instance of the specified class; otherwise
1001 * throwing an exception with the specified message. This method is useful when
1002 * validating according to an arbitrary class</p>
1003 *
1004 * <pre>Validate.isInstanceOf(OkClass.classs, object, "Wrong class, object is of class %s",
1005 * object.getClass().getName());</pre>
1006 *
1007 * @param type the class the object must be validated against, not null
1008 * @param obj the object to check, null throws an exception
1009 * @param message the {@link String#format(String, Object...)} exception message if invalid, not null
1010 * @param values the optional values for the formatted exception message, null array not recommended
1011 * @throws IllegalArgumentException if argument is not of specified class
1012 * @see #isInstanceOf(Class, Object)
1013 *
1014 * @since 3.0
1015 */
1016 public static void isInstanceOf(Class<?> type, Object obj, String message, Object... values) {
1017 if (type.isInstance(obj) == false) {
1018 throw new IllegalArgumentException(String.format(message, values));
1019 }
1020 }
1021
1022 // isAssignableFrom
1023 //---------------------------------------------------------------------------------
1024
1025 /**
1026 * Validates that the argument can be converted to the specified class, if not, throws an exception.
1027 *
1028 * <p>This method is useful when validating that there will be no casting errors.</p>
1029 *
1030 * <pre>Validate.isAssignableFrom(SuperClass.class, object.getClass());</pre>
1031 *
1032 * <p>The message format of the exception is "Cannot assign {type} to {superType}"</p>
1033 *
1034 * @param superType the class the class must be validated against, not null
1035 * @param type the class to check, not null
1036 * @throws IllegalArgumentException if type argument is not assignable to the specified superType
1037 * @see #isAssignableFrom(Class, Class, String, Object...)
1038 *
1039 * @since 3.0
1040 */
1041 public static void isAssignableFrom(Class<?> superType, Class<?> type) {
1042 if (superType.isAssignableFrom(type) == false) {
1043 throw new IllegalArgumentException(String.format(DEFAULT_IS_ASSIGNABLE_EX_MESSAGE, type == null ? "null" : type.getName(),
1044 superType.getName()));
1045 }
1046 }
1047
1048 /**
1049 * Validates that the argument can be converted to the specified class, if not throws an exception.
1050 *
1051 * <p>This method is useful when validating if there will be no casting errors.</p>
1052 *
1053 * <pre>Validate.isAssignableFrom(SuperClass.class, object.getClass());</pre>
1054 *
1055 * <p>The message of the exception is "The validated object can not be converted to the"
1056 * followed by the name of the class and "class"</p>
1057 *
1058 * @param superType the class the class must be validated against, not null
1059 * @param type the class to check, not null
1060 * @param message the {@link String#format(String, Object...)} exception message if invalid, not null
1061 * @param values the optional values for the formatted exception message, null array not recommended
1062 * @throws IllegalArgumentException if argument can not be converted to the specified class
1063 * @see #isAssignableFrom(Class, Class)
1064 */
1065 public static void isAssignableFrom(Class<?> superType, Class<?> type, String message, Object... values) {
1066 if (superType.isAssignableFrom(type) == false) {
1067 throw new IllegalArgumentException(String.format(message, values));
1068 }
1069 }
1070 }