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 }