Correct Javadocs of methods that use Validate.notNull() and replace some uses of Validate.isTrue() with Validate.notNull(). (#525)

* Update Javadocs of methods that call Validate.notNull() to refer to NullPointerException instead of IllegalArgumentException for null values.

* Use Validate.notNull() instead of Validate.isTrue() to check for null values, and update the associated tests to check for NullPointerException instead of IllegalArgumentException.

src/main/java/org/apache/commons/lang3/CharUtils.java

@@ -131,7 +131,7 @@ public static Character toCharacterObject(final String str) {
      *
      * @param ch  the character to convert
      * @return the char value of the Character
-     * @throws IllegalArgumentException if the Character is null
+     * @throws NullPointerException if the Character is null
      */
     public static char toChar(final Character ch) {
         Validate.notNull(ch, "The Character must not be null");
@@ -172,6 +172,7 @@ public static char toChar(final Character ch, final char defaultValue) {
      *
      * @param str  the character to convert
      * @return the char value of the first letter of the String
+     * @throws NullPointerException if the string is null
      * @throws IllegalArgumentException if the String is empty
      */
     public static char toChar(final String str) {
@@ -260,7 +261,8 @@ public static int toIntValue(final char ch, final int defaultValue) {
      *
      * @param ch  the character to convert, not null
      * @return the int value of the character
-     * @throws IllegalArgumentException if the Character is not ASCII numeric or is null
+     * @throws NullPointerException if the Character is null
+     * @throws IllegalArgumentException if the Character is not ASCII numeric
      */
     public static int toIntValue(final Character ch) {
         Validate.notNull(ch, "The character must not be null");

src/main/java/org/apache/commons/lang3/SerializationUtils.java

@@ -129,7 +129,7 @@ public static <T extends Serializable> T roundtrip(final T msg) {
      *
      * @param obj  the object to serialize to bytes, may be null
      * @param outputStream  the stream to write to, must not be null
-     * @throws IllegalArgumentException if {@code outputStream} is {@code null}
+     * @throws NullPointerException if {@code outputStream} is {@code null}
      * @throws SerializationException (runtime) if the serialization fails
      */
     public static void serialize(final Serializable obj, final OutputStream outputStream) {
@@ -182,10 +182,8 @@ public static byte[] serialize(final Serializable obj) {
      * @param inputStream
      *            the serialized object input stream, must not be null
      * @return the deserialized object
-     * @throws IllegalArgumentException
+     * @throws NullPointerException if {@code inputStream} is {@code null}
-     *             if {@code inputStream} is {@code null}
+     * @throws SerializationException (runtime) if the serialization fails
-     * @throws SerializationException
-     *             (runtime) if the serialization fails
      */
     public static <T> T deserialize(final InputStream inputStream) {
         Validate.notNull(inputStream, "The InputStream must not be null");
@@ -213,10 +211,8 @@ public static <T> T deserialize(final InputStream inputStream) {
      * @param objectData
      *            the serialized object, must not be null
      * @return the deserialized object
-     * @throws IllegalArgumentException
+     * @throws NullPointerException if {@code objectData} is {@code null}
-     *             if {@code objectData} is {@code null}
+     * @throws SerializationException (runtime) if the serialization fails
-     * @throws SerializationException
-     *             (runtime) if the serialization fails
      */
     public static <T> T deserialize(final byte[] objectData) {
         Validate.notNull(objectData, "The byte[] must not be null");

src/main/java/org/apache/commons/lang3/builder/DiffBuilder.java

@@ -943,8 +943,7 @@ public Object[] getRight() {
      * @param diffResult
      *            the {@code DiffResult} to append
      * @return this
-     * @throws IllegalArgumentException
+     * @throws NullPointerException if field name is {@code null}
-     *             if field name is {@code null}
      * @since 3.5
      */
     public DiffBuilder<T> append(final String fieldName,

src/main/java/org/apache/commons/lang3/builder/DiffResult.java

@@ -69,8 +69,7 @@ public class DiffResult<T> implements Iterable<Diff<?>> {
      *            the style to use for the {@link #toString()} method. May be
      *            {@code null}, in which case
      *            {@link ToStringStyle#DEFAULT_STYLE} is used
-     * @throws IllegalArgumentException
+     * @throws NullPointerException if {@code lhs}, {@code rhs} or {@code diffs} is {@code null}
-     *             if {@code lhs}, {@code rhs} or {@code diffs} is {@code null}
      */
     DiffResult(final T lhs, final T rhs, final List<Diff<?>> diffs,
             final ToStringStyle style) {

src/main/java/org/apache/commons/lang3/math/Fraction.java

@@ -308,7 +308,7 @@ public static Fraction getFraction(double value) {
      *
      * @param str  the string to parse, must not be {@code null}
      * @return the new {@code Fraction} instance
-     * @throws IllegalArgumentException if the string is {@code null}
+     * @throws NullPointerException if the string is {@code null}
      * @throws NumberFormatException if the number format is invalid
      */
     public static Fraction getFraction(String str) {
@@ -773,7 +773,7 @@ private Fraction addSub(final Fraction fraction, final boolean isAdd) {
      *
      * @param fraction  the fraction to multiply by, must not be {@code null}
      * @return a {@code Fraction} instance with the resulting values
-     * @throws IllegalArgumentException if the fraction is {@code null}
+     * @throws NullPointerException if the fraction is {@code null}
      * @throws ArithmeticException if the resulting numerator or denominator exceeds
      *  {@code Integer.MAX_VALUE}
      */
@@ -795,7 +795,7 @@ public Fraction multiplyBy(final Fraction fraction) {
      *
      * @param fraction  the fraction to divide by, must not be {@code null}
      * @return a {@code Fraction} instance with the resulting values
-     * @throws IllegalArgumentException if the fraction is {@code null}
+     * @throws NullPointerException if the fraction is {@code null}
      * @throws ArithmeticException if the fraction to divide by is zero
      * @throws ArithmeticException if the resulting numerator or denominator exceeds
      *  {@code Integer.MAX_VALUE}

src/main/java/org/apache/commons/lang3/math/IEEE754rUtils.java

@@ -32,7 +32,7 @@ public class IEEE754rUtils {
      *
      * @param array  an array, must not be null or empty
      * @return the minimum value in the array
-     * @throws IllegalArgumentException if {@code array} is {@code null}
+     * @throws NullPointerException if {@code array} is {@code null}
      * @throws IllegalArgumentException if {@code array} is empty
       * @since 3.4 Changed signature from min(double[]) to min(double...)
      */
@@ -54,7 +54,7 @@ public static double min(final double... array) {
      *
      * @param array  an array, must not be null or empty
      * @return the minimum value in the array
-     * @throws IllegalArgumentException if {@code array} is {@code null}
+     * @throws NullPointerException if {@code array} is {@code null}
      * @throws IllegalArgumentException if {@code array} is empty
      * @since 3.4 Changed signature from min(float[]) to min(float...)
      */
@@ -144,7 +144,7 @@ public static float min(final float a, final float b) {
      *
      * @param array  an array, must not be null or empty
      * @return the minimum value in the array
-     * @throws IllegalArgumentException if {@code array} is {@code null}
+     * @throws NullPointerException if {@code array} is {@code null}
      * @throws IllegalArgumentException if {@code array} is empty
      * @since 3.4 Changed signature from max(double[]) to max(double...)
      */
@@ -166,7 +166,7 @@ public static double max(final double... array) {
      *
      * @param array  an array, must not be null or empty
      * @return the minimum value in the array
-     * @throws IllegalArgumentException if {@code array} is {@code null}
+     * @throws NullPointerException if {@code array} is {@code null}
      * @throws IllegalArgumentException if {@code array} is empty
      * @since 3.4 Changed signature from max(float[]) to max(float...)
      */

src/main/java/org/apache/commons/lang3/reflect/FieldUtils.java

@@ -81,8 +81,8 @@ public static Field getField(final Class<?> cls, final String fieldName) {
      *            {@link java.lang.reflect.AccessibleObject#setAccessible(boolean)} method. {@code false} will only
      *            match {@code public} fields.
      * @return the Field object
-     * @throws IllegalArgumentException
+     * @throws NullPointerException if the class is {@code null}
-     *             if the class is {@code null}, or the field name is blank or empty or is matched at multiple places
+     * @throws IllegalArgumentException if the field name is blank or empty or is matched at multiple places
      * in the inheritance hierarchy
      */
     public static Field getField(final Class<?> cls, final String fieldName, final boolean forceAccess) {

src/main/java/org/apache/commons/lang3/reflect/MethodUtils.java

@@ -847,8 +847,7 @@ public static Set<Method> getOverrideHierarchy(final Method method, final Interf
      * @param annotationCls
      *            the {@link java.lang.annotation.Annotation} that must be present on a method to be matched
      * @return an array of Methods (possibly empty).
-     * @throws IllegalArgumentException
+     * @throws NullPointerException if the class or annotation are {@code null}
-     *            if the class or annotation are {@code null}
      * @since 3.4
      */
     public static Method[] getMethodsWithAnnotation(final Class<?> cls, final Class<? extends Annotation> annotationCls) {
@@ -881,8 +880,7 @@ public static List<Method> getMethodsListWithAnnotation(final Class<?> cls, fina
      * @param ignoreAccess
      *            determines if non public methods should be considered
      * @return an array of Methods (possibly empty).
-     * @throws IllegalArgumentException
+     * @throws NullPointerException if the class or annotation are {@code null}
-     *            if the class or annotation are {@code null}
      * @since 3.6
      */
     public static Method[] getMethodsWithAnnotation(final Class<?> cls, final Class<? extends Annotation> annotationCls,
@@ -903,8 +901,7 @@ public static Method[] getMethodsWithAnnotation(final Class<?> cls, final Class<
      * @param ignoreAccess
      *            determines if non public methods should be considered
      * @return a list of Methods (possibly empty).
-     * @throws IllegalArgumentException
+     * @throws NullPointerException if either the class or annotation class is {@code null}
-     *            if the class or annotation are {@code null}
      * @since 3.6
      */
     public static List<Method> getMethodsListWithAnnotation(final Class<?> cls,
@@ -912,7 +909,7 @@ public static List<Method> getMethodsListWithAnnotation(final Class<?> cls,
                                                             final boolean searchSupers, final boolean ignoreAccess) {
 
         Validate.notNull(cls, "The class must not be null");
-        Validate.isTrue(annotationCls != null, "The annotation class must not be null");
+        Validate.notNull(annotationCls, "The annotation class must not be null");
         final List<Class<?>> classes = (searchSupers ? getAllSuperclassesAndInterfaces(cls)
                 : new ArrayList<>());
         classes.add(0, cls);
@@ -947,15 +944,14 @@ public static List<Method> getMethodsListWithAnnotation(final Class<?> cls,
      * @param ignoreAccess
      *            determines if underlying method has to be accessible
      * @return the first matching annotation, or {@code null} if not found
-     * @throws IllegalArgumentException
+     * @throws NullPointerException if either the method or annotation class is {@code null}
-     *            if the method or annotation are {@code null}
      * @since 3.6
      */
     public static <A extends Annotation> A getAnnotation(final Method method, final Class<A> annotationCls,
                                                          final boolean searchSupers, final boolean ignoreAccess) {
 
         Validate.notNull(method, "The method must not be null");
-        Validate.isTrue(annotationCls != null, "The annotation class must not be null");
+        Validate.notNull(annotationCls, "The annotation class must not be null");
         if (!ignoreAccess && !MemberUtils.isAccessible(method)) {
             return null;
         }

src/main/java/org/apache/commons/lang3/time/DateUtils.java

@@ -509,7 +509,7 @@ public static Date addMilliseconds(final Date date, final int amount) {
      * @param calendarField  the calendar field to add to
      * @param amount  the amount to add, may be negative
      * @return the new {@code Date} with the amount added
-     * @throws IllegalArgumentException if the date is null
+     * @throws NullPointerException if the date is null
      */
     private static Date add(final Date date, final int calendarField, final int amount) {
         validateDateNotNull(date);
@@ -736,7 +736,7 @@ public static Date round(final Date date, final int field) {
      * @param date  the date to work with, not null
      * @param field  the field from {@code Calendar} or {@code SEMI_MONTH}
      * @return the different rounded date, not null
-     * @throws IllegalArgumentException if the date is {@code null}
+     * @throws NullPointerException if the date is {@code null}
      * @throws ArithmeticException if the year is over 280 million
      */
     public static Calendar round(final Calendar date, final int field) {
@@ -776,7 +776,7 @@ private static IllegalArgumentException nullDateIllegalArgumentException() {
      * @param date  the date to work with, either {@code Date} or {@code Calendar}, not null
      * @param field  the field from {@code Calendar} or {@code SEMI_MONTH}
      * @return the different rounded date, not null
-     * @throws IllegalArgumentException if the date is {@code null}
+     * @throws NullPointerException if the date is {@code null}
      * @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
      * @throws ArithmeticException if the year is over 280 million
      */
@@ -806,7 +806,7 @@ public static Date round(final Object date, final int field) {
      * @param date  the date to work with, not null
      * @param field  the field from {@code Calendar} or {@code SEMI_MONTH}
      * @return the different truncated date, not null
-     * @throws IllegalArgumentException if the date is {@code null}
+     * @throws NullPointerException if the date is {@code null}
      * @throws ArithmeticException if the year is over 280 million
      */
     public static Date truncate(final Date date, final int field) {
@@ -829,7 +829,7 @@ public static Date truncate(final Date date, final int field) {
      * @param date  the date to work with, not null
      * @param field  the field from {@code Calendar} or {@code SEMI_MONTH}
      * @return the different truncated date, not null
-     * @throws IllegalArgumentException if the date is {@code null}
+     * @throws NullPointerException if the date is {@code null}
      * @throws ArithmeticException if the year is over 280 million
      */
     public static Calendar truncate(final Calendar date, final int field) {
@@ -853,7 +853,7 @@ public static Calendar truncate(final Calendar date, final int field) {
      * @param date  the date to work with, either {@code Date} or {@code Calendar}, not null
      * @param field  the field from {@code Calendar} or {@code SEMI_MONTH}
      * @return the different truncated date, not null
-     * @throws IllegalArgumentException if the date is {@code null}
+     * @throws NullPointerException if the date is {@code null}
      * @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
      * @throws ArithmeticException if the year is over 280 million
      */
@@ -883,7 +883,7 @@ public static Date truncate(final Object date, final int field) {
      * @param date  the date to work with, not null
      * @param field  the field from {@code Calendar} or {@code SEMI_MONTH}
      * @return the different ceil date, not null
-     * @throws IllegalArgumentException if the date is {@code null}
+     * @throws NullPointerException if the date is {@code null}
      * @throws ArithmeticException if the year is over 280 million
      * @since 2.5
      */
@@ -907,7 +907,7 @@ public static Date ceiling(final Date date, final int field) {
      * @param date  the date to work with, not null
      * @param field  the field from {@code Calendar} or {@code SEMI_MONTH}
      * @return the different ceil date, not null
-     * @throws IllegalArgumentException if the date is {@code null}
+     * @throws NullPointerException if the date is {@code null}
      * @throws ArithmeticException if the year is over 280 million
      * @since 2.5
      */
@@ -932,7 +932,7 @@ public static Calendar ceiling(final Calendar date, final int field) {
      * @param date  the date to work with, either {@code Date} or {@code Calendar}, not null
      * @param field  the field from {@code Calendar} or {@code SEMI_MONTH}
      * @return the different ceil date, not null
-     * @throws IllegalArgumentException if the date is {@code null}
+     * @throws NullPointerException if the date is {@code null}
      * @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
      * @throws ArithmeticException if the year is over 280 million
      * @since 2.5
@@ -1121,7 +1121,7 @@ private static void modify(final Calendar val, final int field, final ModifyType
      * {@link DateUtils#RANGE_WEEK_RELATIVE},
      * {@link DateUtils#RANGE_WEEK_CENTER}
      * @return the date iterator, not null, not null
-     * @throws IllegalArgumentException if the date is {@code null}
+     * @throws NullPointerException if the date is {@code null}
      * @throws IllegalArgumentException if the rangeStyle is invalid
      */
     public static Iterator<Calendar> iterator(final Date focus, final int rangeStyle) {
@@ -1643,8 +1643,8 @@ public static long getFragmentInDays(final Calendar calendar, final int fragment
      * @param fragment the Calendar field part of date to calculate
      * @param unit the time unit
      * @return number of units within the fragment of the date
-     * @throws IllegalArgumentException if the date is {@code null} or
+     * @throws NullPointerException if the date is {@code null}
-     * fragment is not supported
+     * @throws IllegalArgumentException if fragment is not supported
      * @since 2.4
      */
     private static long getFragment(final Date date, final int fragment, final TimeUnit unit) {

src/main/java/org/apache/commons/lang3/time/FormatCache.java

@@ -65,8 +65,8 @@ public F getInstance() {
      * @param timeZone  the time zone, null means use the default TimeZone
      * @param locale  the locale, null means use the default Locale
      * @return a pattern based date/time formatter
+     * @throws NullPointerException if pattern is {@code null}
      * @throws IllegalArgumentException if pattern is invalid
-     *  or {@code null}
      */
     public F getInstance(final String pattern, TimeZone timeZone, Locale locale) {
         Validate.notNull(pattern, "pattern must not be null");

src/test/java/org/apache/commons/lang3/reflect/MethodUtilsTest.java

@@ -863,7 +863,7 @@ public void testGetAnnotationNotSearchSupersAndNotIgnoreAccess() throws NoSuchMe
 
     @Test
     public void testGetMethodsWithAnnotationIllegalArgumentException1() {
-        assertThrows(IllegalArgumentException.class, () -> MethodUtils.getMethodsWithAnnotation(FieldUtilsTest.class, null));
+        assertThrows(NullPointerException.class, () -> MethodUtils.getMethodsWithAnnotation(FieldUtilsTest.class, null));
     }
 
     @Test
@@ -891,7 +891,7 @@ public void testGetMethodsListWithAnnotation() throws NoSuchMethodException {
 
     @Test
     public void testGetMethodsListWithAnnotationIllegalArgumentException1() {
-        assertThrows(IllegalArgumentException.class, () -> MethodUtils.getMethodsListWithAnnotation(FieldUtilsTest.class, null));
+        assertThrows(NullPointerException.class, () -> MethodUtils.getMethodsListWithAnnotation(FieldUtilsTest.class, null));
     }
 
     @Test
@@ -906,7 +906,7 @@ public void testGetMethodsListWithAnnotationIllegalArgumentException3() {
 
     @Test
     public void testGetAnnotationIllegalArgumentException1() {
-        assertThrows(IllegalArgumentException.class,
+        assertThrows(NullPointerException.class,
                 () -> MethodUtils.getAnnotation(FieldUtilsTest.class.getDeclaredMethods()[0], null, true, true));
     }