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