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