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.lang;
018
019 import java.util.Collection;
020 import java.util.Iterator;
021 import java.util.Map;
022
023 /**
024 * <p>Assists in validating arguments.</p>
025 *
026 * <p>The class is based along the lines of JUnit. If an argument value is
027 * deemed invalid, an IllegalArgumentException is thrown. For example:</p>
028 *
029 * <pre>
030 * Validate.isTrue( i > 0, "The value must be greater than zero: ", i);
031 * Validate.notNull( surname, "The surname must not be null");
032 * </pre>
033 *
034 * @author <a href="mailto:ola.berg@arkitema.se">Ola Berg</a>
035 * @author Stephen Colebourne
036 * @author Gary Gregory
037 * @author Norm Deane
038 * @since 2.0
039 * @version $Id: Validate.java 437554 2006-08-28 06:21:41Z bayard $
040 */
041 public class Validate {
042 // Validate has no dependencies on other classes in Commons Lang at present
043
044 /**
045 * Constructor. This class should not normally be instantiated.
046 */
047 public Validate() {
048 super();
049 }
050
051 // isTrue
052 //---------------------------------------------------------------------------------
053
054 /**
055 * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
056 * if the test result is <code>false</code>.</p>
057 *
058 * <p>This is used when validating according to an arbitrary boolean expression,
059 * such as validating a primitive number or using your own custom validation
060 * expression.</p>
061 *
062 * <pre>
063 * Validate.isTrue( myObject.isOk(), "The object is not OK: ", myObject);
064 * </pre>
065 *
066 * <p>For performance reasons, the object is passed as a separate parameter and
067 * appended to the message string only in the case of an error.</p>
068 *
069 * @param expression a boolean expression
070 * @param message the exception message you would like to see if the
071 * expression is <code>false</code>
072 * @param value the value to append to the message in case of error
073 * @throws IllegalArgumentException if expression is <code>false</code>
074 */
075 public static void isTrue(boolean expression, String message, Object value) {
076 if (expression == false) {
077 throw new IllegalArgumentException(message + value);
078 }
079 }
080
081 /**
082 * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
083 * if the test result is <code>false</code>.</p>
084 *
085 * <p>This is used when validating according to an arbitrary boolean expression,
086 * such as validating a primitive number or using your own custom validation
087 * expression.</p>
088 *
089 * <pre>
090 * Validate.isTrue( i > 0, "The value must be greater than zero: ", i);
091 * </pre>
092 *
093 * <p>For performance reasons, the long value is passed as a separate parameter and
094 * appended to the message string only in the case of an error.</p>
095 *
096 * @param expression a boolean expression
097 * @param message the exception message you would like to see if the expression is <code>false</code>
098 * @param value the value to append to the message in case of error
099 * @throws IllegalArgumentException if expression is <code>false</code>
100 */
101 public static void isTrue(boolean expression, String message, long value) {
102 if (expression == false) {
103 throw new IllegalArgumentException(message + value);
104 }
105 }
106
107 /**
108 * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
109 * if the test result is <code>false</code>.</p>
110 *
111 * <p>This is used when validating according to an arbitrary boolean expression,
112 * such as validating a primitive number or using your own custom validation
113 * expression.</p>
114 *
115 * <pre>
116 * Validate.isTrue( d > 0.0, "The value must be greater than zero: ", d);
117 * </pre>
118 *
119 * <p>For performance reasons, the double value is passed as a separate parameter and
120 * appended to the message string only in the case of an error.</p>
121 *
122 * @param expression a boolean expression
123 * @param message the exception message you would like to see if the expression
124 * is <code>false</code>
125 * @param value the value to append to the message in case of error
126 * @throws IllegalArgumentException if expression is <code>false</code>
127 */
128 public static void isTrue(boolean expression, String message, double value) {
129 if (expression == false) {
130 throw new IllegalArgumentException(message + value);
131 }
132 }
133
134 /**
135 * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
136 * if the test result is <code>false</code>.</p>
137 *
138 * <p>This is used when validating according to an arbitrary boolean expression,
139 * such as validating a primitive number or using your own custom validation
140 * expression.</p>
141 *
142 * <pre>
143 * Validate.isTrue( (i > 0), "The value must be greater than zero");
144 * Validate.isTrue( myObject.isOk(), "The object is not OK");
145 * </pre>
146 *
147 * <p>For performance reasons, the message string should not involve a string append,
148 * instead use the {@link #isTrue(boolean, String, Object)} method.</p>
149 *
150 * @param expression a boolean expression
151 * @param message the exception message you would like to see if the expression
152 * is <code>false</code>
153 * @throws IllegalArgumentException if expression is <code>false</code>
154 */
155 public static void isTrue(boolean expression, String message) {
156 if (expression == false) {
157 throw new IllegalArgumentException(message);
158 }
159 }
160
161 /**
162 * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
163 * if the test result is <code>false</code>.</p>
164 *
165 * <p>This is used when validating according to an arbitrary boolean expression,
166 * such as validating a primitive number or using your own custom validation
167 * expression.</p>
168 *
169 * <pre>
170 * Validate.isTrue( i > 0 );
171 * Validate.isTrue( myObject.isOk() );
172 * </pre>
173 *
174 * <p>The message in the exception is 'The validated expression is false'.</p>
175 *
176 * @param expression a boolean expression
177 * @throws IllegalArgumentException if expression is <code>false</code>
178 */
179 public static void isTrue(boolean expression) {
180 if (expression == false) {
181 throw new IllegalArgumentException("The validated expression is false");
182 }
183 }
184
185 // notNull
186 //---------------------------------------------------------------------------------
187
188 /**
189 * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
190 * if the argument is <code>null</code>.</p>
191 *
192 * <pre>
193 * Validate.notNull(myObject, "The object must not be null");
194 * </pre>
195 *
196 * @param object the object to check is not <code>null</code>
197 * @param message the exception message you would like to see
198 * if the object is <code>null</code>
199 * @throws IllegalArgumentException if the object is <code>null</code>
200 */
201 public static void notNull(Object object, String message) {
202 if (object == null) {
203 throw new IllegalArgumentException(message);
204 }
205 }
206
207 /**
208 * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
209 * if the argument is <code>null</code>.</p>
210 *
211 * <pre>
212 * Validate.notNull(myObject);
213 * </pre>
214 *
215 * <p>The message in the exception is 'The validated object is null'.</p>
216 *
217 * @param object the object to check is not <code>null</code>
218 * @throws IllegalArgumentException if the object is <code>null</code>
219 */
220 public static void notNull(Object object) {
221 if (object == null) {
222 throw new IllegalArgumentException("The validated object is null");
223 }
224 }
225
226 // notEmpty array
227 //---------------------------------------------------------------------------------
228
229 /**
230 * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
231 * if the argument array is empty (<code>null</code> or no elements).</p>
232 *
233 * <pre>
234 * Validate.notEmpty(myArray, "The array must not be empty");
235 * </pre>
236 *
237 * @param array the array to check is not empty
238 * @param message the exception message you would like to see if the array is empty
239 * @throws IllegalArgumentException if the array is empty
240 */
241 public static void notEmpty(Object[] array, String message) {
242 if (array == null || array.length == 0) {
243 throw new IllegalArgumentException(message);
244 }
245 }
246
247 /**
248 * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
249 * if the argument array is empty (<code>null</code> or no elements).</p>
250 *
251 * <pre>
252 * Validate.notEmpty(myArray);
253 * </pre>
254 *
255 * <p>The message in the exception is 'The validated array is empty'.
256 *
257 * @param array the array to check is not empty
258 * @throws IllegalArgumentException if the array is empty
259 */
260 public static void notEmpty(Object[] array) {
261 if (array == null || array.length == 0) {
262 throw new IllegalArgumentException("The validated array is empty");
263 }
264 }
265
266 // notEmpty collection
267 //---------------------------------------------------------------------------------
268
269 /**
270 * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
271 * if the argument Collection is empty (<code>null</code> or no elements).</p>
272 *
273 * <pre>
274 * Validate.notEmpty(myCollection, "The collection must not be empty");
275 * </pre>
276 *
277 * @param collection the collection to check is not empty
278 * @param message the exception message you would like to see if the collection is empty
279 * @throws IllegalArgumentException if the collection is empty
280 */
281 public static void notEmpty(Collection collection, String message) {
282 if (collection == null || collection.size() == 0) {
283 throw new IllegalArgumentException(message);
284 }
285 }
286
287 /**
288 * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
289 * if the argument Collection is empty (<code>null</code> or no elements).</p>
290 *
291 * <pre>
292 * Validate.notEmpty(myCollection);
293 * </pre>
294 *
295 * <p>The message in the exception is 'The validated collection is empty'.</p>
296 *
297 * @param collection the collection to check is not empty
298 * @throws IllegalArgumentException if the collection is empty
299 */
300 public static void notEmpty(Collection collection) {
301 if (collection == null || collection.size() == 0) {
302 throw new IllegalArgumentException("The validated collection is empty");
303 }
304 }
305
306 // notEmpty map
307 //---------------------------------------------------------------------------------
308
309 /**
310 * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
311 * if the argument Map is empty (<code>null</code> or no elements).</p>
312 *
313 * <pre>
314 * Validate.notEmpty(myMap, "The map must not be empty");
315 * </pre>
316 *
317 * @param map the map to check is not empty
318 * @param message the exception message you would like to see if the map is empty
319 * @throws IllegalArgumentException if the map is empty
320 */
321 public static void notEmpty(Map map, String message) {
322 if (map == null || map.size() == 0) {
323 throw new IllegalArgumentException(message);
324 }
325 }
326
327 /**
328 * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
329 * if the argument Map is empty (<code>null</code> or no elements).</p>
330 *
331 * <pre>
332 * Validate.notEmpty(myMap);
333 * </pre>
334 *
335 * <p>The message in the exception is 'The validated map is empty'.</p>
336 *
337 * @param map the map to check is not empty
338 * @throws IllegalArgumentException if the map is empty
339 */
340 public static void notEmpty(Map map) {
341 if (map == null || map.size() == 0) {
342 throw new IllegalArgumentException("The validated map is empty");
343 }
344 }
345
346 // notEmpty string
347 //---------------------------------------------------------------------------------
348
349 /**
350 * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
351 * if the argument String is empty (<code>null</code> or zero length).</p>
352 *
353 * <pre>
354 * Validate.notEmpty(myString, "The string must not be empty");
355 * </pre>
356 *
357 * @param string the string to check is not empty
358 * @param message the exception message you would like to see if the string is empty
359 * @throws IllegalArgumentException if the string is empty
360 */
361 public static void notEmpty(String string, String message) {
362 if (string == null || string.length() == 0) {
363 throw new IllegalArgumentException(message);
364 }
365 }
366
367 /**
368 * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
369 * if the argument String is empty (<code>null</code> or zero length).</p>
370 *
371 * <pre>
372 * Validate.notEmpty(myString);
373 * </pre>
374 *
375 * <p>The message in the exception is 'The validated string is empty'.</p>
376 *
377 * @param string the string to check is not empty
378 * @throws IllegalArgumentException if the string is empty
379 */
380 public static void notEmpty(String string) {
381 if (string == null || string.length() == 0) {
382 throw new IllegalArgumentException("The validated string is empty");
383 }
384 }
385
386 // notNullElements array
387 //---------------------------------------------------------------------------------
388
389 /**
390 * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
391 * if the argument array has <code>null</code> elements or is
392 * <code>null</code>.</p>
393 *
394 * <pre>
395 * Validate.noNullElements(myArray, "The array must not contain null elements");
396 * </pre>
397 *
398 * <p>If the array is null then the message in the exception is 'The validated object is null'.</p>
399 *
400 * @param array the array to check
401 * @param message the exception message if the array has
402 * <code>null</code> elements
403 * @throws IllegalArgumentException if the array has <code>null</code>
404 * elements or is <code>null</code>
405 */
406 public static void noNullElements(Object[] array, String message) {
407 Validate.notNull(array);
408 for (int i = 0; i < array.length; i++) {
409 if (array[i] == null) {
410 throw new IllegalArgumentException(message);
411 }
412 }
413 }
414
415 /**
416 * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
417 * if the argument array has <code>null</code> elements or is
418 * <code>null</code>.</p>
419 *
420 * <pre>
421 * Validate.noNullElements(myArray);
422 * </pre>
423 *
424 * <p>If the array has a null element the message in the exception is
425 * 'The validated array contains null element at index: '.</p>
426 *
427 * <p>If the array is null then the message in the exception is 'The validated object is null'.</p>
428 *
429 * @param array the array to check
430 * @throws IllegalArgumentException if the array has <code>null</code>
431 * elements or is <code>null</code>
432 */
433 public static void noNullElements(Object[] array) {
434 Validate.notNull(array);
435 for (int i = 0; i < array.length; i++) {
436 if (array[i] == null) {
437 throw new IllegalArgumentException("The validated array contains null element at index: " + i);
438 }
439 }
440 }
441
442 // notNullElements collection
443 //---------------------------------------------------------------------------------
444
445 /**
446 * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
447 * if the argument Collection has <code>null</code> elements or is
448 * <code>null</code>.</p>
449 *
450 * <pre>
451 * Validate.noNullElements(myCollection, "The collection must not contain null elements");
452 * </pre>
453 *
454 * <p>If the collection is null then the message in the exception is 'The validated object is null'.</p>
455 *
456 * @param collection the collection to check
457 * @param message the exception message if the collection has
458 * <code>null</code> elements
459 * @throws IllegalArgumentException if the collection has
460 * <code>null</code> elements or is <code>null</code>
461 */
462 public static void noNullElements(Collection collection, String message) {
463 Validate.notNull(collection);
464 for (Iterator it = collection.iterator(); it.hasNext();) {
465 if (it.next() == null) {
466 throw new IllegalArgumentException(message);
467 }
468 }
469 }
470
471 /**
472 * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
473 * if the argument Collection has <code>null</code> elements or is
474 * <code>null</code>.</p>
475 *
476 * <pre>
477 * Validate.noNullElements(myCollection);
478 * </pre>
479 *
480 * <p>The message in the exception is 'The validated collection contains null element at index: '.</p>
481 *
482 * <p>If the collection is null then the message in the exception is 'The validated object is null'.</p>
483 *
484 * @param collection the collection to check
485 * @throws IllegalArgumentException if the collection has
486 * <code>null</code> elements or is <code>null</code>
487 */
488 public static void noNullElements(Collection collection) {
489 Validate.notNull(collection);
490 int i = 0;
491 for (Iterator it = collection.iterator(); it.hasNext(); i++) {
492 if (it.next() == null) {
493 throw new IllegalArgumentException("The validated collection contains null element at index: " + i);
494 }
495 }
496 }
497
498 /**
499 * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
500 * if the argument collection is <code>null</code> or has elements that
501 * are not of type <code>clazz</code> or a subclass.</p>
502 *
503 * <pre>
504 * Validate.allElementsOfType(collection, String.class, "Collection has invalid elements");
505 * </pre>
506 *
507 * @param collection the collection to check, not null
508 * @param clazz the <code>Class</code> which the collection's elements are expected to be, not null
509 * @param message the exception message if the <code>Collection</code> has elements not of type <code>clazz</code>
510 * @since 2.1
511 */
512 public static void allElementsOfType(Collection collection, Class clazz, String message) {
513 Validate.notNull(collection);
514 Validate.notNull(clazz);
515 for (Iterator it = collection.iterator(); it.hasNext(); ) {
516 if (clazz.isInstance(it.next()) == false) {
517 throw new IllegalArgumentException(message);
518 }
519 }
520 }
521
522 /**
523 * <p>
524 * Validate an argument, throwing <code>IllegalArgumentException</code> if the argument collection is
525 * <code>null</code> or has elements that are not of type <code>clazz</code> or a subclass.
526 * </p>
527 *
528 * <pre>
529 * Validate.allElementsOfType(collection, String.class);
530 * </pre>
531 *
532 * <p>
533 * The message in the exception is 'The validated collection contains an element not of type clazz at index: '.
534 * </p>
535 *
536 * @param collection
537 * the collection to check, not null
538 * @param clazz
539 * the <code>Class</code> which the collection's elements are expected to be, not null
540 * @since 2.1
541 */
542 public static void allElementsOfType(Collection collection, Class clazz) {
543 Validate.notNull(collection);
544 Validate.notNull(clazz);
545 int i = 0;
546 for (Iterator it = collection.iterator(); it.hasNext(); i++) {
547 if (clazz.isInstance(it.next()) == false) {
548 throw new IllegalArgumentException("The validated collection contains an element not of type "
549 + clazz.getName() + " at index: " + i);
550 }
551 }
552 }
553
554 }