Author: scolebourne
Date: Fri Mar 4 14:27:50 2011
New Revision: 1077965
URL: http://svn.apache.org/viewvc?rev=1077965&view=rev
Log:
Javadoc
Modified:
commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/Validate.java
Modified:
commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/Validate.java
URL:
http://svn.apache.org/viewvc/commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/Validate.java?rev=1077965&r1=1077964&r2=1077965&view=diff
==============================================================================
---
commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/Validate.java
(original)
+++
commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/Validate.java
Fri Mar 4 14:27:50 2011
@@ -90,9 +90,9 @@ public class Validate {
* <p>For performance reasons, the long 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
+ * @param expression the boolean expression to check
+ * @param message the {@link String#format(String, Object...)} exception
message if invalid, not null
+ * @param value the value to append to the message when invalid
* @throws IllegalArgumentException if expression is <code>false</code>
* @see #isTrue(boolean)
* @see #isTrue(boolean, String, double)
@@ -115,9 +115,9 @@ public class Validate {
* <p>For performance reasons, the double 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
+ * @param expression the boolean expression to check
+ * @param message the {@link String#format(String, Object...)} exception
message if invalid, not null
+ * @param value the value to append to the message when invalid
* @throws IllegalArgumentException if expression is <code>false</code>
* @see #isTrue(boolean)
* @see #isTrue(boolean, String, long)
@@ -139,9 +139,9 @@ public class Validate {
* Validate.isTrue(i >= min && i <= max, "The value must be between %d and
%d", min, max);
* Validate.isTrue(myObject.isOk(), "The object is not okay");</pre>
*
- * @param expression the boolean expression to check
- * @param message the exception message if invalid
- * @param values the optional values for the formatted exception message
+ * @param expression the boolean expression to check
+ * @param message the {@link String#format(String, Object...)} exception
message if invalid, not null
+ * @param values the optional values for the formatted exception message,
null array not recommended
* @throws IllegalArgumentException if expression is <code>false</code>
* @see #isTrue(boolean)
* @see #isTrue(boolean, String, long)
@@ -166,7 +166,7 @@ public class Validate {
* <p>The message of the exception is "The validated expression is
* false".</p>
*
- * @param expression the boolean expression to check
+ * @param expression the boolean expression to check
* @throws IllegalArgumentException if expression is <code>false</code>
* @see #isTrue(boolean, String, long)
* @see #isTrue(boolean, String, double)
@@ -191,7 +191,7 @@ public class Validate {
* null".</p>
*
* @param <T> the object type
- * @param object the object to check
+ * @param object the object to check
* @return the validated object (never <code>null</code> for method
chaining)
* @throws NullPointerException if the object is <code>null</code>
* @see #notNull(Object, String, Object...)
@@ -207,9 +207,9 @@ public class Validate {
* <pre>Validate.notNull(myObject, "The object must not be null");</pre>
*
* @param <T> the object type
- * @param object the object to check
- * @param message the exception message if invalid
- * @param values the optional values for the formatted exception message
+ * @param object the object to check
+ * @param message the {@link String#format(String, Object...)} exception
message if invalid, not null
+ * @param values the optional values for the formatted exception message
* @return the validated object (never <code>null</code> for method
chaining)
* @throws NullPointerException if the object is <code>null</code>
* @see #notNull(Object)
@@ -232,8 +232,9 @@ public class Validate {
* <pre>Validate.notEmpty(myArray, "The array must not be empty");</pre>
*
* @param <T> the array type
- * @param array the array to check
- * @param message the exception message if invalid
+ * @param array the array to check, validated not null by this method
+ * @param message the {@link String#format(String, Object...)} exception
message if invalid, not null
+ * @param values the optional values for the formatted exception message,
null array not recommended
* @return the validated array (never <code>null</code> method for
chaining)
* @throws NullPointerException if the array is <code>null</code>
* @throws IllegalArgumentException if the array is empty
@@ -259,7 +260,7 @@ public class Validate {
* empty".
*
* @param <T> the array type
- * @param array the array to check
+ * @param array the array to check, validated not null by this method
* @return the validated array (never <code>null</code> method for
chaining)
* @throws NullPointerException if the array is <code>null</code>
* @throws IllegalArgumentException if the array is empty
@@ -280,8 +281,9 @@ public class Validate {
* <pre>Validate.notEmpty(myCollection, "The collection must not be
empty");</pre>
*
* @param <T> the collection type
- * @param collection the collection to check
- * @param message the exception message if invalid
+ * @param collection the collection to check, validated not null by this
method
+ * @param message the {@link String#format(String, Object...)} exception
message if invalid, not null
+ * @param values the optional values for the formatted exception message,
null array not recommended
* @return the validated collection (never <code>null</code> method for
chaining)
* @throws NullPointerException if the collection is <code>null</code>
* @throws IllegalArgumentException if the collection is empty
@@ -307,7 +309,7 @@ public class Validate {
* empty".</p>
*
* @param <T> the collection type
- * @param collection the collection to check
+ * @param collection the collection to check, validated not null by this
method
* @return the validated collection (never <code>null</code> method for
chaining)
* @throws NullPointerException if the collection is <code>null</code>
* @throws IllegalArgumentException if the collection is empty
@@ -328,8 +330,9 @@ public class Validate {
* <pre>Validate.notEmpty(myMap, "The map must not be empty");</pre>
*
* @param <T> the map type
- * @param map the map to check
- * @param message the exception message if invalid
+ * @param map the map to check, validated not null by this method
+ * @param message the {@link String#format(String, Object...)} exception
message if invalid, not null
+ * @param values the optional values for the formatted exception message,
null array not recommended
* @return the validated map (never <code>null</code> method for chaining)
* @throws NullPointerException if the map is <code>null</code>
* @throws IllegalArgumentException if the map is empty
@@ -355,7 +358,7 @@ public class Validate {
* empty".</p>
*
* @param <T> the map type
- * @param map the map to check
+ * @param map the map to check, validated not null by this method
* @return the validated map (never <code>null</code> method for chaining)
* @throws NullPointerException if the map is <code>null</code>
* @throws IllegalArgumentException if the map is empty
@@ -376,8 +379,9 @@ public class Validate {
* <pre>Validate.notEmpty(myString, "The string must not be empty");</pre>
*
* @param <T> the character sequence type
- * @param chars the character sequence to check
- * @param message the exception message if invalid
+ * @param chars the character sequence to check, validated not null by
this method
+ * @param message the {@link String#format(String, Object...)} exception
message if invalid, not null
+ * @param values the optional values for the formatted exception message,
null array not recommended
* @return the validated character sequence (never <code>null</code>
method for chaining)
* @throws NullPointerException if the character sequence is
<code>null</code>
* @throws IllegalArgumentException if the character sequence is empty
@@ -404,7 +408,7 @@ public class Validate {
* character sequence is empty".</p>
*
* @param <T> the character sequence type
- * @param chars the character sequence to check
+ * @param chars the character sequence to check, validated not null by
this method
* @return the validated character sequence (never <code>null</code>
method for chaining)
* @throws NullPointerException if the character sequence is
<code>null</code>
* @throws IllegalArgumentException if the character sequence is empty
@@ -426,8 +430,9 @@ public class Validate {
* <pre>Validate.notBlank(myString, "The string must not be blank");</pre>
*
* @param <T> the character sequence type
- * @param chars the character sequence to check
- * @param message the exception message if invalid
+ * @param chars the character sequence to check, validated not null by
this method
+ * @param message the {@link String#format(String, Object...)} exception
message if invalid, not null
+ * @param values the optional values for the formatted exception message,
null array not recommended
* @return the validated character sequence (never <code>null</code>
method for chaining)
* @throws NullPointerException if the character sequence is
<code>null</code>
* @throws IllegalArgumentException if the character sequence is blank
@@ -454,7 +459,7 @@ public class Validate {
* sequence is blank".</p>
*
* @param <T> the character sequence type
- * @param chars the character sequence to check
+ * @param chars the character sequence to check, validated not null by
this method
* @return the validated character sequence (never <code>null</code>
method for chaining)
* @throws NullPointerException if the character sequence is
<code>null</code>
* @throws IllegalArgumentException if the character sequence is blank
@@ -482,7 +487,9 @@ public class Validate {
* argument.</p>
*
* @param <T> the array type
- * @param array the array to check
+ * @param array the array to check, validated not null by this method
+ * @param message the {@link String#format(String, Object...)} exception
message if invalid, not null
+ * @param values the optional values for the formatted exception message,
null array not recommended
* @return the validated array (never <code>null</code> method for
chaining)
* @throws NullPointerException if the array is <code>null</code>
* @throws IllegalArgumentException if an element is <code>null</code>
@@ -514,7 +521,7 @@ public class Validate {
* " followed by the index.</p>
*
* @param <T> the array type
- * @param array the array to check
+ * @param array the array to check, validated not null by this method
* @return the validated array (never <code>null</code> method for
chaining)
* @throws NullPointerException if the array is <code>null</code>
* @throws IllegalArgumentException if an element is <code>null</code>
@@ -542,7 +549,9 @@ public class Validate {
* argument.</p>
*
* @param <T> the iterable type
- * @param iterable the iterable to check
+ * @param iterable the iterable to check, validated not null by this
method
+ * @param message the {@link String#format(String, Object...)} exception
message if invalid, not null
+ * @param values the optional values for the formatted exception message,
null array not recommended
* @return the validated iterable (never <code>null</code> method for
chaining)
* @throws NullPointerException if the array is <code>null</code>
* @throws IllegalArgumentException if an element is <code>null</code>
@@ -575,7 +584,7 @@ public class Validate {
* " followed by the index.</p>
*
* @param <T> the iterable type
- * @param iterable the iterable to check
+ * @param iterable the iterable to check, validated not null by this
method
* @return the validated iterable (never <code>null</code> method for
chaining)
* @throws NullPointerException if the array is <code>null</code>
* @throws IllegalArgumentException if an element is <code>null</code>
@@ -598,9 +607,10 @@ public class Validate {
* is "The validated object is null".</p>
*
* @param <T> the array type
- * @param array the array to check
- * @param index the index
- * @param message the exception message if invalid
+ * @param array the array to check, validated not null by this method
+ * @param index the index to check
+ * @param message the {@link String#format(String, Object...)} exception
message if invalid, not null
+ * @param values the optional values for the formatted exception message,
null array not recommended
* @return the validated array (never <code>null</code> for method
chaining)
* @throws NullPointerException if the array is <code>null</code>
* @throws IndexOutOfBoundsException if the index is invalid
@@ -628,8 +638,8 @@ public class Validate {
* index.</p>
*
* @param <T> the array type
- * @param array the array to check
- * @param index the index
+ * @param array the array to check, validated not null by this method
+ * @param index the index to check
* @return the validated array (never <code>null</code> for method
chaining)
* @throws NullPointerException if the array is <code>null</code>
* @throws IndexOutOfBoundsException if the index is invalid
@@ -652,9 +662,10 @@ public class Validate {
* exception is "The validated object is null".</p>
*
* @param <T> the collection type
- * @param collection the collection to check
- * @param index the index
- * @param message the exception message if invalid
+ * @param collection the collection to check, validated not null by this
method
+ * @param index the index to check
+ * @param message the {@link String#format(String, Object...)} exception
message if invalid, not null
+ * @param values the optional values for the formatted exception message,
null array not recommended
* @return the validated collection (never <code>null</code> for chaining)
* @throws NullPointerException if the collection is <code>null</code>
* @throws IndexOutOfBoundsException if the index is invalid
@@ -679,8 +690,8 @@ public class Validate {
* followed by the index.</p>
*
* @param <T> the collection type
- * @param collection the collection to check
- * @param index the index
+ * @param collection the collection to check, validated not null by this
method
+ * @param index the index to check
* @return the validated collection (never <code>null</code> for method
chaining)
* @throws NullPointerException if the collection is <code>null</code>
* @throws IndexOutOfBoundsException if the index is invalid
@@ -704,9 +715,10 @@ public class Validate {
* of the exception is "The validated object is null".</p>
*
* @param <T> the character sequence type
- * @param chars the character sequence to check
- * @param index the index
- * @param message the exception message if invalid
+ * @param chars the character sequence to check, validated not null by
this method
+ * @param index the index to check
+ * @param message the {@link String#format(String, Object...)} exception
message if invalid, not null
+ * @param values the optional values for the formatted exception message,
null array not recommended
* @return the validated character sequence (never <code>null</code> for
method chaining)
* @throws NullPointerException if the character sequence is
<code>null</code>
* @throws IndexOutOfBoundsException if the index is invalid
@@ -735,8 +747,8 @@ public class Validate {
* followed by the index.</p>
*
* @param <T> the character sequence type
- * @param chars the character sequence to check
- * @param index the index
+ * @param chars the character sequence to check, validated not null by
this method
+ * @param index the index to check
* @return the validated character sequence (never <code>null</code> for
method chaining)
* @throws NullPointerException if the character sequence is
<code>null</code>
* @throws IndexOutOfBoundsException if the index is invalid
@@ -746,6 +758,9 @@ public class Validate {
return validIndex(chars, index,
DEFAULT_VALID_INDEX_CHAR_SEQUENCE_EX_MESSAGE, Integer.valueOf(index));
}
+ // validState
+
//---------------------------------------------------------------------------------
+
/**
* <p>Validate that the stateful condition is <code>true</code>; otherwise
* throwing an exception. This method is useful when validating according
@@ -759,7 +774,7 @@ public class Validate {
* <p>The message of the exception is "The validated state is
* false".</p>
*
- * @param expression the boolean expression to check
+ * @param expression the boolean expression to check
* @throws IllegalStateException if expression is <code>false</code>
* @see #validState(boolean, String, Object...)
*/
@@ -777,9 +792,9 @@ public class Validate {
*
* <pre>Validate.validState(this.isOk(), "The state is not OK: %s",
myObject);</pre>
*
- * @param expression the boolean expression to check
- * @param message the exception message if invalid
- * @param values the optional values for the formatted exception message
+ * @param expression the boolean expression to check
+ * @param message the {@link String#format(String, Object...)} exception
message if invalid, not null
+ * @param values the optional values for the formatted exception message,
null array not recommended
* @throws IllegalStateException if expression is <code>false</code>
* @see #validState(boolean)
*/
@@ -788,7 +803,10 @@ public class Validate {
throw new IllegalStateException(String.format(message, values));
}
}
-
+
+ // matchesPattern
+
//---------------------------------------------------------------------------------
+
/**
* <p>Validate that the specified argument character sequence matches the
specified regular
* expression pattern; otherwise throwing an exception.</p>
@@ -797,8 +815,8 @@ public class Validate {
*
* <p>The syntax of the pattern is the one used in the {@link Pattern}
class.</p>
*
- * @param input the character sequence to validate
- * @param pattern regular expression pattern
+ * @param input the character sequence to validate, not null
+ * @param pattern the regular expression pattern, not null
* @throws IllegalArgumentException if the character sequence does not
match the pattern
* @see #matchesPattern(CharSequence, String, String, Object...)
*/
@@ -807,7 +825,7 @@ public class Validate {
throw new
IllegalArgumentException(String.format(DEFAULT_MATCHES_PATTERN_EX, input,
pattern));
}
}
-
+
/**
* <p>Validate that the specified argument character sequence matches the
specified regular
* expression pattern; otherwise throwing an exception with the specified
message.</p>
@@ -816,10 +834,10 @@ public class Validate {
*
* <p>The syntax of the pattern is the one used in the {@link Pattern}
class.</p>
*
- * @param input the character sequence to validate
- * @param pattern regular expression pattern
- * @param message the exception message
- * @param values (optional) values to replace in the exception message
+ * @param input the character sequence to validate, not null
+ * @param pattern the regular expression pattern, not null
+ * @param message the {@link String#format(String, Object...)} exception
message if invalid, not null
+ * @param values the optional values for the formatted exception message,
null array not recommended
* @throws IllegalArgumentException if the character sequence does not
match the pattern
* @see #matchesPattern(CharSequence, String)
*/
@@ -828,16 +846,19 @@ public class Validate {
throw new IllegalArgumentException(String.format(message, values));
}
}
-
+
+ // inclusiveBetween
+
//---------------------------------------------------------------------------------
+
/**
* <p>Validate that the specified argument object fall between the two
* inclusive values specified; otherwise, throws an exception.</p>
*
* <pre>Validate.inclusiveBetween(0, 2, 1);</pre>
*
- * @param value the object to validate
- * @param start the inclusive start value
- * @param end the inclusive end value
+ * @param start the inclusive start value, not null
+ * @param end the inclusive end value, not null
+ * @param value the object to validate, not null
* @throws IllegalArgumentException if the value falls out of the
boundaries
* @see #inclusiveBetween(Object, Object, Comparable, String, Object...)
*/
@@ -846,7 +867,7 @@ public class Validate {
throw new
IllegalArgumentException(String.format(DEFAULT_INCLUSIVE_BETWEEN_EX_MESSAGE,
value, start, end));
}
}
-
+
/**
* <p>Validate that the specified argument object fall between the two
* inclusive values specified; otherwise, throws an exception with the
@@ -854,11 +875,11 @@ public class Validate {
*
* <pre>Validate.inclusiveBetween(0, 2, 1, "Not in boundaries");</pre>
*
- * @param value the object to validate
- * @param start the inclusive start value
- * @param end the inclusive end value
- * @param message the exception message
- * @param values to replace in the exception message (optional)
+ * @param start the inclusive start value, not null
+ * @param end the inclusive end value, not null
+ * @param value the object to validate, not null
+ * @param message the {@link String#format(String, Object...)} exception
message if invalid, not null
+ * @param values the optional values for the formatted exception message,
null array not recommended
* @throws IllegalArgumentException if the value falls out of the
boundaries
* @see #inclusiveBetween(Object, Object, Comparable)
*/
@@ -867,16 +888,19 @@ public class Validate {
throw new IllegalArgumentException(String.format(message, values));
}
}
-
+
+ // exclusiveBetween
+
//---------------------------------------------------------------------------------
+
/**
* <p>Validate that the specified argument object fall between the two
* exclusive values specified; otherwise, throws an exception.</p>
*
* <pre>Validate.inclusiveBetween(0, 2, 1);</pre>
*
- * @param value the object to validate
- * @param start the exclusive start value
- * @param end the exclusive end value
+ * @param start the exclusive start value, not null
+ * @param end the exclusive end value, not null
+ * @param value the object to validate, not null
* @throws IllegalArgumentException if the value falls out of the
boundaries
* @see #exclusiveBetween(Object, Object, Comparable, String, Object...)
*/
@@ -885,7 +909,7 @@ public class Validate {
throw new
IllegalArgumentException(String.format(DEFAULT_EXCLUSIVE_BETWEEN_EX_MESSAGE,
value, start, end));
}
}
-
+
/**
* <p>Validate that the specified argument object fall between the two
* exclusive values specified; otherwise, throws an exception with the
@@ -893,11 +917,11 @@ public class Validate {
*
* <pre>Validate.inclusiveBetween(0, 2, 1, "Not in boundaries");</pre>
*
- * @param value the object to validate
- * @param start the exclusive start value
- * @param end the exclusive end value
- * @param message the exception message
- * @param values to replace in the exception message (optional)
+ * @param start the exclusive start value, not null
+ * @param end the exclusive end value, not null
+ * @param value the object to validate, not null
+ * @param message the {@link String#format(String, Object...)} exception
message if invalid, not null
+ * @param values the optional values for the formatted exception message,
null array not recommended
* @throws IllegalArgumentException if the value falls out of the
boundaries
* @see #exclusiveBetween(Object, Object, Comparable)
*/
@@ -907,6 +931,9 @@ public class Validate {
}
}
+ // isInstanceOf
+
//---------------------------------------------------------------------------------
+
/**
* <p>Validate that the argument is an instance of the specified class;
otherwise
* throwing an exception. This method is useful when validating according
to an arbitrary
@@ -917,17 +944,17 @@ public class Validate {
* <p>The message of the exception is "The validated object is not an
instance of"
* followed by the name of the class</p>
*
- * @param type the class the object must be validated against
- * @param o the object to check
+ * @param type the class the object must be validated against, not null
+ * @param obj the object to check, null throws an exception
* @throws IllegalArgumentException if argument is not of specified class
* @see #isInstanceOf(Class, Object, String, Object...)
*/
- public static void isInstanceOf(Class<?> type, Object o) {
- if (type.isInstance(o) == false) {
+ public static void isInstanceOf(Class<?> type, Object obj) {
+ if (type.isInstance(obj) == false) {
throw new
IllegalArgumentException(String.format(DEFAULT_IS_INSTANCE_OF_EX_MESSAGE,
type.getName()));
}
}
-
+
/**
* <p>Validate that the argument is an instance of the specified class;
otherwise
* throwing an exception with the specified message. This method is useful
when
@@ -935,19 +962,22 @@ public class Validate {
*
* <pre>Validate.isInstanceOf(OkClass.classs, object, "Wrong class, object
is of class %s", object.getClass().getName());</pre>
*
- * @param type the class the object must be validated against
- * @param o the object to check
- * @param message exception message
- * @param values optional value for the exception message
+ * @param type the class the object must be validated against, not null
+ * @param obj the object to check, null throws an exception
+ * @param message the {@link String#format(String, Object...)} exception
message if invalid, not null
+ * @param values the optional values for the formatted exception message,
null array not recommended
* @throws IllegalArgumentException if argument is not of specified class
* @see #isInstanceOf(Class, Object)
*/
- public static void isInstanceOf(Class<?> type, Object o, String message,
Object... values) {
- if (type.isInstance(o) == false) {
+ public static void isInstanceOf(Class<?> type, Object obj, String message,
Object... values) {
+ if (type.isInstance(obj) == false) {
throw new IllegalArgumentException(String.format(message, values));
}
}
-
+
+ // isAssignableFrom
+
//---------------------------------------------------------------------------------
+
/**
* <p>Validate that the argument can be converted to the specified class;
otherwise
* throwing an exception with the specified message. This method is useful
when
@@ -958,8 +988,8 @@ public class Validate {
* <p>The message of the exception is "The validated object can not
be converted to the"
* followed by the name of the class and "class"</p>
*
- * @param superType the class the class must be validated against
- * @param type the class to check
+ * @param superType the class the class must be validated against, not
null
+ * @param type the class to check, not null
* @throws IllegalArgumentException if argument can not be converted to
the specified class
* @see #isAssignableFrom(Class, Class, String, Object...)
*/
@@ -968,7 +998,7 @@ public class Validate {
throw new
IllegalArgumentException(String.format(DEFAULT_IS_ASSIGNABLE_EX_MESSAGE,
superType.getName()));
}
}
-
+
/**
* <p>Validate that the argument can be converted to the specified class;
otherwise
* throwing an exception. This method is useful when validating if there
will be no
@@ -979,10 +1009,10 @@ public class Validate {
* <p>The message of the exception is "The validated object can not
be converted to the"
* followed by the name of the class and "class"</p>
*
- * @param superType the class the class must be validated against
- * @param type the class to check
- * @param message the exception message if invalid
- * @param values the optional values for the formatted exception message
+ * @param superType the class the class must be validated against, not
null
+ * @param type the class to check, not null
+ * @param message the {@link String#format(String, Object...)} exception
message if invalid, not null
+ * @param values the optional values for the formatted exception message,
null array not recommended
* @throws IllegalArgumentException if argument can not be converted to
the specified class
* @see #isAssignableFrom(Class, Class)
*/
