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 "The validated expression is
+ * false".</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 "The validated object is
+ * null".</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 "The validated array is
+ * empty".
*
- * @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 "The validated collection is
+ * empty".</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 "The validated map is
+ * empty".</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 "The validated
+ * string is empty".</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 "The validated object is null".</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 "The validated object is null".</p>
+ *
+ * <p>If the array has a <code>null</code> element, then the message in the
+ * exception is "The validated array contains null element at index:
+ * " 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 "The validated object is null".</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 "The validated object is null".</p>
+ *
+ * <p>If the collection has a <code>null</code> element, then the message
in the
+ * exception is "The validated collection contains null element at
index:
+ * " 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) {
