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