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