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