This is an automated email from the ASF dual-hosted git repository.
ggregory pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-lang.git
commit ea344865514a8b75eb4e9d1a159fc8434e5bb7fa
Author: Gary Gregory <garydgreg...@gmail.com>
AuthorDate: Thu Feb 25 09:01:23 2021 -0500
Add and use ObjectUtils.requireNonEmpty().
This is a different implementation of the ideas and discussion in PR
#716.
---
src/changes/changes.xml | 1 +
.../org/apache/commons/lang3/BooleanUtils.java | 58 ++-------
.../java/org/apache/commons/lang3/ObjectUtils.java | 142 +++++++++++++++------
.../org/apache/commons/lang3/BooleanUtilsTest.java | 12 +-
.../org/apache/commons/lang3/ObjectUtilsTest.java | 15 ++-
5 files changed, 133 insertions(+), 95 deletions(-)
diff --git a/src/changes/changes.xml b/src/changes/changes.xml
index 5223d7f..dc029f5 100644
--- a/src/changes/changes.xml
+++ b/src/changes/changes.xml
@@ -96,6 +96,7 @@ The <action> type attribute can be add,update,fix,remove.
<action type="add" dev="ggregory" due-to="Gary
Gregory">Add DurationUtils.</action>
<action type="add" dev="jochen">Introduce the use of
@Nonnull, and @Nullable, and the Objects class as a helper tool.</action>
<action type="add" dev="ggregory" due-to="Arturo Bernal,
Gary Gregory">Add and use true and false String constants #714.</action>
+ <action type="add" dev="ggregory" due-to="Arturo Bernal,
Gary Gregory">Add and use ObjectUtils.requireNonEmpty() #716.</action>
<!-- UPDATE -->
<action type="update" dev="ggregory" due-to="Gary
Gregory">Enable Dependabot #587.</action>
<action type="update" dev="chtompki">Bump junit-jupiter
from 5.6.2 to 5.7.0.</action>
diff --git a/src/main/java/org/apache/commons/lang3/BooleanUtils.java
b/src/main/java/org/apache/commons/lang3/BooleanUtils.java
index f8b1e39..bc7234e 100644
--- a/src/main/java/org/apache/commons/lang3/BooleanUtils.java
+++ b/src/main/java/org/apache/commons/lang3/BooleanUtils.java
@@ -29,7 +29,6 @@ import org.apache.commons.lang3.math.NumberUtils;
* @since 2.0
*/
public class BooleanUtils {
-
/**
* The false String {@code "false"}.
*
@@ -86,18 +85,12 @@ public class BooleanUtils {
* @param array an array of {@code boolean}s
* @return the result of the logical 'and' operation. That is {@code false}
* if any of the parameters is {@code false} and {@code true} otherwise.
- * @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.0.1
*/
public static boolean and(final boolean... array) {
- // Validates input
- if (array == null) {
- throw new IllegalArgumentException("The Array must not be null");
- }
- if (array.length == 0) {
- throw new IllegalArgumentException("Array is empty");
- }
+ ObjectUtils.requireNonEmpty(array, "array");
for (final boolean element : array) {
if (!element) {
return false;
@@ -121,18 +114,13 @@ public class BooleanUtils {
* @param array an array of {@code Boolean}s
* @return the result of the logical 'and' operation. That is {@code false}
* if any of the parameters is {@code false} and {@code true} otherwise.
- * @throws IllegalArgumentException if {@code array} is {@code null}
+ * @throws NullPointerException if {@code array} is {@code null}
* @throws IllegalArgumentException if {@code array} is empty.
* @throws IllegalArgumentException if {@code array} contains a {@code
null}
* @since 3.0.1
*/
public static Boolean and(final Boolean... array) {
- if (array == null) {
- throw new IllegalArgumentException("The Array must not be null");
- }
- if (array.length == 0) {
- throw new IllegalArgumentException("Array is empty");
- }
+ ObjectUtils.requireNonEmpty(array, "array");
try {
final boolean[] primitive = ArrayUtils.toPrimitive(array);
return and(primitive) ? Boolean.TRUE : Boolean.FALSE;
@@ -262,7 +250,6 @@ public class BooleanUtils {
}
return bool.booleanValue() ? Boolean.FALSE : Boolean.TRUE;
}
-
/**
* <p>Performs an 'or' operation on a set of booleans.</p>
*
@@ -277,17 +264,12 @@ public class BooleanUtils {
*
* @param array an array of {@code boolean}s
* @return {@code true} if any of the arguments is {@code true}, and it
returns {@code false} otherwise.
- * @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.0.1
*/
public static boolean or(final boolean... array) {
- if (array == null) {
- throw new IllegalArgumentException("The Array must not be null");
- }
- if (array.length == 0) {
- throw new IllegalArgumentException("Array is empty");
- }
+ ObjectUtils.requireNonEmpty(array, "array");
for (final boolean element : array) {
if (element) {
return true;
@@ -311,18 +293,13 @@ public class BooleanUtils {
*
* @param array an array of {@code Boolean}s
* @return {@code true} if any of the arguments is {@code true}, and it
returns {@code false} otherwise.
- * @throws IllegalArgumentException if {@code array} is {@code null}
+ * @throws NullPointerException if {@code array} is {@code null}
* @throws IllegalArgumentException if {@code array} is empty.
* @throws IllegalArgumentException if {@code array} contains a {@code
null}
* @since 3.0.1
*/
public static Boolean or(final Boolean... array) {
- if (array == null) {
- throw new IllegalArgumentException("The Array must not be null");
- }
- if (array.length == 0) {
- throw new IllegalArgumentException("Array is empty");
- }
+ ObjectUtils.requireNonEmpty(array, "array");
try {
final boolean[] primitive = ArrayUtils.toPrimitive(array);
return or(primitive) ? Boolean.TRUE : Boolean.FALSE;
@@ -1109,17 +1086,11 @@ public class BooleanUtils {
*
* @param array an array of {@code boolean}s
* @return the result of the xor operations
- * @throws IllegalArgumentException if {@code array} is {@code null}
+ * @throws NullPointerException if {@code array} is {@code null}
* @throws IllegalArgumentException if {@code array} is empty.
*/
public static boolean xor(final boolean... array) {
- if (array == null) {
- throw new IllegalArgumentException("The Array must not be null");
- }
- if (array.length == 0) {
- throw new IllegalArgumentException("Array is empty");
- }
-
+ ObjectUtils.requireNonEmpty(array, "array");
// false if the neutral element of the xor operator
boolean result = false;
for (final boolean element : array) {
@@ -1141,17 +1112,12 @@ public class BooleanUtils {
*
* @param array an array of {@code Boolean}s
* @return the result of the xor operations
- * @throws IllegalArgumentException if {@code array} is {@code null}
+ * @throws NullPointerException if {@code array} is {@code null}
* @throws IllegalArgumentException if {@code array} is empty.
* @throws IllegalArgumentException if {@code array} contains a {@code
null}
*/
public static Boolean xor(final Boolean... array) {
- if (array == null) {
- throw new IllegalArgumentException("The Array must not be null");
- }
- if (array.length == 0) {
- throw new IllegalArgumentException("Array is empty");
- }
+ ObjectUtils.requireNonEmpty(array, "array");
try {
final boolean[] primitive = ArrayUtils.toPrimitive(array);
return xor(primitive) ? Boolean.TRUE : Boolean.FALSE;
diff --git a/src/main/java/org/apache/commons/lang3/ObjectUtils.java
b/src/main/java/org/apache/commons/lang3/ObjectUtils.java
index 3d4db58..f88c26b 100644
--- a/src/main/java/org/apache/commons/lang3/ObjectUtils.java
+++ b/src/main/java/org/apache/commons/lang3/ObjectUtils.java
@@ -27,6 +27,7 @@ import java.util.Collections;
import java.util.Comparator;
import java.util.HashMap;
import java.util.Map;
+import java.util.Objects;
import java.util.TreeSet;
import java.util.function.Supplier;
@@ -109,32 +110,6 @@ public class ObjectUtils {
public static final Null NULL = new Null();
/**
- * Checks if all values in the given array are {@code null}.
- *
- * <p>
- * If all the values are {@code null} or the array is {@code null}
- * or empty, then {@code true} is returned, otherwise {@code false} is
returned.
- * </p>
- *
- * <pre>
- * ObjectUtils.allNull(*) = false
- * ObjectUtils.allNull(*, null) = false
- * ObjectUtils.allNull(null, *) = false
- * ObjectUtils.allNull(null, null, *, *) = false
- * ObjectUtils.allNull(null) = true
- * ObjectUtils.allNull(null, null) = true
- * </pre>
- *
- * @param values the values to test, may be {@code null} or empty
- * @return {@code true} if all values in the array are {@code null}s,
- * {@code false} if there is at least one non-null value in the array.
- * @since 3.11
- */
- public static boolean allNull(final Object... values) {
- return !anyNotNull(values);
- }
-
- /**
* Checks if all values in the array are not {@code nulls}.
*
* <p>
@@ -174,31 +149,29 @@ public class ObjectUtils {
}
/**
- * Checks if any value in the given array is {@code null}.
+ * Checks if all values in the given array are {@code null}.
*
* <p>
- * If any of the values are {@code null} or the array is {@code null},
- * then {@code true} is returned, otherwise {@code false} is returned.
+ * If all the values are {@code null} or the array is {@code null}
+ * or empty, then {@code true} is returned, otherwise {@code false} is
returned.
* </p>
*
* <pre>
- * ObjectUtils.anyNull(*) = false
- * ObjectUtils.anyNull(*, *) = false
- * ObjectUtils.anyNull(null) = true
- * ObjectUtils.anyNull(null, null) = true
- * ObjectUtils.anyNull(null, *) = true
- * ObjectUtils.anyNull(*, null) = true
- * ObjectUtils.anyNull(*, *, null, *) = true
+ * ObjectUtils.allNull(*) = false
+ * ObjectUtils.allNull(*, null) = false
+ * ObjectUtils.allNull(null, *) = false
+ * ObjectUtils.allNull(null, null, *, *) = false
+ * ObjectUtils.allNull(null) = true
+ * ObjectUtils.allNull(null, null) = true
* </pre>
*
* @param values the values to test, may be {@code null} or empty
- * @return {@code true} if there is at least one {@code null} value in the
array,
- * {@code false} if all the values are non-null.
- * If the array is {@code null} or empty, {@code true} is also returned.
+ * @return {@code true} if all values in the array are {@code null}s,
+ * {@code false} if there is at least one non-null value in the array.
* @since 3.11
*/
- public static boolean anyNull(final Object... values) {
- return !allNotNull(values);
+ public static boolean allNull(final Object... values) {
+ return !anyNotNull(values);
}
/**
@@ -228,6 +201,34 @@ public class ObjectUtils {
return firstNonNull(values) != null;
}
+ /**
+ * Checks if any value in the given array is {@code null}.
+ *
+ * <p>
+ * If any of the values are {@code null} or the array is {@code null},
+ * then {@code true} is returned, otherwise {@code false} is returned.
+ * </p>
+ *
+ * <pre>
+ * ObjectUtils.anyNull(*) = false
+ * ObjectUtils.anyNull(*, *) = false
+ * ObjectUtils.anyNull(null) = true
+ * ObjectUtils.anyNull(null, null) = true
+ * ObjectUtils.anyNull(null, *) = true
+ * ObjectUtils.anyNull(*, null) = true
+ * ObjectUtils.anyNull(*, *, null, *) = true
+ * </pre>
+ *
+ * @param values the values to test, may be {@code null} or empty
+ * @return {@code true} if there is at least one {@code null} value in the
array,
+ * {@code false} if all the values are non-null.
+ * If the array is {@code null} or empty, {@code true} is also returned.
+ * @since 3.11
+ */
+ public static boolean anyNull(final Object... values) {
+ return !allNotNull(values);
+ }
+
// cloning
//-----------------------------------------------------------------------
/**
@@ -1184,6 +1185,64 @@ public class ObjectUtils {
return !equals(object1, object2);
}
+ /**
+ * Checks that the specified object reference is not {@code null} or empty
per {@link #isEmpty(Object)}. Use this
+ * method for validation, for example:
+ *
+ * <blockquote>
+ *
+ * <pre>
+ * public Foo(Bar bar) {
+ * this.bar = Objects.requireNonEmpty(bar);
+ * }
+ * </pre>
+ *
+ * </blockquote>
+ *
+ * @param <T> the type of the reference.
+ * @param obj the object reference to check for nullity.
+ * @return {@code obj} if not {@code null}.
+ * @throws NullPointerException if {@code obj} is {@code null}.
+ * @throws IllegalArgumentException if {@code obj} is empty per {@link
#isEmpty(Object)}.
+ * @see #isEmpty(Object)
+ * @since 3.12.0
+ */
+ public static <T> T requireNonEmpty(final T obj) {
+ return requireNonEmpty(obj, "object");
+ }
+
+ /**
+ * Checks that the specified object reference is not {@code null} or empty
per {@link #isEmpty(Object)}. Use this
+ * method for validation, for example:
+ *
+ * <blockquote>
+ *
+ * <pre>
+ * public Foo(Bar bar) {
+ * this.bar = Objects.requireNonEmpty(bar, "bar");
+ * }
+ * </pre>
+ *
+ * </blockquote>
+ *
+ * @param <T> the type of the reference.
+ * @param obj the object reference to check for nullity.
+ * @param message the exception message.
+ * @return {@code obj} if not {@code null}.
+ * @throws NullPointerException if {@code obj} is {@code null}.
+ * @throws IllegalArgumentException if {@code obj} is empty per {@link
#isEmpty(Object)}.
+ * @see #isEmpty(Object)
+ * @since 3.12.0
+ */
+ public static <T> T requireNonEmpty(final T obj, final String message) {
+ // check for null first to give the most precise exception.
+ Objects.requireNonNull(obj, message);
+ if (isEmpty(obj)) {
+ throw new IllegalArgumentException(message);
+ }
+ return obj;
+ }
+
// ToString
//-----------------------------------------------------------------------
/**
@@ -1210,7 +1269,6 @@ public class ObjectUtils {
public static String toString(final Object obj) {
return obj == null ? StringUtils.EMPTY : obj.toString();
}
-
/**
* <p>Gets the {@code toString} of an {@code Object} returning
* a specified text if {@code null} input.</p>
diff --git a/src/test/java/org/apache/commons/lang3/BooleanUtilsTest.java
b/src/test/java/org/apache/commons/lang3/BooleanUtilsTest.java
index f01bcfd..0865f94 100644
--- a/src/test/java/org/apache/commons/lang3/BooleanUtilsTest.java
+++ b/src/test/java/org/apache/commons/lang3/BooleanUtilsTest.java
@@ -441,7 +441,7 @@ public class BooleanUtilsTest {
@Test
public void testAnd_object_nullInput() {
- assertThrows(IllegalArgumentException.class, () ->
BooleanUtils.and((Boolean[]) null));
+ assertThrows(NullPointerException.class, () ->
BooleanUtils.and((Boolean[]) null));
}
@Test
@@ -553,7 +553,7 @@ public class BooleanUtilsTest {
@Test
public void testAnd_primitive_nullInput() {
- assertThrows(IllegalArgumentException.class, () ->
BooleanUtils.and((boolean[]) null));
+ assertThrows(NullPointerException.class, () ->
BooleanUtils.and((boolean[]) null));
}
@Test
@@ -640,7 +640,7 @@ public class BooleanUtilsTest {
@Test
public void testOr_object_nullInput() {
- assertThrows(IllegalArgumentException.class, () ->
BooleanUtils.or((Boolean[]) null));
+ assertThrows(NullPointerException.class, () ->
BooleanUtils.or((Boolean[]) null));
}
@Test
@@ -752,7 +752,7 @@ public class BooleanUtilsTest {
@Test
public void testOr_primitive_nullInput() {
- assertThrows(IllegalArgumentException.class, () ->
BooleanUtils.or((boolean[]) null));
+ assertThrows(NullPointerException.class, () ->
BooleanUtils.or((boolean[]) null));
}
@Test
@@ -822,7 +822,7 @@ public class BooleanUtilsTest {
@Test
public void testXor_object_nullInput() {
- assertThrows(IllegalArgumentException.class, () ->
BooleanUtils.xor((Boolean[]) null));
+ assertThrows(NullPointerException.class, () ->
BooleanUtils.xor((Boolean[]) null));
}
@Test
public void testXor_object_validInput_2items() {
@@ -940,7 +940,7 @@ public class BooleanUtilsTest {
@Test
public void testXor_primitive_nullInput() {
- assertThrows(IllegalArgumentException.class, () ->
BooleanUtils.xor((boolean[]) null));
+ assertThrows(NullPointerException.class, () ->
BooleanUtils.xor((boolean[]) null));
}
@Test
diff --git a/src/test/java/org/apache/commons/lang3/ObjectUtilsTest.java
b/src/test/java/org/apache/commons/lang3/ObjectUtilsTest.java
index b61ec8c..75abbb0 100644
--- a/src/test/java/org/apache/commons/lang3/ObjectUtilsTest.java
+++ b/src/test/java/org/apache/commons/lang3/ObjectUtilsTest.java
@@ -740,11 +740,24 @@ public class ObjectUtilsTest {
@Test
public void testPossibleCloneOfUncloneable() {
final UncloneableString string = new UncloneableString("apache");
- final CloneFailedException e =
assertThrows(CloneFailedException.class, () ->
ObjectUtils.cloneIfPossible(string));
+ final CloneFailedException e = assertThrows(CloneFailedException.class,
+ () -> ObjectUtils.cloneIfPossible(string));
assertEquals(NoSuchMethodException.class, e.getCause().getClass());
}
@Test
+ public void testRequireNonEmpty() {
+ assertEquals("foo", ObjectUtils.requireNonEmpty("foo"));
+ assertEquals("foo", ObjectUtils.requireNonEmpty("foo", "foo"));
+ //
+ assertThrows(NullPointerException.class, () ->
ObjectUtils.requireNonEmpty(null));
+ assertThrows(NullPointerException.class, () ->
ObjectUtils.requireNonEmpty(null, "foo"));
+ //
+ assertThrows(IllegalArgumentException.class, () ->
ObjectUtils.requireNonEmpty(""));
+ assertThrows(IllegalArgumentException.class, () ->
ObjectUtils.requireNonEmpty("", "foo"));
+ }
+
+ @Test
public void testToString_Object() {
assertEquals("", ObjectUtils.toString(null) );
assertEquals(Boolean.TRUE.toString(),
ObjectUtils.toString(Boolean.TRUE) );
