[LANG-1634] Add ObjectUtils #applyIfNonNull and #applyFirstNonNull

Utility methods that take a java.util.function.Consumer and possibly
null value(s). The consumer is invoked if the value is not null or with
the first non-null value, respectively.

Author: bindul

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

@@ -27,6 +27,7 @@
 import java.util.HashMap;
 import java.util.Map;
 import java.util.TreeSet;
+import java.util.function.Consumer;
 import java.util.function.Supplier;
 
 import org.apache.commons.lang3.exception.CloneFailedException;
@@ -226,6 +227,62 @@ public static boolean anyNotNull(final Object... values) {
         return firstNonNull(values) != null;
     }
 
+    /**
+     * <p>
+     * Invokes the given {@code consumer's} {@link Consumer#accept(Object)} with the first {@code non-null} value from
+     * {@code objects}. If all the values are null, the consumer is not invoked.
+     * </p>
+     *
+     * <p>
+     * The caller is responsible for thread-safety and exception handling of consumer.
+     * </p>
+     *
+     * <pre>
+     * ObjectUtils.applyIfNonNull(bean::setValue, null)                 - setValue not invoked
+     * ObjectUtils.applyIfNonNull(bean::setValue, null, "abc", "def")   - setValue invoked with "abc"
+     * ObjectUtils.applyIfNonNull(v -&gt; bean.setValue(v), "abc")      - setValue invoked with "abc"
+     * </pre>
+     *
+     * @param <T> the type of the object
+     * @param objects  the values to test, may be {@code null} or empty
+     * @param consumer the consumer operation to invoke with the first non-null {@code objects}.
+     * @see #firstNonNull(Object...)
+     * @see #applyIfNonNull(Consumer, Object)
+     * @since 3.12
+     */
+    @SafeVarargs
+    public static <T> void applyFirstNonNull(final Consumer<T> consumer, final T... objects) {
+        applyIfNonNull(consumer, firstNonNull(objects));
+    }
+
+    /**
+     * <p>
+     * Invokes the given {@code consumer's} {@link Consumer#accept(Object)} with the {@code object} if it is
+     * {@code non-null}, otherwise the consumer is not invoked.
+     * </p>
+     *
+     * <p>
+     * The caller is responsible for thread-safety and exception handling of consumer.
+     * </p>
+     *
+     * <pre>
+     * ObjectUtils.applyIfNonNull(bean::setValue, null)             - setValue not invoked
+     * ObjectUtils.applyIfNonNull(bean::setValue, "abc")            - setValue invoked with "abc"
+     * ObjectUtils.applyIfNonNull(v -&gt; bean.setValue(v), "abc")  - setValue invoked with "abc"
+     * </pre>
+     *
+     * @param <T> the type of the object
+     * @param object the {@code Object} to test, may be {@code null}
+     * @param consumer the consumer operation to invoke with {@code object} if it is {@code non-null}
+     * @see #applyFirstNonNull(Consumer, Object...)
+     * @since 3.12
+     */
+    public static <T> void applyIfNonNull(final Consumer<T> consumer, final T object) {
+        if (object != null) {
+            consumer.accept(object);
+        }
+    }
+
     // cloning
     //-----------------------------------------------------------------------
     /**

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

@@ -245,6 +245,33 @@ public void testEquals() {
         assertTrue(ObjectUtils.equals(FOO, FOO), "ObjectUtils.equals(\"foo\", \"foo\") returned false");
     }
 
+    @Test
+    public void testApplyIfNonNull() {
+        final ApplyIfNonNullBean bean = new ApplyIfNonNullBean();
+        bean.setValue(FOO);
+
+        ObjectUtils.applyIfNonNull(bean::setValue, null);
+        assertEquals(FOO, bean.getValue());
+
+        ObjectUtils.applyIfNonNull(bean::setValue, BAR);
+        assertEquals(BAR, bean.getValue());
+
+        ObjectUtils.applyIfNonNull(v -> bean.setValue(v), FOO);
+        assertEquals(FOO, bean.getValue());
+    }
+
+    @Test
+    public void testApplyFirstNonNull() {
+        final ApplyIfNonNullBean bean = new ApplyIfNonNullBean();
+        bean.setValue(FOO);
+
+        ObjectUtils.applyFirstNonNull(bean::setValue, null, null, null);
+        assertEquals(FOO, bean.getValue());
+
+        ObjectUtils.applyFirstNonNull(bean::setValue, null, null, BAR, FOO, null);
+        assertEquals(BAR, bean.getValue());
+    }
+
     @Test
     public void testNotEqual() {
         assertFalse(ObjectUtils.notEqual(null, null), "ObjectUtils.notEqual(null, null) returned false");
@@ -764,4 +791,13 @@ public int compare(final CharSequence o1, final CharSequence o2) {
 
     }
 
+    static final class ApplyIfNonNullBean {
+        private String value;
+        public String getValue() {
+            return value;
+        }
+        public void setValue(String value) {
+            this.value = value;
+        }
+    }
 }