    001/*
    002 * Licensed to the Apache Software Foundation (ASF) under one or more
    003 * contributor license agreements.  See the NOTICE file distributed with
    004 * this work for additional information regarding copyright ownership.
    005 * The ASF licenses this file to You under the Apache License, Version 2.0
    006 * (the "License"); you may not use this file except in compliance with
    007 * the License.  You may obtain a copy of the License at
    008 *
    009 *      http://www.apache.org/licenses/LICENSE-2.0
    010 *
    011 * Unless required by applicable law or agreed to in writing, software
    012 * distributed under the License is distributed on an "AS IS" BASIS,
    013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    014 * See the License for the specific language governing permissions and
    015 * limitations under the License.
    016 */
    017package org.apache.commons.lang3;
    018
    019import java.io.IOException;
    020import java.io.Serializable;
    021import java.lang.reflect.Array;
    022import java.time.Duration;
    023import java.util.ArrayList;
    024import java.util.Collection;
    025import java.util.Collections;
    026import java.util.Comparator;
    027import java.util.HashMap;
    028import java.util.Hashtable;
    029import java.util.Map;
    030import java.util.Objects;
    031import java.util.Optional;
    032import java.util.TreeSet;
    033import java.util.function.Supplier;
    034import java.util.stream.Stream;
    035
    036import org.apache.commons.lang3.exception.CloneFailedException;
    037import org.apache.commons.lang3.function.Suppliers;
    038import org.apache.commons.lang3.mutable.MutableInt;
    039import org.apache.commons.lang3.stream.Streams;
    040import org.apache.commons.lang3.text.StrBuilder;
    041import org.apache.commons.lang3.time.DurationUtils;
    042
    043/**
    044 * Operations on {@link Object}.
    045 *
    046 * <p>This class tries to handle {@code null} input gracefully.
    047 * An exception will generally not be thrown for a {@code null} input.
    048 * Each method documents its behavior in more detail.</p>
    049 *
    050 * <p>#ThreadSafe#</p>
    051 * @since 1.0
    052 */
    053//@Immutable
    054@SuppressWarnings("deprecation") // deprecated class StrBuilder is imported
    055// because it is part of the signature of deprecated methods
    056public class ObjectUtils {
    057
    058    /**
    059     * Class used as a null placeholder where {@code null}
    060     * has another meaning.
    061     *
    062     * <p>For example, in a {@link HashMap} the
    063     * {@link java.util.HashMap#get(Object)} method returns
    064     * {@code null} if the {@link Map} contains {@code null} or if there is
    065     * no matching key. The {@code null} placeholder can be used to distinguish
    066     * between these two cases.</p>
    067     *
    068     * <p>Another example is {@link Hashtable}, where {@code null}
    069     * cannot be stored.</p>
    070     */
    071    public static class Null implements Serializable {
    072        /**
    073         * Required for serialization support. Declare serialization compatibility with Commons Lang 1.0
    074         *
    075         * @see java.io.Serializable
    076         */
    077        private static final long serialVersionUID = 7092611880189329093L;
    078
    079        /**
    080         * Restricted constructor - singleton.
    081         */
    082        Null() {
    083        }
    084
    085        /**
    086         * Ensure Singleton after serialization.
    087         *
    088         * @return the singleton value
    089         */
    090        private Object readResolve() {
    091            return NULL;
    092        }
    093    }
    094
    095    private static final char AT_SIGN = '@';
    096
    097    /**
    098     * Singleton used as a {@code null} placeholder where
    099     * {@code null} has another meaning.
    100     *
    101     * <p>For example, in a {@link HashMap} the
    102     * {@link java.util.HashMap#get(Object)} method returns
    103     * {@code null} if the {@link Map} contains {@code null} or if there
    104     * is no matching key. The {@code null} placeholder can be used to
    105     * distinguish between these two cases.</p>
    106     *
    107     * <p>Another example is {@link Hashtable}, where {@code null}
    108     * cannot be stored.</p>
    109     *
    110     * <p>This instance is Serializable.</p>
    111     */
    112    public static final Null NULL = new Null();
    113
    114    /**
    115     * Tests if all values in the array are not {@code nulls}.
    116     *
    117     * <p>
    118     * If any value is {@code null} or the array is {@code null} then
    119     * {@code false} is returned. If all elements in array are not
    120     * {@code null} or the array is empty (contains no elements) {@code true}
    121     * is returned.
    122     * </p>
    123     *
    124     * <pre>
    125     * ObjectUtils.allNotNull(*)             = true
    126     * ObjectUtils.allNotNull(*, *)          = true
    127     * ObjectUtils.allNotNull(null)          = false
    128     * ObjectUtils.allNotNull(null, null)    = false
    129     * ObjectUtils.allNotNull(null, *)       = false
    130     * ObjectUtils.allNotNull(*, null)       = false
    131     * ObjectUtils.allNotNull(*, *, null, *) = false
    132     * </pre>
    133     *
    134     * @param values  the values to test, may be {@code null} or empty
    135     * @return {@code false} if there is at least one {@code null} value in the array or the array is {@code null},
    136     * {@code true} if all values in the array are not {@code null}s or array contains no elements.
    137     * @since 3.5
    138     */
    139    public static boolean allNotNull(final Object... values) {
    140        return values != null && Stream.of(values).noneMatch(Objects::isNull);
    141    }
    142
    143    /**
    144     * Tests if all values in the given array are {@code null}.
    145     *
    146     * <p>
    147     * If all the values are {@code null} or the array is {@code null}
    148     * or empty, then {@code true} is returned, otherwise {@code false} is returned.
    149     * </p>
    150     *
    151     * <pre>
    152     * ObjectUtils.allNull(*)                = false
    153     * ObjectUtils.allNull(*, null)          = false
    154     * ObjectUtils.allNull(null, *)          = false
    155     * ObjectUtils.allNull(null, null, *, *) = false
    156     * ObjectUtils.allNull(null)             = true
    157     * ObjectUtils.allNull(null, null)       = true
    158     * </pre>
    159     *
    160     * @param values  the values to test, may be {@code null} or empty
    161     * @return {@code true} if all values in the array are {@code null}s,
    162     * {@code false} if there is at least one non-null value in the array.
    163     * @since 3.11
    164     */
    165    public static boolean allNull(final Object... values) {
    166        return !anyNotNull(values);
    167    }
    168
    169    /**
    170     * Tests if any value in the given array is not {@code null}.
    171     *
    172     * <p>
    173     * If all the values are {@code null} or the array is {@code null}
    174     * or empty then {@code false} is returned. Otherwise {@code true} is returned.
    175     * </p>
    176     *
    177     * <pre>
    178     * ObjectUtils.anyNotNull(*)                = true
    179     * ObjectUtils.anyNotNull(*, null)          = true
    180     * ObjectUtils.anyNotNull(null, *)          = true
    181     * ObjectUtils.anyNotNull(null, null, *, *) = true
    182     * ObjectUtils.anyNotNull(null)             = false
    183     * ObjectUtils.anyNotNull(null, null)       = false
    184     * </pre>
    185     *
    186     * @param values  the values to test, may be {@code null} or empty
    187     * @return {@code true} if there is at least one non-null value in the array,
    188     * {@code false} if all values in the array are {@code null}s.
    189     * If the array is {@code null} or empty {@code false} is also returned.
    190     * @since 3.5
    191     */
    192    public static boolean anyNotNull(final Object... values) {
    193        return firstNonNull(values) != null;
    194    }
    195
    196    /**
    197     * Tests if any value in the given array is {@code null}.
    198     *
    199     * <p>
    200     * If any of the values are {@code null} or the array is {@code null},
    201     * then {@code true} is returned, otherwise {@code false} is returned.
    202     * </p>
    203     *
    204     * <pre>
    205     * ObjectUtils.anyNull(*)             = false
    206     * ObjectUtils.anyNull(*, *)          = false
    207     * ObjectUtils.anyNull(null)          = true
    208     * ObjectUtils.anyNull(null, null)    = true
    209     * ObjectUtils.anyNull(null, *)       = true
    210     * ObjectUtils.anyNull(*, null)       = true
    211     * ObjectUtils.anyNull(*, *, null, *) = true
    212     * </pre>
    213     *
    214     * @param values  the values to test, may be {@code null} or empty
    215     * @return {@code true} if there is at least one {@code null} value in the array,
    216     * {@code false} if all the values are non-null.
    217     * If the array is {@code null} or empty, {@code true} is also returned.
    218     * @since 3.11
    219     */
    220    public static boolean anyNull(final Object... values) {
    221        return !allNotNull(values);
    222    }
    223
    224    /**
    225     * Clones an object.
    226     *
    227     * @param <T> the type of the object
    228     * @param obj  the object to clone, null returns null
    229     * @return the clone if the object implements {@link Cloneable} otherwise {@code null}
    230     * @throws CloneFailedException if the object is cloneable and the clone operation fails
    231     * @since 3.0
    232     */
    233    public static <T> T clone(final T obj) {
    234        if (obj instanceof Cloneable) {
    235            final Object result;
    236            final Class<? extends Object> objClass = obj.getClass();
    237            if (isArray(obj)) {
    238                final Class<?> componentType = objClass.getComponentType();
    239                if (componentType.isPrimitive()) {
    240                    int length = Array.getLength(obj);
    241                    result = Array.newInstance(componentType, length);
    242                    while (length-- > 0) {
    243                        Array.set(result, length, Array.get(obj, length));
    244                    }
    245                } else {
    246                    result = ((Object[]) obj).clone();
    247                }
    248            } else {
    249                try {
    250                    result = objClass.getMethod("clone").invoke(obj);
    251                } catch (final ReflectiveOperationException e) {
    252                    throw new CloneFailedException("Exception cloning Cloneable type " + objClass.getName(), e);
    253                }
    254            }
    255            return (T) result;
    256        }
    257
    258        return null;
    259    }
    260
    261    /**
    262     * Clones an object if possible.
    263     *
    264     * <p>This method is similar to {@link #clone(Object)}, but will return the provided
    265     * instance as the return value instead of {@code null} if the instance
    266     * is not cloneable. This is more convenient if the caller uses different
    267     * implementations (e.g. of a service) and some of the implementations do not allow concurrent
    268     * processing or have state. In such cases the implementation can simply provide a proper
    269     * clone implementation and the caller's code does not have to change.</p>
    270     *
    271     * @param <T> the type of the object
    272     * @param obj  the object to clone, null returns null
    273     * @return the clone if the object implements {@link Cloneable} otherwise the object itself
    274     * @throws CloneFailedException if the object is cloneable and the clone operation fails
    275     * @since 3.0
    276     */
    277    public static <T> T cloneIfPossible(final T obj) {
    278        final T clone = clone(obj);
    279        return clone == null ? obj : clone;
    280    }
    281
    282    /**
    283     * Null safe comparison of Comparables.
    284     * {@code null} is assumed to be less than a non-{@code null} value.
    285     * <p>TODO Move to ComparableUtils.</p>
    286     *
    287     * @param <T> type of the values processed by this method
    288     * @param c1  the first comparable, may be null
    289     * @param c2  the second comparable, may be null
    290     * @return a negative value if c1 &lt; c2, zero if c1 = c2
    291     *  and a positive value if c1 &gt; c2
    292     */
    293    public static <T extends Comparable<? super T>> int compare(final T c1, final T c2) {
    294        return compare(c1, c2, false);
    295    }
    296
    297    /**
    298     * Null safe comparison of Comparables.
    299     * <p>TODO Move to ComparableUtils.</p>
    300     *
    301     * @param <T> type of the values processed by this method
    302     * @param c1  the first comparable, may be null
    303     * @param c2  the second comparable, may be null
    304     * @param nullGreater if true {@code null} is considered greater
    305     *  than a non-{@code null} value or if false {@code null} is
    306     *  considered less than a Non-{@code null} value
    307     * @return a negative value if c1 &lt; c2, zero if c1 = c2
    308     *  and a positive value if c1 &gt; c2
    309     * @see java.util.Comparator#compare(Object, Object)
    310     */
    311    public static <T extends Comparable<? super T>> int compare(final T c1, final T c2, final boolean nullGreater) {
    312        if (c1 == c2) {
    313            return 0;
    314        }
    315        if (c1 == null) {
    316            return nullGreater ? 1 : -1;
    317        }
    318        if (c2 == null) {
    319            return nullGreater ? -1 : 1;
    320        }
    321        return c1.compareTo(c2);
    322    }
    323
    324    /**
    325     * Returns the provided value unchanged.
    326     * This can prevent javac from inlining a constant
    327     * field, e.g.,
    328     *
    329     * <pre>
    330     *     public final static boolean MAGIC_FLAG = ObjectUtils.CONST(true);
    331     * </pre>
    332     *
    333     * This way any jars that refer to this field do not
    334     * have to recompile themselves if the field's value
    335     * changes at some future date.
    336     *
    337     * @param v the boolean value to return
    338     * @return the boolean v, unchanged
    339     * @since 3.2
    340     */
    341    public static boolean CONST(final boolean v) {
    342        return v;
    343    }
    344
    345    /**
    346     * Returns the provided value unchanged.
    347     * This can prevent javac from inlining a constant
    348     * field, e.g.,
    349     *
    350     * <pre>
    351     *     public final static byte MAGIC_BYTE = ObjectUtils.CONST((byte) 127);
    352     * </pre>
    353     *
    354     * This way any jars that refer to this field do not
    355     * have to recompile themselves if the field's value
    356     * changes at some future date.
    357     *
    358     * @param v the byte value to return
    359     * @return the byte v, unchanged
    360     * @since 3.2
    361     */
    362    public static byte CONST(final byte v) {
    363        return v;
    364    }
    365
    366    /**
    367     * Returns the provided value unchanged.
    368     * This can prevent javac from inlining a constant
    369     * field, e.g.,
    370     *
    371     * <pre>
    372     *     public final static char MAGIC_CHAR = ObjectUtils.CONST('a');
    373     * </pre>
    374     *
    375     * This way any jars that refer to this field do not
    376     * have to recompile themselves if the field's value
    377     * changes at some future date.
    378     *
    379     * @param v the char value to return
    380     * @return the char v, unchanged
    381     * @since 3.2
    382     */
    383    public static char CONST(final char v) {
    384        return v;
    385    }
    386
    387    /**
    388     * Returns the provided value unchanged.
    389     * This can prevent javac from inlining a constant
    390     * field, e.g.,
    391     *
    392     * <pre>
    393     *     public final static double MAGIC_DOUBLE = ObjectUtils.CONST(1.0);
    394     * </pre>
    395     *
    396     * This way any jars that refer to this field do not
    397     * have to recompile themselves if the field's value
    398     * changes at some future date.
    399     *
    400     * @param v the double value to return
    401     * @return the double v, unchanged
    402     * @since 3.2
    403     */
    404    public static double CONST(final double v) {
    405        return v;
    406    }
    407
    408    /**
    409     * Returns the provided value unchanged.
    410     * This can prevent javac from inlining a constant
    411     * field, e.g.,
    412     *
    413     * <pre>
    414     *     public final static float MAGIC_FLOAT = ObjectUtils.CONST(1.0f);
    415     * </pre>
    416     *
    417     * This way any jars that refer to this field do not
    418     * have to recompile themselves if the field's value
    419     * changes at some future date.
    420     *
    421     * @param v the float value to return
    422     * @return the float v, unchanged
    423     * @since 3.2
    424     */
    425    public static float CONST(final float v) {
    426        return v;
    427    }
    428
    429    /**
    430     * Returns the provided value unchanged.
    431     * This can prevent javac from inlining a constant
    432     * field, e.g.,
    433     *
    434     * <pre>
    435     *     public final static int MAGIC_INT = ObjectUtils.CONST(123);
    436     * </pre>
    437     *
    438     * This way any jars that refer to this field do not
    439     * have to recompile themselves if the field's value
    440     * changes at some future date.
    441     *
    442     * @param v the int value to return
    443     * @return the int v, unchanged
    444     * @since 3.2
    445     */
    446    public static int CONST(final int v) {
    447        return v;
    448    }
    449
    450    /**
    451     * Returns the provided value unchanged.
    452     * This can prevent javac from inlining a constant
    453     * field, e.g.,
    454     *
    455     * <pre>
    456     *     public final static long MAGIC_LONG = ObjectUtils.CONST(123L);
    457     * </pre>
    458     *
    459     * This way any jars that refer to this field do not
    460     * have to recompile themselves if the field's value
    461     * changes at some future date.
    462     *
    463     * @param v the long value to return
    464     * @return the long v, unchanged
    465     * @since 3.2
    466     */
    467    public static long CONST(final long v) {
    468        return v;
    469    }
    470
    471    /**
    472     * Returns the provided value unchanged.
    473     * This can prevent javac from inlining a constant
    474     * field, e.g.,
    475     *
    476     * <pre>
    477     *     public final static short MAGIC_SHORT = ObjectUtils.CONST((short) 123);
    478     * </pre>
    479     *
    480     * This way any jars that refer to this field do not
    481     * have to recompile themselves if the field's value
    482     * changes at some future date.
    483     *
    484     * @param v the short value to return
    485     * @return the short v, unchanged
    486     * @since 3.2
    487     */
    488    public static short CONST(final short v) {
    489        return v;
    490    }
    491
    492    /**
    493     * Returns the provided value unchanged.
    494     * This can prevent javac from inlining a constant
    495     * field, e.g.,
    496     *
    497     * <pre>
    498     *     public final static String MAGIC_STRING = ObjectUtils.CONST("abc");
    499     * </pre>
    500     *
    501     * This way any jars that refer to this field do not
    502     * have to recompile themselves if the field's value
    503     * changes at some future date.
    504     *
    505     * @param <T> the Object type
    506     * @param v the genericized Object value to return (typically a String).
    507     * @return the genericized Object v, unchanged (typically a String).
    508     * @since 3.2
    509     */
    510    public static <T> T CONST(final T v) {
    511        return v;
    512    }
    513
    514    /**
    515     * Returns the provided value unchanged.
    516     * This can prevent javac from inlining a constant
    517     * field, e.g.,
    518     *
    519     * <pre>
    520     *     public final static byte MAGIC_BYTE = ObjectUtils.CONST_BYTE(127);
    521     * </pre>
    522     *
    523     * This way any jars that refer to this field do not
    524     * have to recompile themselves if the field's value
    525     * changes at some future date.
    526     *
    527     * @param v the byte literal (as an int) value to return
    528     * @throws IllegalArgumentException if the value passed to v
    529     *         is larger than a byte, that is, smaller than -128 or
    530     *         larger than 127.
    531     * @return the byte v, unchanged
    532     * @since 3.2
    533     */
    534    public static byte CONST_BYTE(final int v) {
    535        if (v < Byte.MIN_VALUE || v > Byte.MAX_VALUE) {
    536            throw new IllegalArgumentException("Supplied value must be a valid byte literal between -128 and 127: [" + v + "]");
    537        }
    538        return (byte) v;
    539    }
    540
    541    /**
    542     * Returns the provided value unchanged.
    543     * This can prevent javac from inlining a constant
    544     * field, e.g.,
    545     *
    546     * <pre>
    547     *     public final static short MAGIC_SHORT = ObjectUtils.CONST_SHORT(127);
    548     * </pre>
    549     *
    550     * This way any jars that refer to this field do not
    551     * have to recompile themselves if the field's value
    552     * changes at some future date.
    553     *
    554     * @param v the short literal (as an int) value to return
    555     * @throws IllegalArgumentException if the value passed to v
    556     *         is larger than a short, that is, smaller than -32768 or
    557     *         larger than 32767.
    558     * @return the byte v, unchanged
    559     * @since 3.2
    560     */
    561    public static short CONST_SHORT(final int v) {
    562        if (v < Short.MIN_VALUE || v > Short.MAX_VALUE) {
    563            throw new IllegalArgumentException("Supplied value must be a valid byte literal between -32768 and 32767: [" + v + "]");
    564        }
    565        return (short) v;
    566    }
    567
    568    /**
    569     * Returns a default value if the object passed is {@code null}.
    570     *
    571     * <pre>
    572     * ObjectUtils.defaultIfNull(null, null)      = null
    573     * ObjectUtils.defaultIfNull(null, "")        = ""
    574     * ObjectUtils.defaultIfNull(null, "zz")      = "zz"
    575     * ObjectUtils.defaultIfNull("abc", *)        = "abc"
    576     * ObjectUtils.defaultIfNull(Boolean.TRUE, *) = Boolean.TRUE
    577     * </pre>
    578     *
    579     * @param <T> the type of the object
    580     * @param object  the {@link Object} to test, may be {@code null}
    581     * @param defaultValue  the default value to return, may be {@code null}
    582     * @return {@code object} if it is not {@code null}, defaultValue otherwise
    583     * TODO Rename to getIfNull in 4.0
    584     */
    585    public static <T> T defaultIfNull(final T object, final T defaultValue) {
    586        return object != null ? object : defaultValue;
    587    }
    588
    589    // Null-safe equals/hashCode
    590    /**
    591     * Compares two objects for equality, where either one or both
    592     * objects may be {@code null}.
    593     *
    594     * <pre>
    595     * ObjectUtils.equals(null, null)                  = true
    596     * ObjectUtils.equals(null, "")                    = false
    597     * ObjectUtils.equals("", null)                    = false
    598     * ObjectUtils.equals("", "")                      = true
    599     * ObjectUtils.equals(Boolean.TRUE, null)          = false
    600     * ObjectUtils.equals(Boolean.TRUE, "true")        = false
    601     * ObjectUtils.equals(Boolean.TRUE, Boolean.TRUE)  = true
    602     * ObjectUtils.equals(Boolean.TRUE, Boolean.FALSE) = false
    603     * </pre>
    604     *
    605     * @param object1  the first object, may be {@code null}
    606     * @param object2  the second object, may be {@code null}
    607     * @return {@code true} if the values of both objects are the same
    608     * @deprecated this method has been replaced by {@code java.util.Objects.equals(Object, Object)} in Java 7 and will
    609     * be removed from future releases.
    610     */
    611    @Deprecated
    612    public static boolean equals(final Object object1, final Object object2) {
    613        return Objects.equals(object1, object2);
    614    }
    615
    616    /**
    617     * Returns the first value in the array which is not {@code null}.
    618     * If all the values are {@code null} or the array is {@code null}
    619     * or empty then {@code null} is returned.
    620     *
    621     * <pre>
    622     * ObjectUtils.firstNonNull(null, null)      = null
    623     * ObjectUtils.firstNonNull(null, "")        = ""
    624     * ObjectUtils.firstNonNull(null, null, "")  = ""
    625     * ObjectUtils.firstNonNull(null, "zz")      = "zz"
    626     * ObjectUtils.firstNonNull("abc", *)        = "abc"
    627     * ObjectUtils.firstNonNull(null, "xyz", *)  = "xyz"
    628     * ObjectUtils.firstNonNull(Boolean.TRUE, *) = Boolean.TRUE
    629     * ObjectUtils.firstNonNull()                = null
    630     * </pre>
    631     *
    632     * @param <T> the component type of the array
    633     * @param values  the values to test, may be {@code null} or empty
    634     * @return the first value from {@code values} which is not {@code null},
    635     *  or {@code null} if there are no non-null values
    636     * @since 3.0
    637     */
    638    @SafeVarargs
    639    public static <T> T firstNonNull(final T... values) {
    640        return Streams.of(values).filter(Objects::nonNull).findFirst().orElse(null);
    641    }
    642
    643    /**
    644     * Delegates to {@link Object#getClass()} using generics.
    645     *
    646     * @param <T> The argument type or null.
    647     * @param object The argument.
    648     * @return The argument's Class or null.
    649     * @since 3.13.0
    650     */
    651    @SuppressWarnings("unchecked")
    652    public static <T> Class<T> getClass(final T object) {
    653        return object == null ? null : (Class<T>) object.getClass();
    654    }
    655
    656    /**
    657     * Executes the given suppliers in order and returns the first return
    658     * value where a value other than {@code null} is returned.
    659     * Once a non-{@code null} value is obtained, all following suppliers are
    660     * not executed anymore.
    661     * If all the return values are {@code null} or no suppliers are provided
    662     * then {@code null} is returned.
    663     *
    664     * <pre>
    665     * ObjectUtils.firstNonNullLazy(null, () -&gt; null) = null
    666     * ObjectUtils.firstNonNullLazy(() -&gt; null, () -&gt; "") = ""
    667     * ObjectUtils.firstNonNullLazy(() -&gt; "", () -&gt; throw new IllegalStateException()) = ""
    668     * ObjectUtils.firstNonNullLazy(() -&gt; null, () -&gt; "zz) = "zz"
    669     * ObjectUtils.firstNonNullLazy() = null
    670     * </pre>
    671     *
    672     * @param <T> the type of the return values
    673     * @param suppliers  the suppliers returning the values to test.
    674     *                   {@code null} values are ignored.
    675     *                   Suppliers may return {@code null} or a value of type {@code T}
    676     * @return the first return value from {@code suppliers} which is not {@code null},
    677     *  or {@code null} if there are no non-null values
    678     * @since 3.10
    679     */
    680    @SafeVarargs
    681    public static <T> T getFirstNonNull(final Supplier<T>... suppliers) {
    682        return Streams.of(suppliers).filter(Objects::nonNull).map(Supplier::get).filter(Objects::nonNull).findFirst().orElse(null);
    683    }
    684
    685    /**
    686     * Returns the given {@code object} is it is non-null, otherwise returns the Supplier's {@link Supplier#get()}
    687     * value.
    688     *
    689     * <p>
    690     * The caller responsible for thread-safety and exception handling of default value supplier.
    691     * </p>
    692     *
    693     * <pre>
    694     * ObjectUtils.getIfNull(null, () -&gt; null)     = null
    695     * ObjectUtils.getIfNull(null, null)              = null
    696     * ObjectUtils.getIfNull(null, () -&gt; "")       = ""
    697     * ObjectUtils.getIfNull(null, () -&gt; "zz")     = "zz"
    698     * ObjectUtils.getIfNull("abc", *)                = "abc"
    699     * ObjectUtils.getIfNull(Boolean.TRUE, *)         = Boolean.TRUE
    700     * </pre>
    701     *
    702     * @param <T> the type of the object
    703     * @param object the {@link Object} to test, may be {@code null}
    704     * @param defaultSupplier the default value to return, may be {@code null}
    705     * @return {@code object} if it is not {@code null}, {@code defaultValueSupplier.get()} otherwise
    706     * @since 3.10
    707     */
    708    public static <T> T getIfNull(final T object, final Supplier<T> defaultSupplier) {
    709        return object != null ? object : Suppliers.get(defaultSupplier);
    710    }
    711
    712    /**
    713     * Gets the hash code of an object returning zero when the
    714     * object is {@code null}.
    715     *
    716     * <pre>
    717     * ObjectUtils.hashCode(null)   = 0
    718     * ObjectUtils.hashCode(obj)    = obj.hashCode()
    719     * </pre>
    720     *
    721     * @param obj  the object to obtain the hash code of, may be {@code null}
    722     * @return the hash code of the object, or zero if null
    723     * @since 2.1
    724     * @deprecated this method has been replaced by {@code java.util.Objects.hashCode(Object)} in Java 7 and will be
    725     * removed in future releases
    726     */
    727    @Deprecated
    728    public static int hashCode(final Object obj) {
    729        // hashCode(Object) for performance vs. hashCodeMulti(Object[]), as hash code is often critical
    730        return Objects.hashCode(obj);
    731    }
    732
    733    /**
    734     * Returns the hexadecimal hash code for the given object per {@link Objects#hashCode(Object)}.
    735     * <p>
    736     * Short hand for {@code Integer.toHexString(Objects.hashCode(object))}.
    737     * </p>
    738     *
    739     * @param object object for which the hashCode is to be calculated
    740     * @return Hash code in hexadecimal format.
    741     * @since 3.13.0
    742     */
    743    public static String hashCodeHex(final Object object) {
    744        return Integer.toHexString(Objects.hashCode(object));
    745    }
    746
    747    /**
    748     * Gets the hash code for multiple objects.
    749     *
    750     * <p>This allows a hash code to be rapidly calculated for a number of objects.
    751     * The hash code for a single object is the <em>not</em> same as {@link #hashCode(Object)}.
    752     * The hash code for multiple objects is the same as that calculated by an
    753     * {@link ArrayList} containing the specified objects.</p>
    754     *
    755     * <pre>
    756     * ObjectUtils.hashCodeMulti()                 = 1
    757     * ObjectUtils.hashCodeMulti((Object[]) null)  = 1
    758     * ObjectUtils.hashCodeMulti(a)                = 31 + a.hashCode()
    759     * ObjectUtils.hashCodeMulti(a,b)              = (31 + a.hashCode()) * 31 + b.hashCode()
    760     * ObjectUtils.hashCodeMulti(a,b,c)            = ((31 + a.hashCode()) * 31 + b.hashCode()) * 31 + c.hashCode()
    761     * </pre>
    762     *
    763     * @param objects  the objects to obtain the hash code of, may be {@code null}
    764     * @return the hash code of the objects, or zero if null
    765     * @since 3.0
    766     * @deprecated this method has been replaced by {@code java.util.Objects.hash(Object...)} in Java 7 and will be
    767     * removed in future releases.
    768     */
    769    @Deprecated
    770    public static int hashCodeMulti(final Object... objects) {
    771        int hash = 1;
    772        if (objects != null) {
    773            for (final Object object : objects) {
    774                final int tmpHash = Objects.hashCode(object);
    775                hash = hash * 31 + tmpHash;
    776            }
    777        }
    778        return hash;
    779    }
    780
    781    /**
    782     * Returns the hexadecimal hash code for the given object per {@link System#identityHashCode(Object)}.
    783     * <p>
    784     * Short hand for {@code Integer.toHexString(System.identityHashCode(object))}.
    785     * </p>
    786     *
    787     * @param object object for which the hashCode is to be calculated
    788     * @return Hash code in hexadecimal format.
    789     * @since 3.13.0
    790     */
    791    public static String identityHashCodeHex(final Object object) {
    792        return Integer.toHexString(System.identityHashCode(object));
    793    }
    794
    795    /**
    796     * Appends the toString that would be produced by {@link Object}
    797     * if a class did not override toString itself. {@code null}
    798     * will throw a NullPointerException for either of the two parameters.
    799     *
    800     * <pre>
    801     * ObjectUtils.identityToString(appendable, "")            = appendable.append("java.lang.String@1e23")
    802     * ObjectUtils.identityToString(appendable, Boolean.TRUE)  = appendable.append("java.lang.Boolean@7fa")
    803     * ObjectUtils.identityToString(appendable, Boolean.TRUE)  = appendable.append("java.lang.Boolean@7fa")
    804     * </pre>
    805     *
    806     * @param appendable  the appendable to append to
    807     * @param object  the object to create a toString for
    808     * @throws IOException if an I/O error occurs.
    809     * @since 3.2
    810     */
    811    public static void identityToString(final Appendable appendable, final Object object) throws IOException {
    812        Objects.requireNonNull(object, "object");
    813        appendable.append(object.getClass().getName())
    814              .append(AT_SIGN)
    815              .append(identityHashCodeHex(object));
    816    }
    817
    818    /**
    819     * Gets the toString that would be produced by {@link Object}
    820     * if a class did not override toString itself. {@code null}
    821     * will return {@code null}.
    822     *
    823     * <pre>
    824     * ObjectUtils.identityToString(null)         = null
    825     * ObjectUtils.identityToString("")           = "java.lang.String@1e23"
    826     * ObjectUtils.identityToString(Boolean.TRUE) = "java.lang.Boolean@7fa"
    827     * </pre>
    828     *
    829     * @param object  the object to create a toString for, may be
    830     *  {@code null}
    831     * @return the default toString text, or {@code null} if
    832     *  {@code null} passed in
    833     */
    834    public static String identityToString(final Object object) {
    835        if (object == null) {
    836            return null;
    837        }
    838        final String name = object.getClass().getName();
    839        final String hexString = identityHashCodeHex(object);
    840        final StringBuilder builder = new StringBuilder(name.length() + 1 + hexString.length());
    841        // @formatter:off
    842        builder.append(name)
    843              .append(AT_SIGN)
    844              .append(hexString);
    845        // @formatter:on
    846        return builder.toString();
    847    }
    848
    849    /**
    850     * Appends the toString that would be produced by {@link Object}
    851     * if a class did not override toString itself. {@code null}
    852     * will throw a NullPointerException for either of the two parameters.
    853     *
    854     * <pre>
    855     * ObjectUtils.identityToString(builder, "")            = builder.append("java.lang.String@1e23")
    856     * ObjectUtils.identityToString(builder, Boolean.TRUE)  = builder.append("java.lang.Boolean@7fa")
    857     * ObjectUtils.identityToString(builder, Boolean.TRUE)  = builder.append("java.lang.Boolean@7fa")
    858     * </pre>
    859     *
    860     * @param builder  the builder to append to
    861     * @param object  the object to create a toString for
    862     * @since 3.2
    863     * @deprecated as of 3.6, because StrBuilder was moved to commons-text,
    864     *  use one of the other {@code identityToString} methods instead
    865     */
    866    @Deprecated
    867    public static void identityToString(final StrBuilder builder, final Object object) {
    868        Objects.requireNonNull(object, "object");
    869        final String name = object.getClass().getName();
    870        final String hexString = identityHashCodeHex(object);
    871        builder.ensureCapacity(builder.length() +  name.length() + 1 + hexString.length());
    872        builder.append(name)
    873              .append(AT_SIGN)
    874              .append(hexString);
    875    }
    876
    877    /**
    878     * Appends the toString that would be produced by {@link Object}
    879     * if a class did not override toString itself. {@code null}
    880     * will throw a NullPointerException for either of the two parameters.
    881     *
    882     * <pre>
    883     * ObjectUtils.identityToString(buf, "")            = buf.append("java.lang.String@1e23")
    884     * ObjectUtils.identityToString(buf, Boolean.TRUE)  = buf.append("java.lang.Boolean@7fa")
    885     * ObjectUtils.identityToString(buf, Boolean.TRUE)  = buf.append("java.lang.Boolean@7fa")
    886     * </pre>
    887     *
    888     * @param buffer  the buffer to append to
    889     * @param object  the object to create a toString for
    890     * @since 2.4
    891     */
    892    public static void identityToString(final StringBuffer buffer, final Object object) {
    893        Objects.requireNonNull(object, "object");
    894        final String name = object.getClass().getName();
    895        final String hexString = identityHashCodeHex(object);
    896        buffer.ensureCapacity(buffer.length() + name.length() + 1 + hexString.length());
    897        buffer.append(name)
    898              .append(AT_SIGN)
    899              .append(hexString);
    900    }
    901
    902    /**
    903     * Appends the toString that would be produced by {@link Object}
    904     * if a class did not override toString itself. {@code null}
    905     * will throw a NullPointerException for either of the two parameters.
    906     *
    907     * <pre>
    908     * ObjectUtils.identityToString(builder, "")            = builder.append("java.lang.String@1e23")
    909     * ObjectUtils.identityToString(builder, Boolean.TRUE)  = builder.append("java.lang.Boolean@7fa")
    910     * ObjectUtils.identityToString(builder, Boolean.TRUE)  = builder.append("java.lang.Boolean@7fa")
    911     * </pre>
    912     *
    913     * @param builder  the builder to append to
    914     * @param object  the object to create a toString for
    915     * @since 3.2
    916     */
    917    public static void identityToString(final StringBuilder builder, final Object object) {
    918        Objects.requireNonNull(object, "object");
    919        final String name = object.getClass().getName();
    920        final String hexString = identityHashCodeHex(object);
    921        builder.ensureCapacity(builder.length() +  name.length() + 1 + hexString.length());
    922        builder.append(name)
    923              .append(AT_SIGN)
    924              .append(hexString);
    925    }
    926
    927    // Constants (LANG-816):
    928    /*
    929        These methods ensure constants are not inlined by javac.
    930        For example, typically a developer might declare a constant like so:
    931
    932            public final static int MAGIC_NUMBER = 5;
    933
    934        Should a different jar file refer to this, and the MAGIC_NUMBER
    935        is changed a later date (e.g., MAGIC_NUMBER = 6), the different jar
    936        file will need to recompile itself.  This is because javac
    937        typically inlines the primitive or String constant directly into
    938        the bytecode, and removes the reference to the MAGIC_NUMBER field.
    939
    940        To help the other jar (so that it does not need to recompile
    941        when constants are changed) the original developer can declare
    942        their constant using one of the CONST() utility methods, instead:
    943
    944            public final static int MAGIC_NUMBER = CONST(5);
    945     */
    946
    947    /**
    948     * Tests whether the given object is an Object array or a primitive array in a null-safe manner.
    949     *
    950     * <p>
    951     * A {@code null} {@code object} Object will return {@code false}.
    952     * </p>
    953     *
    954     * <pre>
    955     * ObjectUtils.isArray(null)             = false
    956     * ObjectUtils.isArray("")               = false
    957     * ObjectUtils.isArray("ab")             = false
    958     * ObjectUtils.isArray(new int[]{})      = true
    959     * ObjectUtils.isArray(new int[]{1,2,3}) = true
    960     * ObjectUtils.isArray(1234)             = false
    961     * </pre>
    962     *
    963     * @param object the object to check, may be {@code null}
    964     * @return {@code true} if the object is an {@code array}, {@code false} otherwise
    965     * @since 3.13.0
    966     */
    967    public static boolean isArray(final Object object) {
    968        return object != null && object.getClass().isArray();
    969    }
    970
    971    /**
    972     * Tests if an Object is empty or null.
    973     *
    974     * The following types are supported:
    975     * <ul>
    976     * <li>{@link CharSequence}: Considered empty if its length is zero.</li>
    977     * <li>{@link Array}: Considered empty if its length is zero.</li>
    978     * <li>{@link Collection}: Considered empty if it has zero elements.</li>
    979     * <li>{@link Map}: Considered empty if it has zero key-value mappings.</li>
    980     * <li>{@link Optional}: Considered empty if {@link Optional#isPresent} returns false, regardless of the "emptiness" of the contents.</li>
    981     * </ul>
    982     *
    983     * <pre>
    984     * ObjectUtils.isEmpty(null)             = true
    985     * ObjectUtils.isEmpty("")               = true
    986     * ObjectUtils.isEmpty("ab")             = false
    987     * ObjectUtils.isEmpty(new int[]{})      = true
    988     * ObjectUtils.isEmpty(new int[]{1,2,3}) = false
    989     * ObjectUtils.isEmpty(1234)             = false
    990     * ObjectUtils.isEmpty(1234)             = false
    991     * ObjectUtils.isEmpty(Optional.of(""))  = false
    992     * ObjectUtils.isEmpty(Optional.empty()) = true
    993     * </pre>
    994     *
    995     * @param object  the {@link Object} to test, may be {@code null}
    996     * @return {@code true} if the object has a supported type and is empty or null,
    997     * {@code false} otherwise
    998     * @since 3.9
    999     */
    1000    public static boolean isEmpty(final Object object) {
    1001        if (object == null) {
    1002            return true;
    1003        }
    1004        if (object instanceof CharSequence) {
    1005            return ((CharSequence) object).length() == 0;
    1006        }
    1007        if (isArray(object)) {
    1008            return Array.getLength(object) == 0;
    1009        }
    1010        if (object instanceof Collection<?>) {
    1011            return ((Collection<?>) object).isEmpty();
    1012        }
    1013        if (object instanceof Map<?, ?>) {
    1014            return ((Map<?, ?>) object).isEmpty();
    1015        }
    1016        if (object instanceof Optional<?>) {
    1017            // TODO Java 11 Use Optional#isEmpty()
    1018            return !((Optional<?>) object).isPresent();
    1019        }
    1020        return false;
    1021    }
    1022
    1023    /**
    1024     * Tests if an Object is not empty and not null.
    1025     *
    1026     * The following types are supported:
    1027     * <ul>
    1028     * <li>{@link CharSequence}: Considered empty if its length is zero.</li>
    1029     * <li>{@link Array}: Considered empty if its length is zero.</li>
    1030     * <li>{@link Collection}: Considered empty if it has zero elements.</li>
    1031     * <li>{@link Map}: Considered empty if it has zero key-value mappings.</li>
    1032     * <li>{@link Optional}: Considered empty if {@link Optional#isPresent} returns false, regardless of the "emptiness" of the contents.</li>
    1033     * </ul>
    1034     *
    1035     * <pre>
    1036     * ObjectUtils.isNotEmpty(null)             = false
    1037     * ObjectUtils.isNotEmpty("")               = false
    1038     * ObjectUtils.isNotEmpty("ab")             = true
    1039     * ObjectUtils.isNotEmpty(new int[]{})      = false
    1040     * ObjectUtils.isNotEmpty(new int[]{1,2,3}) = true
    1041     * ObjectUtils.isNotEmpty(1234)             = true
    1042     * ObjectUtils.isNotEmpty(Optional.of(""))  = true
    1043     * ObjectUtils.isNotEmpty(Optional.empty()) = false
    1044     * </pre>
    1045     *
    1046     * @param object  the {@link Object} to test, may be {@code null}
    1047     * @return {@code true} if the object has an unsupported type or is not empty
    1048     * and not null, {@code false} otherwise
    1049     * @since 3.9
    1050     */
    1051    public static boolean isNotEmpty(final Object object) {
    1052        return !isEmpty(object);
    1053    }
    1054
    1055    /**
    1056     * Null safe comparison of Comparables.
    1057     * <p>TODO Move to ComparableUtils.</p>
    1058     *
    1059     * @param <T> type of the values processed by this method
    1060     * @param values the set of comparable values, may be null
    1061     * @return
    1062     *  <ul>
    1063     *   <li>If any objects are non-null and unequal, the greater object.
    1064     *   <li>If all objects are non-null and equal, the first.
    1065     *   <li>If any of the comparables are null, the greater of the non-null objects.
    1066     *   <li>If all the comparables are null, null is returned.
    1067     *  </ul>
    1068     */
    1069    @SafeVarargs
    1070    public static <T extends Comparable<? super T>> T max(final T... values) {
    1071        T result = null;
    1072        if (values != null) {
    1073            for (final T value : values) {
    1074                if (compare(value, result, false) > 0) {
    1075                    result = value;
    1076                }
    1077            }
    1078        }
    1079        return result;
    1080    }
    1081
    1082    /**
    1083     * Find the "best guess" middle value among comparables. If there is an even
    1084     * number of total values, the lower of the two middle values will be returned.
    1085     * @param <T> type of values processed by this method
    1086     * @param comparator to use for comparisons
    1087     * @param items to compare
    1088     * @return T at middle position
    1089     * @throws NullPointerException if items or comparator is {@code null}
    1090     * @throws IllegalArgumentException if items is empty or contains {@code null} values
    1091     * @since 3.0.1
    1092     */
    1093    @SafeVarargs
    1094    public static <T> T median(final Comparator<T> comparator, final T... items) {
    1095        Validate.notEmpty(items, "null/empty items");
    1096        Validate.noNullElements(items);
    1097        Objects.requireNonNull(comparator, "comparator");
    1098        final TreeSet<T> treeSet = new TreeSet<>(comparator);
    1099        Collections.addAll(treeSet, items);
    1100        return (T) treeSet.toArray()[(treeSet.size() - 1) / 2];
    1101    }
    1102
    1103    /**
    1104     * Find the "best guess" middle value among comparables. If there is an even
    1105     * number of total values, the lower of the two middle values will be returned.
    1106     * @param <T> type of values processed by this method
    1107     * @param items to compare
    1108     * @return T at middle position
    1109     * @throws NullPointerException if items is {@code null}
    1110     * @throws IllegalArgumentException if items is empty or contains {@code null} values
    1111     * @since 3.0.1
    1112     */
    1113    @SafeVarargs
    1114    public static <T extends Comparable<? super T>> T median(final T... items) {
    1115        Validate.notEmpty(items);
    1116        Validate.noNullElements(items);
    1117        final TreeSet<T> sort = new TreeSet<>();
    1118        Collections.addAll(sort, items);
    1119        return (T) sort.toArray()[(sort.size() - 1) / 2];
    1120    }
    1121
    1122    /**
    1123     * Null safe comparison of Comparables.
    1124     * <p>TODO Move to ComparableUtils.</p>
    1125     *
    1126     * @param <T> type of the values processed by this method
    1127     * @param values the set of comparable values, may be null
    1128     * @return
    1129     *  <ul>
    1130     *   <li>If any objects are non-null and unequal, the lesser object.
    1131     *   <li>If all objects are non-null and equal, the first.
    1132     *   <li>If any of the comparables are null, the lesser of the non-null objects.
    1133     *   <li>If all the comparables are null, null is returned.
    1134     *  </ul>
    1135     */
    1136    @SafeVarargs
    1137    public static <T extends Comparable<? super T>> T min(final T... values) {
    1138        T result = null;
    1139        if (values != null) {
    1140            for (final T value : values) {
    1141                if (compare(value, result, true) < 0) {
    1142                    result = value;
    1143                }
    1144            }
    1145        }
    1146        return result;
    1147    }
    1148
    1149    /**
    1150     * Find the most frequently occurring item.
    1151     *
    1152     * @param <T> type of values processed by this method
    1153     * @param items to check
    1154     * @return most populous T, {@code null} if non-unique or no items supplied
    1155     * @since 3.0.1
    1156     */
    1157    @SafeVarargs
    1158    public static <T> T mode(final T... items) {
    1159        if (ArrayUtils.isNotEmpty(items)) {
    1160            final HashMap<T, MutableInt> occurrences = new HashMap<>(items.length);
    1161            for (final T t : items) {
    1162                final MutableInt count = occurrences.get(t);
    1163                if (count == null) {
    1164                    occurrences.put(t, new MutableInt(1));
    1165                } else {
    1166                    count.increment();
    1167                }
    1168            }
    1169            T result = null;
    1170            int max = 0;
    1171            for (final Map.Entry<T, MutableInt> e : occurrences.entrySet()) {
    1172                final int cmp = e.getValue().intValue();
    1173                if (cmp == max) {
    1174                    result = null;
    1175                } else if (cmp > max) {
    1176                    max = cmp;
    1177                    result = e.getKey();
    1178                }
    1179            }
    1180            return result;
    1181        }
    1182        return null;
    1183    }
    1184
    1185    /**
    1186     * Compares two objects for inequality, where either one or both
    1187     * objects may be {@code null}.
    1188     *
    1189     * <pre>
    1190     * ObjectUtils.notEqual(null, null)                  = false
    1191     * ObjectUtils.notEqual(null, "")                    = true
    1192     * ObjectUtils.notEqual("", null)                    = true
    1193     * ObjectUtils.notEqual("", "")                      = false
    1194     * ObjectUtils.notEqual(Boolean.TRUE, null)          = true
    1195     * ObjectUtils.notEqual(Boolean.TRUE, "true")        = true
    1196     * ObjectUtils.notEqual(Boolean.TRUE, Boolean.TRUE)  = false
    1197     * ObjectUtils.notEqual(Boolean.TRUE, Boolean.FALSE) = true
    1198     * </pre>
    1199     *
    1200     * @param object1  the first object, may be {@code null}
    1201     * @param object2  the second object, may be {@code null}
    1202     * @return {@code false} if the values of both objects are the same
    1203     */
    1204    public static boolean notEqual(final Object object1, final Object object2) {
    1205        return !Objects.equals(object1, object2);
    1206    }
    1207
    1208    /**
    1209     * Checks that the specified object reference is not {@code null} or empty per {@link #isEmpty(Object)}. Use this
    1210     * method for validation, for example:
    1211     *
    1212     * <blockquote>
    1213     *
    1214     * <pre>
    1215     * public Foo(Bar bar) {
    1216     *     this.bar = Objects.requireNonEmpty(bar);
    1217     * }
    1218     * </pre>
    1219     *
    1220     * </blockquote>
    1221     *
    1222     * @param <T> the type of the reference.
    1223     * @param obj the object reference to check for nullity.
    1224     * @return {@code obj} if not {@code null}.
    1225     * @throws NullPointerException     if {@code obj} is {@code null}.
    1226     * @throws IllegalArgumentException if {@code obj} is empty per {@link #isEmpty(Object)}.
    1227     * @see #isEmpty(Object)
    1228     * @since 3.12.0
    1229     */
    1230    public static <T> T  requireNonEmpty(final T obj) {
    1231        return requireNonEmpty(obj, "object");
    1232    }
    1233
    1234    /**
    1235     * Checks that the specified object reference is not {@code null} or empty per {@link #isEmpty(Object)}. Use this
    1236     * method for validation, for example:
    1237     *
    1238     * <blockquote>
    1239     *
    1240     * <pre>
    1241     * public Foo(Bar bar) {
    1242     *     this.bar = Objects.requireNonEmpty(bar, "bar");
    1243     * }
    1244     * </pre>
    1245     *
    1246     * </blockquote>
    1247     *
    1248     * @param <T> the type of the reference.
    1249     * @param obj the object reference to check for nullity.
    1250     * @param message the exception message.
    1251     * @return {@code obj} if not {@code null}.
    1252     * @throws NullPointerException     if {@code obj} is {@code null}.
    1253     * @throws IllegalArgumentException if {@code obj} is empty per {@link #isEmpty(Object)}.
    1254     * @see #isEmpty(Object)
    1255     * @since 3.12.0
    1256     */
    1257    public static <T> T requireNonEmpty(final T obj, final String message) {
    1258        // check for null first to give the most precise exception.
    1259        Objects.requireNonNull(obj, message);
    1260        if (isEmpty(obj)) {
    1261            throw new IllegalArgumentException(message);
    1262        }
    1263        return obj;
    1264    }
    1265
    1266    /**
    1267     * Gets the {@code toString} of an {@link Object} returning
    1268     * an empty string ("") if {@code null} input.
    1269     *
    1270     * <pre>
    1271     * ObjectUtils.toString(null)         = ""
    1272     * ObjectUtils.toString("")           = ""
    1273     * ObjectUtils.toString("bat")        = "bat"
    1274     * ObjectUtils.toString(Boolean.TRUE) = "true"
    1275     * </pre>
    1276     *
    1277     * @see Objects#toString(Object)
    1278     * @see Objects#toString(Object, String)
    1279     * @see StringUtils#defaultString(String)
    1280     * @see String#valueOf(Object)
    1281     * @param obj  the Object to {@code toString}, may be null
    1282     * @return the passed in Object's toString, or {@code ""} if {@code null} input
    1283     * @since 2.0
    1284     * @deprecated this method has been replaced by {@code java.util.Objects.toString(Object)} in Java 7 and will be
    1285     * removed in future releases. Note however that said method will return "null" for null references, while this
    1286     * method returns an empty String. To preserve behavior use {@code java.util.Objects.toString(myObject, "")}
    1287     */
    1288    @Deprecated
    1289    public static String toString(final Object obj) {
    1290        return Objects.toString(obj, StringUtils.EMPTY);
    1291    }
    1292
    1293    /**
    1294     * Gets the {@code toString} of an {@link Object} returning
    1295     * a specified text if {@code null} input.
    1296     *
    1297     * <pre>
    1298     * ObjectUtils.toString(null, null)           = null
    1299     * ObjectUtils.toString(null, "null")         = "null"
    1300     * ObjectUtils.toString("", "null")           = ""
    1301     * ObjectUtils.toString("bat", "null")        = "bat"
    1302     * ObjectUtils.toString(Boolean.TRUE, "null") = "true"
    1303     * </pre>
    1304     *
    1305     * @see Objects#toString(Object)
    1306     * @see Objects#toString(Object, String)
    1307     * @see StringUtils#defaultString(String,String)
    1308     * @see String#valueOf(Object)
    1309     * @param obj  the Object to {@code toString}, may be null
    1310     * @param nullStr  the String to return if {@code null} input, may be null
    1311     * @return the passed in Object's toString, or {@code nullStr} if {@code null} input
    1312     * @since 2.0
    1313     * @deprecated this method has been replaced by {@code java.util.Objects.toString(Object, String)} in Java 7 and
    1314     * will be removed in future releases.
    1315     */
    1316    @Deprecated
    1317    public static String toString(final Object obj, final String nullStr) {
    1318        return Objects.toString(obj, nullStr);
    1319    }
    1320
    1321    /**
    1322     * Gets the {@code toString} of an {@link Supplier}'s {@link Supplier#get()} returning
    1323     * a specified text if {@code null} input.
    1324     *
    1325     * <pre>
    1326     * ObjectUtils.toString(() -&gt; obj, () -&gt; expensive())
    1327     * </pre>
    1328     * <pre>
    1329     * ObjectUtils.toString(() -&gt; null, () -&gt; expensive())         = result of expensive()
    1330     * ObjectUtils.toString(() -&gt; null, () -&gt; expensive())         = result of expensive()
    1331     * ObjectUtils.toString(() -&gt; "", () -&gt; expensive())           = ""
    1332     * ObjectUtils.toString(() -&gt; "bat", () -&gt; expensive())        = "bat"
    1333     * ObjectUtils.toString(() -&gt; Boolean.TRUE, () -&gt; expensive()) = "true"
    1334     * </pre>
    1335     *
    1336     * @param obj  the Object to {@code toString}, may be null
    1337     * @param supplier  the Supplier of String used on {@code null} input, may be null
    1338     * @return the passed in Object's toString, or {@code nullStr} if {@code null} input
    1339     * @since 3.14.0
    1340     */
    1341    public static String toString(final Supplier<Object> obj, final Supplier<String> supplier) {
    1342        return obj == null ? Suppliers.get(supplier) : toString(obj.get(), supplier);
    1343    }
    1344
    1345    /**
    1346     * Gets the {@code toString} of an {@link Object} returning
    1347     * a specified text if {@code null} input.
    1348     *
    1349     * <pre>
    1350     * ObjectUtils.toString(obj, () -&gt; expensive())
    1351     * </pre>
    1352     * <pre>
    1353     * ObjectUtils.toString(null, () -&gt; expensive())         = result of expensive()
    1354     * ObjectUtils.toString(null, () -&gt; expensive())         = result of expensive()
    1355     * ObjectUtils.toString("", () -&gt; expensive())           = ""
    1356     * ObjectUtils.toString("bat", () -&gt; expensive())        = "bat"
    1357     * ObjectUtils.toString(Boolean.TRUE, () -&gt; expensive()) = "true"
    1358     * </pre>
    1359     *
    1360     * @param <T> the obj type (used to provide better source compatibility in 3.14.0).
    1361     * @param obj  the Object to {@code toString}, may be null
    1362     * @param supplier  the Supplier of String used on {@code null} input, may be null
    1363     * @return the passed in Object's toString, or {@code nullStr} if {@code null} input
    1364     * @since 3.11
    1365     */
    1366    public static <T> String toString(final T obj, final Supplier<String> supplier) {
    1367        return obj == null ? Suppliers.get(supplier) : obj.toString();
    1368    }
    1369
    1370    /**
    1371     * Calls {@link Object#wait(long, int)} for the given Duration.
    1372     *
    1373     * @param obj The receiver of the wait call.
    1374     * @param duration How long to wait.
    1375     * @throws IllegalArgumentException if the timeout duration is negative.
    1376     * @throws IllegalMonitorStateException if the current thread is not the owner of the {@code obj}'s monitor.
    1377     * @throws InterruptedException if any thread interrupted the current thread before or while the current thread was
    1378     *         waiting for a notification. The <em>interrupted status</em> of the current thread is cleared when this
    1379     *         exception is thrown.
    1380     * @see Object#wait(long, int)
    1381     * @since 3.12.0
    1382     */
    1383    public static void wait(final Object obj, final Duration duration) throws InterruptedException {
    1384        DurationUtils.accept(obj::wait, DurationUtils.zeroIfNull(duration));
    1385    }
    1386
    1387    /**
    1388     * {@link ObjectUtils} instances should NOT be constructed in
    1389     * standard programming. Instead, the static methods on the class should
    1390     * be used, such as {@code ObjectUtils.defaultIfNull("a","b");}.
    1391     *
    1392     * <p>This constructor is public to permit tools that require a JavaBean
    1393     * instance to operate.</p>
    1394     *
    1395     * @deprecated TODO Make private in 4.0.
    1396     */
    1397    @Deprecated
    1398    public ObjectUtils() {
    1399        // empty
    1400    }
    1401
    1402}