Apache
/
commons-lang
mirror of https://github.com/apache/commons-lang.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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.
This commit is contained in:
Isira Seneviratne 2020-07-10 01:26:19 +00:00 committed by GitHub
parent 031f4f61b7
commit 3700641b4e
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
11 changed files with 43 additions and 51 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
src/main/java/org/apache/commons/lang3/CharUtils.java
View File

@ -131,7 +131,7 @@ public class CharUtils {
*
* @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 class CharUtils {
*
* @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 class CharUtils {
*
* @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");

14
src/main/java/org/apache/commons/lang3/SerializationUtils.java
View File

@ -129,7 +129,7 @@ public class SerializationUtils {
*
* @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 class SerializationUtils {
* @param inputStream
* the serialized object input stream, must not be null
* @return the deserialized object
* @throws IllegalArgumentException
* if {@code inputStream} is {@code null}
* @throws SerializationException
* (runtime) if the serialization fails
* @throws NullPointerException if {@code inputStream} is {@code null}
* @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 class SerializationUtils {
* @param objectData
* the serialized object, must not be null
* @return the deserialized object
* @throws IllegalArgumentException
* if {@code objectData} is {@code null}
* @throws SerializationException
* (runtime) if the serialization fails
* @throws NullPointerException if {@code objectData} is {@code null}
* @throws SerializationException (runtime) if the serialization fails
*/
public static <T> T deserialize(final byte[] objectData) {
Validate.notNull(objectData, "The byte[] must not be null");

3
src/main/java/org/apache/commons/lang3/builder/DiffBuilder.java
View File

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

3
src/main/java/org/apache/commons/lang3/builder/DiffResult.java
View File

@ -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
* if {@code lhs}, {@code rhs} or {@code diffs} is {@code null}
* @throws NullPointerException 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) {

6
src/main/java/org/apache/commons/lang3/math/Fraction.java
View File

@ -308,7 +308,7 @@ public final class Fraction extends Number implements Comparable<Fraction> {
*
* @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 @@ public final class Fraction extends Number implements Comparable<Fraction> {
*
* @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 final class Fraction extends Number implements Comparable<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}

8
src/main/java/org/apache/commons/lang3/math/IEEE754rUtils.java
View File

@ -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 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(float[]) to min(float...)
*/
@ -144,7 +144,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 max(double[]) to max(double...)
*/
@ -166,7 +166,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 max(float[]) to max(float...)
*/

6
src/main/java/org/apache/commons/lang3/reflect/FieldUtils.java
View File

@ -81,9 +81,9 @@ public class FieldUtils {
* {@link java.lang.reflect.AccessibleObject#setAccessible(boolean)} method. {@code false} will only
* match {@code public} fields.
* @return the Field object
* @throws IllegalArgumentException
* if the class is {@code null}, or the field name is blank or empty or is matched at multiple places
* in the inheritance hierarchy
* @throws NullPointerException if the class is {@code null}
* @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) {
Validate.notNull(cls, "The class must not be null");

16
src/main/java/org/apache/commons/lang3/reflect/MethodUtils.java
View File

@ -847,8 +847,7 @@ public class MethodUtils {
* @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
* if the class or annotation are {@code null}
* @throws NullPointerException 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 class MethodUtils {
* @param ignoreAccess
* determines if non public methods should be considered
* @return an array of Methods (possibly empty).
* @throws IllegalArgumentException
* if the class or annotation are {@code null}
* @throws NullPointerException 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 class MethodUtils {
* @param ignoreAccess
* determines if non public methods should be considered
* @return a list of Methods (possibly empty).
* @throws IllegalArgumentException
* if the class or annotation are {@code null}
* @throws NullPointerException if either the class or annotation class is {@code null}
* @since 3.6
*/
public static List<Method> getMethodsListWithAnnotation(final Class<?> cls,
@ -912,7 +909,7 @@ public class MethodUtils {
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 class MethodUtils {
* @param ignoreAccess
* determines if underlying method has to be accessible
* @return the first matching annotation, or {@code null} if not found
* @throws IllegalArgumentException
* if the method or annotation are {@code null}
* @throws NullPointerException if either the method or annotation class is {@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;
}

24
src/main/java/org/apache/commons/lang3/time/DateUtils.java
View File

@ -509,7 +509,7 @@ public class DateUtils {
* @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 class DateUtils {
* @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 @@ public class DateUtils {
* @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 class DateUtils {
* @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 class DateUtils {
* @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 class DateUtils {
* @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 class DateUtils {
* @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 class DateUtils {
* @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 class DateUtils {
* @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 @@ public class DateUtils {
* {@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 class DateUtils {
* @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
* fragment is not supported
* @throws NullPointerException if the date is {@code null}
* @throws IllegalArgumentException if fragment is not supported
* @since 2.4
*/
private static long getFragment(final Date date, final int fragment, final TimeUnit unit) {

2
src/main/java/org/apache/commons/lang3/time/FormatCache.java
View File

@ -65,8 +65,8 @@ abstract class FormatCache<F extends Format> {
* @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");

6
src/test/java/org/apache/commons/lang3/reflect/MethodUtilsTest.java
View File

@ -863,7 +863,7 @@ public class MethodUtilsTest {
@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 class MethodUtilsTest {
@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 class MethodUtilsTest {
@Test
public void testGetAnnotationIllegalArgumentException1() {
assertThrows(IllegalArgumentException.class,
assertThrows(NullPointerException.class,
() -> MethodUtils.getAnnotation(FieldUtilsTest.class.getDeclaredMethods()[0], null, true, true));
}