move

Author: Vincent Potucek

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

@@ -640,6 +640,35 @@ public static <T> T firstNonNull(final T... values) {
         return Streams.of(values).filter(Objects::nonNull).findFirst().orElse(null);
     }
 
+    /**
+     * Returns the first value in the collection which is not {@code null}.
+     * If all the values are {@code null} or the collection is {@code null}
+     * or empty then {@code null} is returned.
+     *
+     * <pre>
+     * ObjectUtils.firstNonNull(null, null)      = null
+     * ObjectUtils.firstNonNull(null, "")        = ""
+     * ObjectUtils.firstNonNull(null, null, "")  = ""
+     * ObjectUtils.firstNonNull(null, "zz")      = "zz"
+     * ObjectUtils.firstNonNull("abc", *)        = "abc"
+     * ObjectUtils.firstNonNull(null, "xyz", *)  = "xyz"
+     * ObjectUtils.firstNonNull(Boolean.TRUE, *) = Boolean.TRUE
+     * ObjectUtils.firstNonNull()                = null
+     * </pre>
+     *
+     * @param <T> the component type of the collection
+     * @param values the collection to test, may be {@code null} or empty
+     * @return the first value from {@code values} which is not {@code null},
+     *  or {@code null} if there are no non-null values
+     * @since 3.0
+     */
+    public static <T> Optional<T> firstNonNull(final Collection<T> values) {
+        if (Objects.isNull(values) || values.isEmpty()) {
+            return Optional.empty();
+        }
+        return values.stream().filter(Objects::nonNull).findFirst();
+    }
+
     /**
      * Delegates to {@link Object#getClass()} using generics.
      *

src/test/java/org/apache/commons/lang3/ObjectUtilsTest.java

@@ -478,7 +478,7 @@ public void testEquals() {
     }
 
     @Test
-    public void testFirstNonNull() {
+    public void testFirstNonNullArray() {
         assertEquals("", ObjectUtils.firstNonNull(null, ""));
         final String firstNonNullGenerics = ObjectUtils.firstNonNull(null, null, "123", "456");
         assertEquals("123", firstNonNullGenerics);
@@ -495,6 +495,19 @@ public void testFirstNonNull() {
         assertNull(ObjectUtils.firstNonNull((Object[]) null));
     }
 
+    @Test
+    void testFirstNonNullCollection() {
+        assertEquals("123", ObjectUtils.firstNonNull(Arrays.asList(null, null, "123", "456")).get());
+        assertEquals("", ObjectUtils.firstNonNull(Collections.singletonList("")).get());
+        assertEquals("123", ObjectUtils.firstNonNull(Arrays.asList("123", null, "456", null)).get());
+        assertSame(Boolean.TRUE, ObjectUtils.firstNonNull(Collections.singletonList(Boolean.TRUE)).get());
+
+        // Ensure an empty collection returns empty optional
+        assertEquals(false, ObjectUtils.firstNonNull(Collections.emptyList()).isPresent());
+        // Ensure collection with only nulls returns empty optional
+        assertEquals(false, ObjectUtils.firstNonNull(Arrays.asList(null, null)).isPresent());
+    }
+
     @Test
     public void testGetClass() {
         final String[] newArray = ArrayUtils.EMPTY_STRING_ARRAY;