commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From nia...@apache.org
Subject svn commit: r905325 - /commons/proper/lang/branches/LANG_2_X/src/main/java/org/apache/commons/lang/Validate.java
Date Mon, 01 Feb 2010 16:26:08 GMT
Author: niallp
Date: Mon Feb  1 16:26:08 2010
New Revision: 905325

URL: http://svn.apache.org/viewvc?rev=905325&view=rev
Log:
Javadoc updates

Modified:
    commons/proper/lang/branches/LANG_2_X/src/main/java/org/apache/commons/lang/Validate.java

Modified: commons/proper/lang/branches/LANG_2_X/src/main/java/org/apache/commons/lang/Validate.java
URL: http://svn.apache.org/viewvc/commons/proper/lang/branches/LANG_2_X/src/main/java/org/apache/commons/lang/Validate.java?rev=905325&r1=905324&r2=905325&view=diff
==============================================================================
--- commons/proper/lang/branches/LANG_2_X/src/main/java/org/apache/commons/lang/Validate.java
(original)
+++ commons/proper/lang/branches/LANG_2_X/src/main/java/org/apache/commons/lang/Validate.java
Mon Feb  1 16:26:08 2010
@@ -21,7 +21,7 @@
 import java.util.Map;
 
 /**
- * <p>Assists in validating arguments.</p>
+ * <p>This class assists in validating arguments.</p>
  * 
  * <p>The class is based along the lines of JUnit. If an argument value is 
  * deemed invalid, an IllegalArgumentException is thrown. For example:</p>
@@ -47,29 +47,23 @@
     public Validate() {
       super();
     }
-    
+
     // isTrue
     //---------------------------------------------------------------------------------
-
     /**
-     * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
-     * if the test result is <code>false</code>.</p>
-     * 
-     * <p>This is used when validating according to an arbitrary boolean expression,
-     * such as validating a primitive number or using your own custom validation 
-     * expression.</p>
-     *
-     * <pre>
-     * Validate.isTrue( myObject.isOk(), "The object is not OK: ", myObject);
-     * </pre>
-     *
-     * <p>For performance reasons, the object is passed as a separate parameter and
-     * appended to the message string only in the case of an error.</p>
-     * 
-     * @param expression  a boolean expression
-     * @param message  the exception message you would like to see if the
-     *  expression is <code>false</code>
-     * @param value  the value to append to the message in case of error
+     * <p>Validate that the argument condition is <code>true</code>; otherwise

+     * throwing an exception with the specified message. This method is useful when
+     * validating according to an arbitrary boolean expression, such as validating an 
+     * object or using your own custom validation expression.</p>
+     *
+     * <pre>Validate.isTrue( myObject.isOk(), "The object is not OK: ", myObject);</pre>
+     *
+     * <p>For performance reasons, the object value is passed as a separate parameter
and
+     * appended to the exception message only in the case of an error.</p>
+     * 
+     * @param expression the boolean expression to check 
+     * @param message the exception message if invalid
+     * @param value the value to append to the message when invalid
      * @throws IllegalArgumentException if expression is <code>false</code>
      */
     public static void isTrue(boolean expression, String message, Object value) {
@@ -79,23 +73,19 @@
     }
 
     /**
-     * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
-     * if the test result is <code>false</code>.</p>
-     * 
-     * <p>This is used when validating according to an arbitrary boolean expression,
-     * such as validating a primitive number or using your own custom validation 
-     * expression.</p>
+     * <p>Validate that the argument condition is <code>true</code>; otherwise

+     * throwing an exception with the specified message. This method is useful when
+     * validating according to an arbitrary boolean expression, such as validating a 
+     * primitive number or using your own custom validation expression.</p>
      *
-     * <pre>
-     * Validate.isTrue( i > 0, "The value must be greater than zero: ", i);
-     * </pre>
+     * <pre>Validate.isTrue(i > 0.0, "The value must be greater than zero: ", i);</pre>
      *
      * <p>For performance reasons, the long value is passed as a separate parameter
and
-     * appended to the message string only in the case of an error.</p>
+     * appended to the exception message only in the case of an error.</p>
      * 
-     * @param expression  a boolean expression
-     * @param message  the exception message you would like to see if the expression is <code>false</code>
-     * @param value  the value to append to the message in case of error
+     * @param expression the boolean expression to check 
+     * @param message the exception message if invalid
+     * @param value the value to append to the message when invalid
      * @throws IllegalArgumentException if expression is <code>false</code>
      */
     public static void isTrue(boolean expression, String message, long value) {
@@ -105,24 +95,19 @@
     }
 
     /**
-     * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
-     * if the test result is <code>false</code>.</p>
-     * 
-     * <p>This is used when validating according to an arbitrary boolean expression,
-     * such as validating a primitive number or using your own custom validation 
-     * expression.</p>
+     * <p>Validate that the argument condition is <code>true</code>; otherwise

+     * throwing an exception with the specified message. This method is useful when
+     * validating according to an arbitrary boolean expression, such as validating a 
+     * primitive number or using your own custom validation expression.</p>
      *
-     * <pre>
-     * Validate.isTrue( d > 0.0, "The value must be greater than zero: ", d);
-     * </pre>
+     * <pre>Validate.isTrue(d > 0.0, "The value must be greater than zero: ", d);</pre>
      *
      * <p>For performance reasons, the double value is passed as a separate parameter
and
-     * appended to the message string only in the case of an error.</p>
+     * appended to the exception message only in the case of an error.</p>
      * 
-     * @param expression  a boolean expression
-     * @param message  the exception message you would like to see if the expression
-     *  is <code>false</code>
-     * @param value  the value to append to the message in case of error
+     * @param expression the boolean expression to check 
+     * @param message the exception message if invalid
+     * @param value the value to append to the message when invalid
      * @throws IllegalArgumentException if expression is <code>false</code>
      */
     public static void isTrue(boolean expression, String message, double value) {
@@ -132,24 +117,18 @@
     }
 
     /**
-     * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
-     * if the test result is <code>false</code>.</p>
-     * 
-     * <p>This is used when validating according to an arbitrary boolean expression,
-     * such as validating a primitive number or using your own custom validation 
-     * expression.</p>
+     * <p>Validate that the argument condition is <code>true</code>; otherwise

+     * throwing an exception with the specified message. This method is useful when
+     * validating according to an arbitrary boolean expression, such as validating a 
+     * primitive number or using your own custom validation expression.</p>
      *
      * <pre>
      * Validate.isTrue( (i > 0), "The value must be greater than zero");
      * Validate.isTrue( myObject.isOk(), "The object is not OK");
      * </pre>
      *
-     * <p>For performance reasons, the message string should not involve a string append,
-     * instead use the {@link #isTrue(boolean, String, Object)} method.</p>
-     * 
-     * @param expression  a boolean expression
-     * @param message  the exception message you would like to see if the expression
-     *  is <code>false</code>
+     * @param expression the boolean expression to check 
+     * @param message the exception message if invalid
      * @throws IllegalArgumentException if expression is <code>false</code>
      */
     public static void isTrue(boolean expression, String message) {
@@ -159,21 +138,19 @@
     }
 
     /**
-     * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
-     * if the test result is <code>false</code>.</p>
-     * 
-     * <p>This is used when validating according to an arbitrary boolean expression,
-     * such as validating a primitive number or using your own custom validation 
-     * expression.</p>
+     * <p>Validate that the argument condition is <code>true</code>; otherwise

+     * throwing an exception. This method is useful when validating according 
+     * to an arbitrary boolean expression, such as validating a 
+     * primitive number or using your own custom validation expression.</p>
      *
      * <pre>
-     * Validate.isTrue( i > 0 );
-     * Validate.isTrue( myObject.isOk() );
-     * </pre>
+     * Validate.isTrue(i > 0);
+     * Validate.isTrue(myObject.isOk());</pre>
      *
-     * <p>The message in the exception is 'The validated expression is false'.</p>
+     * <p>The message of the exception is &quot;The validated expression is 
+     * false&quot;.</p>
      * 
-     * @param expression  a boolean expression
+     * @param expression the boolean expression to check 
      * @throws IllegalArgumentException if expression is <code>false</code>
      */
     public static void isTrue(boolean expression) {
@@ -186,17 +163,13 @@
     //---------------------------------------------------------------------------------
 
     /**
-     * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
-     * if the argument is <code>null</code>.</p>
+     * <p>Validate that the specified argument is not <code>null</code>;

+     * otherwise throwing an exception with the specified message.
      *
-     * <pre>
-     * Validate.notNull(myObject, "The object must not be null");
-     * </pre>
+     * <pre>Validate.notNull(myObject, "The object must not be null");</pre>
      * 
-     * @param object  the object to check is not <code>null</code>
-     * @param message  the exception message you would like to see
-     *  if the object is <code>null</code>
-     * @throws IllegalArgumentException if the object is <code>null</code>
+     * @param object the object to check
+     * @param message the exception message if invalid
      */
     public static void notNull(Object object, String message) {
         if (object == null) {
@@ -205,16 +178,15 @@
     }
 
     /**
-     * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
-     * if the argument is <code>null</code>.</p>
+     * <p>Validate that the specified argument is not <code>null</code>;

+     * otherwise throwing an exception.
      *
-     * <pre>
-     * Validate.notNull(myObject);
-     * </pre>
+     * <pre>Validate.notNull(myObject);</pre>
      *
-     * <p>The message in the exception is 'The validated object is null'.</p>
+     * <p>The message of the exception is &quot;The validated object is 
+     * null&quot;.</p>
      * 
-     * @param object  the object to check is not <code>null</code>
+     * @param object the object to check
      * @throws IllegalArgumentException if the object is <code>null</code>
      */
     public static void notNull(Object object) {
@@ -227,15 +199,14 @@
     //---------------------------------------------------------------------------------
 
     /**
-     * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
-     * if the argument array is empty (<code>null</code> or no elements).</p>
+     * <p>Validate that the specified argument array is neither <code>null</code>

+     * nor a length of zero (no elements); otherwise throwing an exception 
+     * with the specified message.
      *
-     * <pre>
-     * Validate.notEmpty(myArray, "The array must not be empty");
-     * </pre>
+     * <pre>Validate.notEmpty(myArray, "The array must not be empty");</pre>
      * 
-     * @param array  the array to check is not empty
-     * @param message  the exception message you would like to see if the array is empty
+     * @param array the array to check
+     * @param message the exception message if invalid
      * @throws IllegalArgumentException if the array is empty
      */
     public static void notEmpty(Object[] array, String message) {
@@ -245,16 +216,15 @@
     }
 
     /**
-     * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
-     * if the argument array is empty (<code>null</code> or no elements).</p>
-     *
-     * <pre>
-     * Validate.notEmpty(myArray);
-     * </pre>
+     * <p>Validate that the specified argument array is neither <code>null</code>

+     * nor a length of zero (no elements); otherwise throwing an exception. 
      *
-     * <p>The message in the exception is 'The validated array is empty'.
+     * <pre>Validate.notEmpty(myArray);</pre>
+     * 
+     * <p>The message in the exception is &quot;The validated array is 
+     * empty&quot;.
      * 
-     * @param array  the array to check is not empty
+     * @param array the array to check
      * @throws IllegalArgumentException if the array is empty
      */
     public static void notEmpty(Object[] array) {
@@ -267,15 +237,14 @@
     //---------------------------------------------------------------------------------
 
     /**
-     * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
-     * if the argument Collection is empty (<code>null</code> or no elements).</p>
+     * <p>Validate that the specified argument collection is neither <code>null</code>

+     * nor a size of zero (no elements); otherwise throwing an exception 
+     * with the specified message.
      *
-     * <pre>
-     * Validate.notEmpty(myCollection, "The collection must not be empty");
-     * </pre>
+     * <pre>Validate.notEmpty(myCollection, "The collection must not be empty");</pre>
      * 
-     * @param collection  the collection to check is not empty
-     * @param message  the exception message you would like to see if the collection is empty
+     * @param collection the collection to check
+     * @param message the exception message if invalid
      * @throws IllegalArgumentException if the collection is empty
      */
     public static void notEmpty(Collection collection, String message) {
@@ -285,16 +254,15 @@
     }
 
     /**
-     * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
-     * if the argument Collection is empty (<code>null</code> or no elements).</p>
-     *
-     * <pre>
-     * Validate.notEmpty(myCollection);
-     * </pre>
+     * <p>Validate that the specified argument collection is neither <code>null</code>

+     * nor a size of zero (no elements); otherwise throwing an exception. 
      *
-     * <p>The message in the exception is 'The validated collection is empty'.</p>
+     * <pre>Validate.notEmpty(myCollection);</pre>
+     * 
+     * <p>The message in the exception is &quot;The validated collection is 
+     * empty&quot;.</p>
      * 
-     * @param collection  the collection to check is not empty
+     * @param collection the collection to check
      * @throws IllegalArgumentException if the collection is empty
      */
     public static void notEmpty(Collection collection) {
@@ -307,15 +275,14 @@
     //---------------------------------------------------------------------------------
 
     /**
-     * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
-     * if the argument Map is empty (<code>null</code> or no elements).</p>
+     * <p>Validate that the specified argument map is neither <code>null</code>

+     * nor a size of zero (no elements); otherwise throwing an exception 
+     * with the specified message.
      *
-     * <pre>
-     * Validate.notEmpty(myMap, "The map must not be empty");
-     * </pre>
+     * <pre>Validate.notEmpty(myMap, "The map must not be empty");</pre>
      * 
-     * @param map  the map to check is not empty
-     * @param message  the exception message you would like to see if the map is empty
+     * @param map the map to check
+     * @param message the exception message if invalid
      * @throws IllegalArgumentException if the map is empty
      */
     public static void notEmpty(Map map, String message) {
@@ -325,17 +292,17 @@
     }
 
     /**
-     * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
-     * if the argument Map is empty (<code>null</code> or no elements).</p>
+     * <p>Validate that the specified argument map is neither <code>null</code>

+     * nor a size of zero (no elements); otherwise throwing an exception. 
      *
-     * <pre>
-     * Validate.notEmpty(myMap);
-     * </pre>
-     *
-     * <p>The message in the exception is 'The validated map is empty'.</p>
+     * <pre>Validate.notEmpty(myMap);</pre>
      * 
-     * @param map  the map to check is not empty
+     * <p>The message in the exception is &quot;The validated map is 
+     * empty&quot;.</p>
+     * 
+     * @param map the map to check
      * @throws IllegalArgumentException if the map is empty
+     * @see #notEmpty(Map, String, Object...)
      */
     public static void notEmpty(Map map) {
         if (map == null || map.size() == 0) {
@@ -347,15 +314,14 @@
     //---------------------------------------------------------------------------------
 
     /**
-     * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
-     * if the argument String is empty (<code>null</code> or zero length).</p>
+     * <p>Validate that the specified argument string is 
+     * neither <code>null</code> nor a length of zero (no characters); 
+     * otherwise throwing an exception with the specified message.
      *
-     * <pre>
-     * Validate.notEmpty(myString, "The string must not be empty");
-     * </pre>
+     * <pre>Validate.notEmpty(myString, "The string must not be empty");</pre>
      * 
-     * @param string  the string to check is not empty
-     * @param message  the exception message you would like to see if the string is empty
+     * @param string the string to check
+     * @param message the exception message if invalid
      * @throws IllegalArgumentException if the string is empty
      */
     public static void notEmpty(String string, String message) {
@@ -365,16 +331,16 @@
     }
 
     /**
-     * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
-     * if the argument String is empty (<code>null</code> or zero length).</p>
-     *
-     * <pre>
-     * Validate.notEmpty(myString);
-     * </pre>
+     * <p>Validate that the specified argument string is 
+     * neither <code>null</code> nor a length of zero (no characters); 
+     * otherwise throwing an exception with the specified message.
      *
-     * <p>The message in the exception is 'The validated string is empty'.</p>
+     * <pre>Validate.notEmpty(myString);</pre>
+     * 
+     * <p>The message in the exception is &quot;The validated 
+     * string is empty&quot;.</p>
      * 
-     * @param string  the string to check is not empty
+     * @param string the string to check
      * @throws IllegalArgumentException if the string is empty
      */
     public static void notEmpty(String string) {
@@ -387,21 +353,19 @@
     //---------------------------------------------------------------------------------
 
     /**
-     * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
-     * if the argument array has <code>null</code> elements or is
-     * <code>null</code>.</p>
-     *
-     * <pre>
-     * Validate.noNullElements(myArray, "The array must not contain null elements");
-     * </pre>
-     * 
-     * <p>If the array is null then the message in the exception is 'The validated
object is null'.</p>
-     *
-     * @param array  the array to check
-     * @param message  the exception message if the array has
-     *  <code>null</code> elements
-     * @throws IllegalArgumentException if the array has <code>null</code>
-     *  elements or is <code>null</code>
+     * <p>Validate that the specified argument array is neither 
+     * <code>null</code> nor contains any elements that are <code>null</code>;
+     * otherwise throwing an exception with the specified message.
+     *
+     * <pre>Validate.noNullElements(myArray, "The array contain null at position %d");</pre>
+     * 
+     * <p>If the array is <code>null</code>, then the message in the exception

+     * is &quot;The validated object is null&quot;.</p>
+     *
+     * @param array the array to check
+     * @param message the exception message if the collection has <code>null</code>
elements
+     * @throws IllegalArgumentException if the array is <code>null</code> or
+     * an element in the array is <code>null</code>
      */
     public static void noNullElements(Object[] array, String message) {
         Validate.notNull(array);
@@ -413,22 +377,22 @@
     }
 
     /**
-     * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
-     * if the argument array has <code>null</code> elements or is
-     * <code>null</code>.</p>
-     *
-     * <pre>
-     * Validate.noNullElements(myArray);
-     * </pre>
-     *
-     * <p>If the array has a null element the message in the exception is
-     * 'The validated array contains null element at index: '.</p>
-     *
-     * <p>If the array is null then the message in the exception is 'The validated
object is null'.</p>
-     * 
-     * @param array  the array to check
-     * @throws IllegalArgumentException if the array has <code>null</code>
-     *  elements or is <code>null</code>
+     * <p>Validate that the specified argument array is neither 
+     * <code>null</code> nor contains any elements that are <code>null</code>;
+     * otherwise throwing an exception.
+     *
+     * <pre>Validate.noNullElements(myArray);</pre>
+     * 
+     * <p>If the array is <code>null</code>, then the message in the exception

+     * is &quot;The validated object is null&quot;.</p>
+     * 
+     * <p>If the array has a <code>null</code> element, then the message
in the
+     * exception is &quot;The validated array contains null element at index: 
+     * &quot followed by the index.</p>
+     *
+     * @param array the array to check
+     * @throws IllegalArgumentException if the array is <code>null</code> or
+     * an element in the array is <code>null</code>
      */
     public static void noNullElements(Object[] array) {
         Validate.notNull(array);
@@ -443,21 +407,20 @@
     //---------------------------------------------------------------------------------
 
     /**
-     * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
-     * if the argument Collection has <code>null</code> elements or is
-     * <code>null</code>.</p>
-     *
-     * <pre>
-     * Validate.noNullElements(myCollection, "The collection must not contain null elements");
-     * </pre>
+     * <p>Validate that the specified argument collection is neither 
+     * <code>null</code> nor contains any elements that are <code>null</code>;
+     * otherwise throwing an exception with the specified message.
      *
-     * <p>If the collection is null then the message in the exception is 'The validated
object is null'.</p>
+     * <pre>Validate.noNullElements(myCollection, "The collection contains null elements");</pre>
+     * 
+     * <p>If the collection is <code>null</code>, then the message in the
exception 
+     * is &quot;The validated object is null&quot;.</p>
      * 
+     *
      * @param collection  the collection to check
      * @param message  the exception message if the collection has
-     *  <code>null</code> elements
-     * @throws IllegalArgumentException if the collection has
-     *  <code>null</code> elements or is <code>null</code>
+     * @throws IllegalArgumentException if the collection is <code>null</code>
or
+     * an element in the collection is <code>null</code>
      */
     public static void noNullElements(Collection collection, String message) {
         Validate.notNull(collection);
@@ -469,21 +432,22 @@
     }
 
     /**
-     * <p>Validate an argument, throwing <code>IllegalArgumentException</code>
-     * if the argument Collection has <code>null</code> elements or is
-     * <code>null</code>.</p>
+     * <p>Validate that the specified argument collection is neither 
+     * <code>null</code> nor contains any elements that are <code>null</code>;
+     * otherwise throwing an exception.
+     *
+     * <pre>Validate.noNullElements(myCollection);</pre>
+     * 
+     * <p>If the collection is <code>null</code>, then the message in the
exception 
+     * is &quot;The validated object is null&quot;.</p>
+     * 
+     * <p>If the collection has a <code>null</code> element, then the message
in the
+     * exception is &quot;The validated collection contains null element at index: 
+     * &quot followed by the index.</p>
      *
-     * <pre>
-     * Validate.noNullElements(myCollection);
-     * </pre>
-     *
-     * <p>The message in the exception is 'The validated collection contains null element
at index: '.</p>
-     *
-     * <p>If the collection is null then the message in the exception is 'The validated
object is null'.</p>
-     * 
      * @param collection  the collection to check
-     * @throws IllegalArgumentException if the collection has
-     *  <code>null</code> elements or is <code>null</code>
+     * @throws IllegalArgumentException if the collection is <code>null</code>
or
+     * an element in the collection is <code>null</code>
      */
     public static void noNullElements(Collection collection) {
         Validate.notNull(collection);
@@ -533,10 +497,8 @@
      * The message in the exception is 'The validated collection contains an element not
of type clazz at index: '.
      * </p>
      * 
-     * @param collection
-     *            the collection to check, not null
-     * @param clazz
-     *            the <code>Class</code> which the collection's elements are
expected to be, not null
+     * @param collection  the collection to check, not null
+     * @param clazz  the <code>Class</code> which the collection's elements are
expected to be, not null
      * @since 2.1
      */
     public static void allElementsOfType(Collection collection, Class clazz) {



Mime
View raw message