Add ObjectUtils.getIfNull(Object, Object) and deprecate

defaultIfNull(Object, Object)

A adaptation of PR #1355 by Pankraz76

Author: garydgregory

src/changes/changes.xml

@@ -123,6 +123,7 @@ The <action> type attribute can be add,update,fix,remove.
     <action                   type="add" dev="ggregory" due-to="Gary Gregory">Add SystemProperties.JAVA_SECURITY_KERBEROS_KDC.</action>
     <action                   type="add" dev="ggregory" due-to="Gary Gregory">Add SystemProperties.JAVA_SECURITY_KERBEROS_REAL.</action>
     <action                   type="add" dev="ggregory" due-to="kommalapatiraviteja">Add ArrayFill.fill(boolean[], boolean) #1386.</action>
+    <action                   type="add" dev="ggregory" due-to="Pankraz76, Gary Gregory">Add ObjectUtils.getIfNull(Object, Object) and deprecate defaultIfNull(Object, Object).</action>
     <!-- UPDATE -->
     <action                   type="update" dev="ggregory" due-to="Gary Gregory, Dependabot">Bump org.apache.commons:commons-parent from 73 to 84 #1267, #1277, #1283, #1288, #1302, #1377.</action>
     <action                   type="update" dev="ggregory" due-to="Gary Gregory, Dependabot">[site] Bump org.codehaus.mojo:taglist-maven-plugin from 3.1.0 to 3.2.1 #1300.</action>

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

