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