1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one 3 * or more contributor license agreements. See the NOTICE file 4 * distributed with this work for additional information 5 * regarding copyright ownership. The ASF licenses this file 6 * to you under the Apache License, Version 2.0 (the 7 * "License"); you may not use this file except in compliance 8 * with the License. You may obtain a copy of the License at 9 * 10 * http://www.apache.org/licenses/LICENSE-2.0 11 * 12 * Unless required by applicable law or agreed to in writing, 13 * software distributed under the License is distributed on an 14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 15 * KIND, either express or implied. See the License for the 16 * specific language governing permissions and limitations 17 * under the License. 18 */ 19 package org.apache.fulcrum.yaafi.framework.util; 20 21 import java.util.Collection; 22 import java.util.Iterator; 23 import java.util.Map; 24 25 import org.apache.commons.lang3.StringUtils; 26 27 /** 28 * <p>Assists in validating arguments.</p> 29 * 30 * <p>The class is based along the lines of JUnit. If an argument value is 31 * deemed invalid, an IllegalArgumentException is thrown. For example:</p> 32 * 33 * <pre> 34 * Validate.isTrue( i > 0, "The value must be greater than zero: ", i); 35 * Validate.notNull( surname, "The surname must not be null"); 36 * </pre> 37 * 38 * @author <a href="mailto:ola.berg@arkitema.se">Ola Berg</a> 39 * @author Stephen Colebourne 40 * @author Gary Gregory 41 * @author Norm Deane 42 * @since 2.0 43 * @version $Id$ 44 */ 45 public class Validate 46 { 47 /** 48 * Constructor. This class should not normally be instantiated. 49 */ 50 public Validate() 51 { 52 } 53 54 // isTrue 55 //--------------------------------------------------------------------------------- 56 57 /** 58 * <p>Validate an argument, throwing <code>IllegalArgumentException</code> 59 * if the test result is <code>false</code>.</p> 60 * 61 * <p>This is used when validating according to an arbitrary boolean expression, 62 * such as validating a primitive number or using your own custom validation 63 * expression.</p> 64 * 65 * <pre> 66 * Validate.isTrue( myObject.isOk(), "The object is not OK: ", myObject); 67 * </pre> 68 * 69 * <p>For performance reasons, the object is passed as a separate parameter and 70 * appended to the message string only in the case of an error.</p> 71 * 72 * @param expression a boolean expression 73 * @param message the exception message you would like to see if the 74 * expression is <code>false</code> 75 * @param value the value to append to the message in case of error 76 * @throws IllegalArgumentException if expression is <code>false</code> 77 */ 78 public static void isTrue(boolean expression, String message, Object value) 79 { 80 if (expression == false) 81 { 82 throw new IllegalArgumentException( message + value ); 83 } 84 } 85 86 /** 87 * <p>Validate an argument, throwing <code>IllegalArgumentException</code> 88 * if the test result is <code>false</code>.</p> 89 * 90 * <p>This is used when validating according to an arbitrary boolean expression, 91 * such as validating a primitive number or using your own custom validation 92 * expression.</p> 93 * 94 * <pre> 95 * Validate.isTrue( i > 0, "The value must be greater than zero: ", i); 96 * </pre> 97 * 98 * <p>For performance reasons, the long value is passed as a separate parameter and 99 * appended to the message string only in the case of an error.</p> 100 * 101 * @param expression a boolean expression 102 * @param message the exception message you would like to see if the expression is <code>false</code> 103 * @param value the value to append to the message in case of error 104 * @throws IllegalArgumentException if expression is <code>false</code> 105 */ 106 public static void isTrue(boolean expression, String message, long value) 107 { 108 if (expression == false) 109 { 110 throw new IllegalArgumentException( message + value ); 111 } 112 } 113 114 /** 115 * <p>Validate an argument, throwing <code>IllegalArgumentException</code> 116 * if the test result is <code>false</code>.</p> 117 * 118 * <p>This is used when validating according to an arbitrary boolean expression, 119 * such as validating a primitive number or using your own custom validation 120 * expression.</p> 121 * 122 * <pre> 123 * Validate.isTrue( d > 0.0, "The value must be greater than zero: ", d); 124 * </pre> 125 * 126 * <p>For performance reasons, the double value is passed as a separate parameter and 127 * appended to the message string only in the case of an error.</p> 128 * 129 * @param expression a boolean expression 130 * @param message the exception message you would like to see if the expression 131 * is <code>false</code> 132 * @param value the value to append to the message in case of error 133 * @throws IllegalArgumentException if expression is <code>false</code> 134 */ 135 public static void isTrue(boolean expression, String message, double value) 136 { 137 if (expression == false) 138 { 139 throw new IllegalArgumentException( message + value ); 140 } 141 } 142 143 /** 144 * <p>Validate an argument, throwing <code>IllegalArgumentException</code> 145 * if the test result is <code>false</code>.</p> 146 * 147 * <p>This is used when validating according to an arbitrary boolean expression, 148 * such as validating a primitive number or using your own custom validation 149 * expression.</p> 150 * 151 * <pre> 152 * Validate.isTrue( (i > 0), "The value must be greater than zero"); 153 * Validate.isTrue( myObject.isOk(), "The object is not OK"); 154 * </pre> 155 * 156 * <p>For performance reasons, the message string should not involve a string append, 157 * instead use the {@link #isTrue(boolean, String, Object)} method.</p> 158 * 159 * @param expression a boolean expression 160 * @param message the exception message you would like to see if the expression 161 * is <code>false</code> 162 * @throws IllegalArgumentException if expression is <code>false</code> 163 */ 164 public static void isTrue(boolean expression, String message) 165 { 166 if (expression == false) 167 { 168 throw new IllegalArgumentException( message ); 169 } 170 } 171 172 /** 173 * <p>Validate an argument, throwing <code>IllegalArgumentException</code> 174 * if the test result is <code>false</code>.</p> 175 * 176 * <p>This is used when validating according to an arbitrary boolean expression, 177 * such as validating a primitive number or using your own custom validation 178 * expression.</p> 179 * 180 * <pre> 181 * Validate.isTrue( i > 0 ); 182 * Validate.isTrue( myObject.isOk() ); 183 * </pre> 184 * 185 * <p>The message in the exception is 'The validated expression is false'.</p> 186 * 187 * @param expression a boolean expression 188 * @throws IllegalArgumentException if expression is <code>false</code> 189 */ 190 public static void isTrue(boolean expression) 191 { 192 if (expression == false) 193 { 194 throw new IllegalArgumentException( 195 "The validated expression is false" ); 196 } 197 } 198 199 // notNull 200 //--------------------------------------------------------------------------------- 201 202 /** 203 * <p>Validate an argument, throwing <code>IllegalArgumentException</code> 204 * if the argument is <code>null</code>.</p> 205 * 206 * <pre> 207 * Validate.notNull(myObject, "The object must not be null"); 208 * </pre> 209 * 210 * @param object the object to check is not <code>null</code> 211 * @param message the exception message you would like to see 212 * if the object is <code>null</code> 213 * @throws IllegalArgumentException if the object is <code>null</code> 214 */ 215 public static void notNull(Object object, String message) 216 { 217 if (object == null) 218 { 219 throw new IllegalArgumentException( message ); 220 } 221 } 222 223 /** 224 * <p>Validate an argument, throwing <code>IllegalArgumentException</code> 225 * if the argument is <code>null</code>.</p> 226 * 227 * <pre> 228 * Validate.notNull(myObject); 229 * </pre> 230 * 231 * <p>The message in the exception is 'The validated object is null'.</p> 232 * 233 * @param object the object to check is not <code>null</code> 234 * @throws IllegalArgumentException if the object is <code>null</code> 235 */ 236 public static void notNull(Object object) 237 { 238 if (object == null) 239 { 240 throw new IllegalArgumentException( "The validated object is null" ); 241 } 242 } 243 244 // notEmpty array 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, "The array must not be empty"); 253 * </pre> 254 * 255 * @param array the array to check is not empty 256 * @param message the exception message you would like to see if the array is empty 257 * @throws IllegalArgumentException if the array is empty 258 */ 259 public static void notEmpty(Object [] array, String message) 260 { 261 if (array == null || array.length == 0) 262 { 263 throw new IllegalArgumentException( message ); 264 } 265 } 266 267 /** 268 * <p>Validate an argument, throwing <code>IllegalArgumentException</code> 269 * if the argument array is empty (<code>null</code> or no elements).</p> 270 * 271 * <pre> 272 * Validate.notEmpty(myArray); 273 * </pre> 274 * 275 * <p>The message in the exception is 'The validated array is empty'. 276 * 277 * @param array the array to check is not empty 278 * @throws IllegalArgumentException if the array is empty 279 */ 280 public static void notEmpty(Object [] array) 281 { 282 if (array == null || array.length == 0) 283 { 284 throw new IllegalArgumentException( "The validated array is empty" ); 285 } 286 } 287 288 // notEmpty collection 289 //--------------------------------------------------------------------------------- 290 291 /** 292 * <p>Validate an argument, throwing <code>IllegalArgumentException</code> 293 * if the argument Collection is empty (<code>null</code> or no elements).</p> 294 * 295 * <pre> 296 * Validate.notEmpty(myCollection, "The collection must not be empty"); 297 * </pre> 298 * 299 * @param collection the collection to check is not empty 300 * @param message the exception message you would like to see if the collection is empty 301 * @throws IllegalArgumentException if the collection is empty 302 */ 303 public static void notEmpty(Collection<?> collection, String message) 304 { 305 if (collection == null || collection.size() == 0) 306 { 307 throw new IllegalArgumentException( message ); 308 } 309 } 310 311 /** 312 * <p>Validate an argument, throwing <code>IllegalArgumentException</code> 313 * if the argument Collection is empty (<code>null</code> or no elements).</p> 314 * 315 * <pre> 316 * Validate.notEmpty(myCollection); 317 * </pre> 318 * 319 * <p>The message in the exception is 'The validated collection is empty'.</p> 320 * 321 * @param collection the collection to check is not empty 322 * @throws IllegalArgumentException if the collection is empty 323 */ 324 public static void notEmpty(Collection<?> collection) 325 { 326 if (collection == null || collection.size() == 0) 327 { 328 throw new IllegalArgumentException( 329 "The validated collection is empty" ); 330 } 331 } 332 333 // notEmpty map 334 //--------------------------------------------------------------------------------- 335 336 /** 337 * <p>Validate an argument, throwing <code>IllegalArgumentException</code> 338 * if the argument Map is empty (<code>null</code> or no elements).</p> 339 * 340 * <pre> 341 * Validate.notEmpty(myMap, "The map must not be empty"); 342 * </pre> 343 * 344 * @param map the map to check is not empty 345 * @param message the exception message you would like to see if the map is empty 346 * @throws IllegalArgumentException if the map is empty 347 */ 348 public static void notEmpty(Map<?, ?> map, String message) 349 { 350 if (map == null || map.size() == 0) 351 { 352 throw new IllegalArgumentException( message ); 353 } 354 } 355 356 /** 357 * <p>Validate an argument, throwing <code>IllegalArgumentException</code> 358 * if the argument Map is empty (<code>null</code> or no elements).</p> 359 * 360 * <pre> 361 * Validate.notEmpty(myMap); 362 * </pre> 363 * 364 * <p>The message in the exception is 'The validated map is empty'.</p> 365 * 366 * @param map the map to check is not empty 367 * @throws IllegalArgumentException if the map is empty 368 */ 369 public static void notEmpty(Map<?, ?> map) 370 { 371 if (map == null || map.size() == 0) 372 { 373 throw new IllegalArgumentException( "The validated map is empty" ); 374 } 375 } 376 377 // notEmpty string 378 //--------------------------------------------------------------------------------- 379 380 /** 381 * <p>Validate an argument, throwing <code>IllegalArgumentException</code> 382 * if the argument String is empty (<code>null</code> or zero length).</p> 383 * 384 * <pre> 385 * Validate.notEmpty(myString, "The string must not be empty"); 386 * </pre> 387 * 388 * @param string the string to check is not empty 389 * @param message the exception message you would like to see if the string is empty 390 * @throws IllegalArgumentException if the string is empty 391 */ 392 public static void notEmpty(String string, String message) 393 { 394 if ( StringUtils.isEmpty(string) ) 395 throw new IllegalArgumentException( message ); 396 } 397 398 /** 399 * <p>Validate an argument, throwing <code>IllegalArgumentException</code> 400 * if the argument String is empty (<code>null</code> or zero length).</p> 401 * 402 * <pre> 403 * Validate.notEmpty(myString); 404 * </pre> 405 * 406 * <p>The message in the exception is 'The validated string is empty'.</p> 407 * 408 * @param string the string to check is not empty 409 * @throws IllegalArgumentException if the string is empty 410 */ 411 public static void notEmpty(String string) 412 { 413 if ( StringUtils.isEmpty(string) ) 414 throw new IllegalArgumentException( "The validated string is empty" ); 415 } 416 417 // notNullElements array 418 //--------------------------------------------------------------------------------- 419 420 /** 421 * <p>Validate an argument, throwing <code>IllegalArgumentException</code> 422 * if the argument array has <code>null</code> elements or is 423 * <code>null</code>.</p> 424 * 425 * <pre> 426 * Validate.noNullElements(myArray, "The array must not contain null elements"); 427 * </pre> 428 * 429 * <p>If the array is null then the message in the exception is 'The validated object is null'.</p> 430 * 431 * @param array the array to check 432 * @param message the exception message if the array has 433 * <code>null</code> elements 434 * @throws IllegalArgumentException if the array has <code>null</code> 435 * elements or is <code>null</code> 436 */ 437 public static void noNullElements(Object [] array, String message) 438 { 439 Validate.notNull( array ); 440 for (int i = 0; i < array.length; i++) 441 { 442 if (array[i] == null) 443 { 444 throw new IllegalArgumentException( message ); 445 } 446 } 447 } 448 449 /** 450 * <p>Validate an argument, throwing <code>IllegalArgumentException</code> 451 * if the argument array has <code>null</code> elements or is 452 * <code>null</code>.</p> 453 * 454 * <pre> 455 * Validate.noNullElements(myArray); 456 * </pre> 457 * 458 * <p>If the array has a null element the message in the exception is 459 * 'The validated array contains null element at index: '.</p> 460 * 461 * <p>If the array is null then the message in the exception is 'The validated object is null'.</p> 462 * 463 * @param array the array to check 464 * @throws IllegalArgumentException if the array has <code>null</code> 465 * elements or is <code>null</code> 466 */ 467 public static void noNullElements(Object [] array) 468 { 469 Validate.notNull( array ); 470 for (int i = 0; i < array.length; i++) 471 { 472 if (array[i] == null) 473 { 474 throw new IllegalArgumentException( 475 "The validated array contains null element at index: " 476 + i ); 477 } 478 } 479 } 480 481 // notNullElements collection 482 //--------------------------------------------------------------------------------- 483 484 /** 485 * <p>Validate an argument, throwing <code>IllegalArgumentException</code> 486 * if the argument Collection has <code>null</code> elements or is 487 * <code>null</code>.</p> 488 * 489 * <pre> 490 * Validate.noNullElements(myCollection, "The collection must not contain null elements"); 491 * </pre> 492 * 493 * <p>If the collection is null then the message in the exception is 'The validated object is null'.</p> 494 * 495 * @param collection the collection to check 496 * @param message the exception message if the collection has 497 * <code>null</code> elements 498 * @throws IllegalArgumentException if the collection has 499 * <code>null</code> elements or is <code>null</code> 500 */ 501 public static void noNullElements(Collection<?> collection, String message) 502 { 503 Validate.notNull( collection ); 504 for (Iterator<?> it = collection.iterator(); it.hasNext();) 505 { 506 if (it.next() == null) 507 { 508 throw new IllegalArgumentException( message ); 509 } 510 } 511 } 512 513 /** 514 * <p>Validate an argument, throwing <code>IllegalArgumentException</code> 515 * if the argument Collection has <code>null</code> elements or is 516 * <code>null</code>.</p> 517 * 518 * <pre> 519 * Validate.noNullElements(myCollection); 520 * </pre> 521 * 522 * <p>The message in the exception is 'The validated collection contains null element at index: '.</p> 523 * 524 * <p>If the collection is null then the message in the exception is 'The validated object is null'.</p> 525 * 526 * @param collection the collection to check 527 * @throws IllegalArgumentException if the collection has 528 * <code>null</code> elements or is <code>null</code> 529 */ 530 public static void noNullElements(Collection<?> collection) 531 { 532 Validate.notNull( collection ); 533 int i = 0; 534 for (Iterator<?> it = collection.iterator(); it.hasNext(); i++) 535 { 536 if (it.next() == null) 537 { 538 throw new IllegalArgumentException( 539 "The validated collection contains null element at index: " 540 + i ); 541 } 542 } 543 } 544 545 /** 546 * <p>Validate an argument, throwing <code>IllegalArgumentException</code> 547 * if the argument collection is <code>null</code> or has elements that 548 * are not of type <code>clazz</code> or a subclass.</p> 549 * 550 * <pre> 551 * Validate.allElementsOfType(collection, String.class, "Collection has invalid elements"); 552 * </pre> 553 * 554 * @param collection the collection to check, not null 555 * @param clazz the <code>Class</code> which the collection's elements are expected to be, not null 556 * @param message the exception message if the <code>Collection</code> has elements not of type <code>clazz</code> 557 * @since 2.1 558 */ 559 public static void allElementsOfType(Collection<?> collection, Class<?> clazz, 560 String message) 561 { 562 Validate.notNull( collection ); 563 Validate.notNull( clazz ); 564 for (Iterator<?> it = collection.iterator(); it.hasNext();) 565 { 566 if (clazz.isInstance( it.next() ) == false) 567 { 568 throw new IllegalArgumentException( message ); 569 } 570 } 571 } 572 573 /** 574 * <p> 575 * Validate an argument, throwing <code>IllegalArgumentException</code> if the argument collection is 576 * <code>null</code> or has elements that are not of type <code>clazz</code> or a subclass. 577 * </p> 578 * 579 * <pre> 580 * Validate.allElementsOfType(collection, String.class); 581 * </pre> 582 * 583 * <p> 584 * The message in the exception is 'The validated collection contains an element not of type clazz at index: '. 585 * </p> 586 * 587 * @param collection 588 * the collection to check, not null 589 * @param clazz 590 * the <code>Class</code> which the collection's elements are expected to be, not null 591 * @since 2.1 592 */ 593 public static void allElementsOfType(Collection<?> collection, Class<?> clazz) 594 { 595 Validate.notNull( collection ); 596 Validate.notNull( clazz ); 597 int i = 0; 598 for (Iterator<?> it = collection.iterator(); it.hasNext(); i++) 599 { 600 if (clazz.isInstance( it.next() ) == false) 601 { 602 throw new IllegalArgumentException( 603 "The validated collection contains an element not of type " 604 + clazz.getName() 605 + " at index: " + i ); 606 } 607 } 608 } 609 }