@@ -580,10 +580,13 @@ public static short CONST_SHORT(final int v) {
      * @param object  the {@link Object} to test, may be {@code null}
      * @param defaultValue  the default value to return, may be {@code null}
      * @return {@code object} if it is not {@code null}, defaultValue otherwise
-     * TODO Rename to getIfNull in 4.0
+     * @see #getIfNull(Object, Object)
+     * @see #getIfNull(Object, Supplier)
+     * @deprecated Use {@link #getIfNull(Object, Object)}.
      */
+    @Deprecated
     public static <T> T defaultIfNull(final T object, final T defaultValue) {
-        return object != null ? object : defaultValue;
+        return getIfNull(object, defaultValue);
     }
 
     // Null-safe equals/hashCode
@@ -703,12 +706,35 @@ public static <T> T getFirstNonNull(final Supplier<T>... suppliers) {
      * @param object the {@link Object} to test, may be {@code null}
      * @param defaultSupplier the default value to return, may be {@code null}
      * @return {@code object} if it is not {@code null}, {@code defaultValueSupplier.get()} otherwise
+     * @see #getIfNull(Object, Object)
      * @since 3.10
      */
     public static <T> T getIfNull(final T object, final Supplier<T> defaultSupplier) {
         return object != null ? object : Suppliers.get(defaultSupplier);
     }
 
+    /**
+     * Returns a default value if the object passed is {@code null}.
+     *
+     * <pre>
+     * ObjectUtils.getIfNull(null, null)      = null
+     * ObjectUtils.getIfNull(null, "")        = ""
+     * ObjectUtils.getIfNull(null, "zz")      = "zz"
+     * ObjectUtils.getIfNull("abc", *)        = "abc"
+     * ObjectUtils.getIfNull(Boolean.TRUE, *) = Boolean.TRUE
+     * </pre>
+     *
+     * @param <T> the type of the object
+     * @param object  the {@link Object} to test, may be {@code null}
+     * @param defaultValue  the default value to return, may be {@code null}
+     * @return {@code object} if it is not {@code null}, defaultValue otherwise
+     * @see #getIfNull(Object, Supplier)
+     * @since 3.18.0
+     */
+    public static <T> T getIfNull(final T object, final T defaultValue) {
+        return object != null ? object : defaultValue;
+    }
+
     /**
      * Gets the hash code of an object returning zero when the
      * object is {@code null}.

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

@@ -56,7 +56,7 @@ public abstract class Diff<T> extends Pair<T, T> {
      */
     protected Diff(final String fieldName) {
         this.fieldName = Objects.requireNonNull(fieldName);
-        this.type = ObjectUtils.defaultIfNull(TypeUtils.getTypeArguments(getClass(), Diff.class).get(Diff.class.getTypeParameters()[0]), Object.class);
+        this.type = ObjectUtils.getIfNull(TypeUtils.getTypeArguments(getClass(), Diff.class).get(Diff.class.getTypeParameters()[0]), Object.class);
     }
 
     Diff(final String fieldName, final Type type) {

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

@@ -235,8 +235,8 @@ private static final class WildcardTypeImpl implements WildcardType {
          * @param lowerBounds of this type
          */
         private WildcardTypeImpl(final Type[] upperBounds, final Type[] lowerBounds) {
-            this.upperBounds = ObjectUtils.defaultIfNull(upperBounds, ArrayUtils.EMPTY_TYPE_ARRAY);
-            this.lowerBounds = ObjectUtils.defaultIfNull(lowerBounds, ArrayUtils.EMPTY_TYPE_ARRAY);
+            this.upperBounds = ObjectUtils.getIfNull(upperBounds, ArrayUtils.EMPTY_TYPE_ARRAY);
+            this.lowerBounds = ObjectUtils.getIfNull(lowerBounds, ArrayUtils.EMPTY_TYPE_ARRAY);
         }
 
         /**

src/main/java/org/apache/commons/lang3/text/FormattableUtils.java

@@ -97,7 +97,7 @@ public static Formatter append(final CharSequence seq, final Formatter formatter
                 "Specified ellipsis '%1$s' exceeds precision of %2$s", ellipsis, Integer.valueOf(precision));
         final StringBuilder buf = new StringBuilder(seq);
         if (precision >= 0 && precision < seq.length()) {
-            final CharSequence actualEllipsis = ObjectUtils.defaultIfNull(ellipsis, StringUtils.EMPTY);
+            final CharSequence actualEllipsis = ObjectUtils.getIfNull(ellipsis, StringUtils.EMPTY);
             buf.replace(precision - actualEllipsis.length(), seq.length(), actualEllipsis.toString());
         }
         final boolean leftJustify = (flags & FormattableFlags.LEFT_JUSTIFY) == FormattableFlags.LEFT_JUSTIFY;

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

@@ -219,7 +219,7 @@ public static int toMillisInt(final Duration duration) {
      * @return The given duration or {@link Duration#ZERO}.
      */
     public static Duration zeroIfNull(final Duration duration) {
-        return ObjectUtils.defaultIfNull(duration, Duration.ZERO);
+        return ObjectUtils.getIfNull(duration, Duration.ZERO);
     }
 
     /**

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

@@ -503,6 +503,35 @@ public void testGetFirstNonNull() {
         assertEquals(Boolean.TRUE, ObjectUtils.getFirstNonNull(Suppliers.nul(), () -> Boolean.TRUE));
     }
 
+    @Test
+    public void testGetIfNullObject() {
+        final Object o = FOO;
+        final Object defaultObject = BAR;
+        assertNull(ObjectUtils.getIfNull(null, (Object) null));
+        assertSame(defaultObject, ObjectUtils.getIfNull(null, defaultObject), "dflt was not returned when o was null");
+        assertSame(o, ObjectUtils.getIfNull(o, defaultObject), "dflt was returned when o was not null");
+    }
+
+    @Test
+    public void testGetIfNullSupplier() {
+        final Object o = FOO;
+        final Object defaultObject = BAR;
+        assertNull(ObjectUtils.getIfNull(null, (Supplier<Object>) null));
+        assertSame(defaultObject, ObjectUtils.getIfNull(null, () -> defaultObject), "dflt was not returned when o was null");
+        assertSame(o, ObjectUtils.getIfNull(o, () -> defaultObject), "dflt was returned when o was not null");
+        assertSame(o, ObjectUtils.getIfNull(FOO, () -> defaultObject), "dflt was returned when o was not null");
+        assertSame(o, ObjectUtils.getIfNull("foo", () -> defaultObject), "dflt was returned when o was not null");
+        final MutableInt callsCounter = new MutableInt(0);
+        final Supplier<Object> countingDefaultSupplier = () -> {
+            callsCounter.increment();
+            return defaultObject;
+        };
+        ObjectUtils.getIfNull(o, countingDefaultSupplier);
+        assertEquals(0, callsCounter.getValue());
+        ObjectUtils.getIfNull(null, countingDefaultSupplier);
+        assertEquals(1, callsCounter.getValue());
+    }
+
     @Test
     public void testHashCode() {
         assertEquals(0, ObjectUtils.hashCode(null));

src/test/java/org/apache/commons/lang3/function/Objects.java

@@ -52,7 +52,7 @@
  *
  * This class is somewhat redundant with regards to {@link ObjectUtils}.
  * For example, {@link #requireNonNull(Object, Object)} is almost equivalent
- * with {@link ObjectUtils#defaultIfNull(Object, Object)}. However, it isn't
+ * with {@link ObjectUtils#getIfNull(Object, Object)}. However, it isn't
  * quite the same, because the latter can, in fact, return null. The former
  * can't, and the Java compiler confirms this.(An alternative to redundancy
  * would have been to change the {@code ObjectUtils} class. However, that